[mapserver-users] Mapserver docs and i18n
thomas bonfort
thomas.bonfort at gmail.com
Wed Jul 4 06:46:14 PDT 2012
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 ?
>
> 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 ?
>
> 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 ?
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
>
More information about the mapserver-users
mailing list