[mapserver-users] Mapserver docs and i18n
Lime, Steve D (DNR)
Steve.Lime at state.mn.us
Tue Jul 10 08:46:47 PDT 2012
What's the status on this one? I see the pull request is still open. Not sure how this impacts branch-6-2 or the master...
Steve
-----Original Message-----
From: mapserver-users-bounces at lists.osgeo.org [mailto:mapserver-users-bounces at lists.osgeo.org] On Behalf Of Yves Jacolin (Free)
Sent: Thursday, July 05, 2012 3:43 AM
To: mapserver-users at lists.osgeo.org
Subject: Re: [mapserver-users] Mapserver docs and i18n
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-ig
> nored- 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
_______________________________________________
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