Migrating existing documentation translation to g-d-u
Now, you see a module on http://l10n.gnome.org/module/, and you know there is a translation for your language in SVN, yet it doesn't show up. What's up?
Well, your translation is probably old-style, non-gnome-doc-utils-using documentation, which you want to switch to g-d-u style (i.e. a single PO file). Why do you want that? Because it will make it easier for you to update and track changes, and you'll get status pages for free. Good enough?
Preparation
For this, you need gnome-doc-utils and xml2po. Always try to use latest version to avoid any bugs which might already be fixed. Recent versions of xml2po support "-r" ("--reuse") option, which can make use of existing translation to build a translated PO file.
Next, you want to have exact original of a document on which translation is based. This is not necessary, but if you actually want good results, you'll try to get the exact same revision (looking at dates of SVN commits, ChangeLog entries and revision info in the document itself should help). This is important because xml2po can work its magic only if the structure of the document is the same.
Also note that you may need to remove additions you added to a translation (such as <copyright> or credits section for the translator), in order to get exact same structure of a document.
Example
I'm going to describe switching Spanish Clock applet documentation inside gnome-panel.
I first looked at gnome-panel/help/es/clock/clock.xml and noticed that it seems based on September 2003, 2.4 manual revision. I've checked that at
and found out that this was checked in around January 2004. So, we're looking for base version dated somewhere in between. Looking at
it seems there's only one choice: revision 1.18. So, lets check that out and use it as base original translation (or you can download it right there). I'm naming it base.xml, and keeping the Spanish translation in clock.xml.
First, I need to check the validity of the translation. xmllint -valid clock.xml lets me know that everything is fine, so I remove any translator references in it (I know these are not in the original), and try out a first run:
xml2po -r clock.xml base.xml |less
I notice that all the messages are somewhat skewed after a certain point. After a bit of comparing the files, I see that one entire <revision> section is missing, and add that back to translation. Now, everything seems fine all the way to the end, so that's it. I do:
xml2po -o es.po -r clock.xml base.xml
and edit es.po removing any duplicate entries (xml2po can't do that automatically yet, because it can't know which one you'd want to keep). Alternatively, you can use msguniq to remove duplicates automatically.
legal.xml is simpler, since it hasn't changed for a long time. I simply do
xml2po -o es.legal.po -r legal.xml ../../C/clock/legal.xml
and msgcat that together with fixed-up es.po to get a final translation:
msgcat -o es.final.po --use-first es.po es.legal.po
Now, I put es.final.po into gnome-panel/help/clock/es/es.po (cvs adding directory and file as I go), and move all the figures (one in this example) from help/es/clock/figures/ to help/clock/es/figures/ (cvs adding these as well).
Add "es" to help/clock/Makefile.am DOC_LINGUAS variable, write a ChangeLog entry, and we're good to go.
Notes
The hardest part is actually getting translated and untranslated XML file of the same structure. If you do that, and have other problems, feel free to drop by #docs or #i18n on irc.gnome.org and ask for help.
Back to GnomeDocUtilsMigration page.