Talk:Documentation translation

Ideas for Improving the Translation Process

Please don't hesitate to add, improve and criticise this article. Edit mercilessly :)

PO files are very well-established in the Free Software translator community, so using them for as many documentation files as we can will get probably us the most translations. PO tools are also good at merging updates. When translating XML files directly, beginners will just do it in a regular editor and make mistakes when a new english tutorial arrives (this has happened at least in some German tutorials).

In addition to what's written above, xml2po can not only be used for converting the tutorial XML files themselves, but can also extract translatable content from the SVG illustrations, for example:

 xml2po --output=tutorial-advanced.pot tutorial-advanced.xml advanced-f[0-9][0-9].svg

Extracting the single XML and SVG files from the PO file requires several calls to xml2po (thus should be scripted):

 xml2po --po-file=de.po tutorial-advanced.xml > de.tmp/tutorial-advanced.xml
 xml2po --po-file=de.po advanced-f01.svg > de.tmp/advanced-f01.svg
 xml2po --po-file=de.po advanced-f02.svg > de.tmp/advanced-f02.svg
 ...
 

This way, we don't even need the translated illustration files in SVN but can generate them on the fly (ScislaC came up with that idea on IRC).

http://cvs.gnome.org/viewcvs/gnome-doc-utils/gnome-doc-utils.make has a Makefile for intelligently handling xml2po and friends, but it is quite complicated. Maybe we could even think about following the route described here: http://live.gnome.org/GnomeDocUtilsMigrationHowTo

Work is done on Embedded Help which also must be integrated.

If we use the msgid "translator-credits" from all the PO files (GUI and tutorials etc.), we can collect them for use in the about box to only show the translators for the language that the GUI is currently in (idea by kaeso on IRC).

Also note that ScislaC (Joshua Andler <scislac at users dot sf dot net>) has a plan to re-arrange the tutorials and sort them in a deeper hierarchy, so we should wait with whatever we do until that is done.

ACSpike said on IRC that he thinks about setting up a build server for documentation (that can convert the XML files to SVG/HTML etc.)

vHalenbach:I find that a good idea too. When all translatable content is in the PO-format it is even possible to establish a Webinterface like the translators of debian and the game wesnoth have. In this interface it is easily to see for everyone how the translation is progressing. Maybe it is open source and we can borrow that from them. I discussed it with Matiphas on IRC a bit.