[mapserver-users] Mapserver docs and i18n

Tue Jul 3 13:13:05 PDT 2012

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.

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.

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)

Sorry for the long "monologue"

Any reactions welcome

Regards

ThomasG
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/mapserver-users/attachments/20120703/5f3e6d83/attachment.html>