[mapserver-users] Mapserver docs and i18n
Thomas Gratier
osgeo.mailinglist at gmail.com
Wed Jul 4 12:51:03 PDT 2012
Hello,
My answer are inline with bold cross *XXXXXXXXXXXXXX* just before (for mail
in html)
Uline of inline of inline start to be difficult to read ;)
Regards
ThomasG77
2012/7/4 thomas bonfort <thomas.bonfort at gmail.com>
> Hi Thomas,
>
> I'm all for simplifying the translation workflow. I tend to dislike
> the current one we have setup because it is difficult for translators
> to keep track of what has been added/modified in the english version,
> resulting in outdated translated docs which in my opinion is worse
> than having no translation at all.
>
> More inline...
>
> On Tue, Jul 3, 2012 at 10:13 PM, Thomas Gratier
> <osgeo.mailinglist at gmail.com> wrote:
> > Hello Jeff, hello all,
> >
> > # First think to understand
> >
> > I praise the Mapserver community and the team behind the engine.
> > I'm a big fan of Mapserver and Sphinx and I've always love the really
> great
> > documentation but I know people who deal only with there native language
> to
> > do the job. So translation is a core part of a project to extend
> popularity
> > accross countries (althought Mapserver popularity is already established)
> >
> > My motivation is to deal with the french translation with i18n and not
> with
> > RST.
> > I want to make think better, the way we do it is good but can be improve.
> > Why? Some thoughts to explain below
> >
> >
> > # Advantages
> >
> > 1. Fulfillment
> >
> > Really important for me because a community is based on humans who search
> > small and big achievements and it's more easy with i18n to measure the
> job.
> >
> > Imagine one rst file of 1000 lines (around 100 lines of empty lines or
> > special rst declarations)
> >
> > You generate is equivalent in pot file.
> > The number of string to translate is 430
> >
> > Offline:
> > Step by step you see what you've done and can by example, see that you've
> > done 86 lines so, 20% of the job is done for the file.
> > Your objective to go until 30%. When you reach it, you're happy. You've
> done
> > 10% more of the file translation.
> >
> > Online:
> > See this online app based on pottle for the Qgis community. You can see
> the
> > http://translate.qgis.org/fr/qgis-user-guide/ example.
> > In this case, you can make a survey of users who contribute, you can
> review
> > with others, you now if a file translation is completed. You can
> distribute
> > task between the community of users and not only of advanced users /
> > developpers.
> >
> > You can have a dedicated community of translators who care about content
> and
> > not about the way to use sphinx and others technical things.
> >
> > 2. Separate presentation from contents
> >
> > When you generate pot files, the string length is quite short. You don't
> > have to care too much about rst indent : you will not break anything.
> > If the presentation change, you content don't. I'm thinking about the
> annual
> > change for FOSS4G image. You have to backport it manually with a merge in
> > every langage version.
> >
> > 3. History and maintainability
> >
> > ## The typical workflow now
> >
> > You cut and paste a rst file and you make the translation. Ok it's nice!!
> > Why does I need to care about i18n? This guy is crazy!!
> >
> > Because now imagine, you've done the translation 3 years ago (your
> community
> > said "do it" and it was done).
> >
> > The content was in english (the letter are use to represent a block of
> > content in master version and number for content of translated example)
> >
> > In the past
> >
> > English French
> >
> > AAAAAAAAA 1111111
> > BBBBBBBBB 222222
> > CCCCCCCCC 333333
> > DDDDDDDDD 444444
> > EEEEEEEEE 555555
> > GGGGGGGG 777777
> > HHHHHHHHH 888888
> >
> > Nowadays
> >
> > BBBBBBBBB ??????
> > CCCCCCCCC ??????
> > DDDDDDDDD ??????
> > FFFFFFFFFF ??????
> > GGGGGGGG ??????
> > HHHHHHHHH ??????
> >
> > The way you do if you kept during three years the file you use to
> translate
> > the original
> >
> > Compare both english version
> >
> > AAAAAAAAA dissapear
> > BBBBBBBBB seems to stay the same (BBBBBBBBB is a block so are you sure
> there
> > no typo fixed?)
> > CCCCCCCCC is the same
> > DDDDDDDDD is the same
> > EEEEEEEEE dissapear
> > FFFFFFFFFF appear
> > GGGGGGGG is the same
> > HHHHHHHHH is the same
> >
> > Now find in the french file the corresponding
> >
> > I now AAAAAAAAA dissapear in english so let's go delete it in the french
> > version
> >
> > Find the equivalent in french of AAAAAAAAA (where it begins and finish)
> and
> > delete it
> > Find BBBBBBBBB block in english and see what was the french string
> > corresponding and replace now
> > Do the same for CCCCCCCCC, DDDDDDDDD
> > EEEEEEEEE dissapear so where is french equivalent (more difficult to find
> > where it begins and finish) to delete
> > FFFFFFFFFF appear so translate
> > Find GGGGGGGGG block in english and see what was the french string
> > corresponding and replace now.
> > Do the same for HHHHHHHHH.
> >
> > You get at the end the result. You just do a semantic three way merge
> > manually (and I haven't imagine a case where there was reordering of
> content
> > or small string fix)
> >
> > BBBBBBBBB 222222
> > CCCCCCCCC 333333
> > DDDDDDDDD 444444
> > FFFFFFFFFF 666666
> > GGGGGGGG 777777
> > HHHHHHHHH 888888
> >
> > ## I18N workflow
> >
> > First translation
> >
> > English French
> >
> > AAAAAAAAA 111111
> > BBBBBBBBB 222222
> > CCCCCCCCC 333333
> > DDDDDDDDD 444444
> > EEEEEEEEE 555555
> > GGGGGGGG 777777
> > HHHHHHHHH 888888
> >
> > In the future, (if community change nothing)
> >
> > BBBBBBBBB ??????
> > CCCCCCCCC ??????
> > DDDDDDDDD ??????
> > FFFFFFFFFF ??????
> > GGGGGGGG ??????
> > HHHHHHHHH ??????
> >
> > The way how msgmerge or manual poedit merge do
> >
> > Open the translated file at a time (po file), open the newly pot file and
> > say merge.
> >
> > What happen,
> > the block AAAAAAAAA match nothing compare to before so comment in the po
> > file
> > BBBBBBBBB block match, keep it.
> > CCCCCCCCC block match, keep it.
> > DDDDDDDDD block match, keep it.
> > The block EEEEEEEEE match nothing compare to before so comment in the po
> > file
> > FFFFFFFFFF match nothing but wasn't there ,so add it
> > GGGGGGGG block match, keep it.
> > HHHHHHHHH block match, keep it.
> >
> > The UI like poedit or pootle tell you, you only have to translate
> FFFFFFFFF,
> > the three way merge is mostly done automatically.
> > That the only job. Quite nice compare to before
> >
> > You foreign (not english) language is more easily updated like that and
> > small change are easy to see.
> >
> > # Drawbacks
> >
> > 1. Less flexibility because, the workflow to be in the core doc
> repository
> > is to ask to integrate change in the english version (master version) and
> > after, you backport everything in every langage.
>
> I don't understand how this is different from the current workflow
> where the english docs are updated and the translator maintainers have
> to backport to their language, can you elaborate please ?
>
*XXXXXXXXXXXXXX*
I was thinking that in some case, community have push for their language in
first and after backport this contribution to english. I'm not aware of
complete history but I was thinking that the part
http://www.mapserver.org/mapfile/symbology/construction.html was created in
German and after translated in English. I've maybe made a mistake and it
never happens like that.
> >
> > 2. Some content are outside of the i18n parsing with sphinx.
> > When you generate i18n strings, see also directive or caption (for
> legend of
> > image) are not parsed. So you must refactor a bit the syntax for image
> > caption to put the legend outside. The same for see also.
>
> can you give an example of such a change ?
>
>
*XXXXXXXXXXXXXX*
.. figure:: picture.png
:scale: 50 %
:alt: map to buried treasure
This is the caption of the figure (a simple paragraph).
The legend consists of all elements after the caption. In this
case, the legend consists of this paragraph and the following
table:
Have to be transformated to
.. figure:: picture.png
:scale: 50 %
:alt: map to buried treasure
This is the caption of the figure (a simple paragraph).
The legend consists of all elements after the caption. In this
case, the legend consists of this paragraph and the following
table:
For the see also case, I haven't found better than putting content outside
of a directive like that and use bold for example to change font style.
I've also open a bug/enhancement ticket on sphinx tracker e.g
https://bitbucket.org/birkenfeld/sphinx/issue/960/directive-seelaso-ignored-in-the-gettextbecause
this missing/bug feature is quite annoying (althougth it can be
acceptable because most "seealso" rst directive are only link references)
An RST "guru" have maybe a better alternative than that.
> >
> > 3. Need to add more explicit links in original doc
> > Example for the glossary :ref:`gis` must be replace with :ref:`gis
> <gis>`__
> > because not helpful for translators not aware of sphinx syntax (the
> problem
> > is already the same nowadays)
>
> I don't think this is a big issue. Doc writers will need to adapt, but
> I know that that my habit is to copy what's already present in the
> code so it won't be a problem if you fix the current refs once and for
> all.
>
>
> Aside from these 3 limitations, it is my understanding that the
> workflow for contributing to the original english docs will be
> unchanged (i.e. we will keep directly modifying the en/*.rst files),
> am I correct ?
>
*XXXXXXXXXXXXXX*
Yes, workflow will not changed. English is in pure rst and stay like that.
Each community can make choice depending on their preferences.
For the moment, we're looping throught variable TRANSLATIONS = de es fr
Imagine the french community choose to make the move to i18n just have to
make change below
TRANSLATIONS = de es
TRANSLATIONI18N = fr
So German community or Spanish one are not impacted and they can switch or
not (I've just added a loop for dealing with TRANSLATIONI18N)
That why I've said I haven't reinvented the wheel because I respect both
old way of doing and maybe future i18n way.
>
> Provided the answer to the previous question was "yes", and that the
> updated method does not disrupt the other languages (for now at
> least), I would be ok for the change.
>
> cheers,
> thomas
>
> >
> > Sorry for the long "monologue"
> >
> > Any reactions welcome
> >
> > Regards
> >
> > ThomasG
> >
> > _______________________________________________
> > mapserver-users mailing list
> > mapserver-users at lists.osgeo.org
> > http://lists.osgeo.org/mailman/listinfo/mapserver-users
> >
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/mapserver-users/attachments/20120704/4c957cb7/attachment.html>
More information about the mapserver-users
mailing list