[mapserver-users] Mapserver docs and i18n
Yves Jacolin (Free)
yjacolin at free.fr
Thu Jul 5 01:42:57 PDT 2012
Hello,
I am now ok with this pull request from Thomas (we discussed on Francophone
mailing list also).
It could improve contribution from non technical user (if a pootle
infrastructure exists, unfortunately which add more work for sysadmin).
Y.
Le mercredi 4 juillet 2012 21:51:03 Thomas Gratier a écrit :
> 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
More information about the mapserver-users
mailing list