librelist archives

Re: [flask] How to translate the documentation ?

From:

Stephane Wirtel

Date:

2010-07-28 @ 12:22

On 07/28/2010 02:01 PM, DasIch wrote:
> In order to translate documentations written in Sphinx you currently
> have to simply copy the existing one and translate each document by
> hand. Obviously this way doesn't provide you with any notifications.
> 
> However there is a GSoC Sphinx project which will bring translations to
> Sphinx by generating PO files it can read from, to translate the
> documentation. Once this is finished it should be possible to easily
> translate documentations.
> 
Not agree with you (or I didn't understand the idea), because if you use a
generated .po file
and if you have a change in your original text, all translations will be lost.

Now, if you notify the translators we have changed just one word in this 
original paragraph,
you will avoid to translate a new text.

If we use the .po files, the original text is the key for the translation process.
For a software it's ok because you translate some words or expression 
("Open" -> "Ouvrir", ...)
but in the case of a documentation, I don't know it's efficient

With gettext, the key is the original sentence. If you change this 
sentence, the key is deprecated
and the translation too.

However, we can define a specific identifier for each paragraph in the 
.rst documentation and use it
to help the translation process but this practice is intrusive.

Do you have an other suggestion ?

Regards,

Stéphane

Tracking changes is difficult however our approach will be to use the
doctree (the ast generated by docutils) of each document and add ids to
each node. Once such a doctree is generated a new doctree will be merged
with the previous one so that the ids remain even for nodes which
changed content e.g. paragraphs.

We will probably have to talk with the guys of the pootle project to see
which format to use or how to modify PO. Pootle is supposed to be used
at least for docs.python.org, currently there is a beta instance running
on http://pootle.python.org

On 07/28/2010 02:42 PM, DasIch wrote:
> Tracking changes is difficult however our approach will be to use the
> doctree (the ast generated by docutils) of each document and add ids to
> each node. Once such a doctree is generated a new doctree will be merged
> with the previous one so that the ids remain even for nodes which
> changed content e.g. paragraphs.
Agree with you, I thought to this solution.

Great !
> 
> We will probably have to talk with the guys of the pootle project to see
> which format to use or how to modify PO. Pootle is supposed to be used
> at least for docs.python.org, currently there is a beta instance running
> on http://pootle.python.org
> 

Hi,

Le 28/07/2010 14:22, Stephane Wirtel a écrit :
> If we use the .po files, the original text is the key for the 
translation process.
> For a software it's ok because you translate some words or expression 
("Open" ->  "Ouvrir", ...)
> but in the case of a documentation, I don't know it's efficient
>
> With gettext, the key is the original sentence. If you change this 
sentence, the key is deprecated
> and the translation too.
>    

That project (see http://gsoc.robertlehmann.de/ and 
http://pootle.python.org/) is for Sphinx. It’s already translating the 
Python documentation which is made of big paragraphs too.
I’d be surprised if they had no solution for this problem.

Regards,
-- 
Simon Sapin