Re: Doc Translations

[danilo gnome org (Danilo Åegan)]

Hi Kurt,

Today at 2:43, Kurt Maute wrote:

> I maintain the Planner User Guide.  So far we've got a translation in
> Spanish - basically a straight copy of the original xml file with the
> content translated.  I'm looking for someone to point me in the
> direction of the current wisdom on maintaining translated files.  I saw
> on the gnome-doc-list several discussions on using po files for this,
> but no real indication of whether this is one of many ways or even the
> accepted best practice.
>
> Could someone point me in the right direction?

I'll try to do that, since I'm the current developer of xml2po
(which means I'm biased, but that's a good thing, no?).

  Retrospect.

Shaun (maintainer of Yelp, Gnome help browser) has planned on getting
entire new build system and stylesheets working for next release of
Gnome. I have chipped in with my xml2po into that plan, and it should
become default for documentation translation in some of the following
releases, hopefully whichever comes first after 2.8.

All of our work is available in gnome-doc-utils, albeit it's not yet
integrated to the extent I'd like it to be.

I'm at fault for not working fast enough on xml2po, but I hope that
will change soon.

  Self-promotion (or why should you use xml2po).

xml2po is result of what I consider best practice for translations.
FWIW, I'm a translator myself, so perhaps I know what I'm doing
(though, that's very questionable :).  PO file format has many
advantages over straight XML for translations.  xml2po leverages
those advantages especially if you start doing your translations from
scratch in PO file format.

Your first usage of xml2po would probably amount to something like:

  xml2po C/planner-manual.xml > planner-manual.pot
  cp planner-manual.pot es.po

Now, edit es.po, and add Spanish translations.  Finally, you merge
your translations back:

  xml2po -p es.po -o es/planner-manual.xml C/planner-manual.xml

Next time C/planner-manual.xml changes, you'd sync (gettextism is
"merge") your es.po first:

  xml2po -u es.po C/planner-manual.xml

Now, you update translations in es.po, and merge them back in the
same way as before (of course, don't forget to check es.po with
"msgfmt -cv -o /dev/null es.po" or you may get errors):

  xml2po -p es.po -o es/planner-manual.xml C/planner-manual.xml


OTOH, you said that you already have Spanish translation in XML
format.  xml2po can help there as well (this is fairly untested
feature as of yet, but it should work sanely if you're careful with
what you pass to it).  Try to get exactly the same revisions of both
translated and untranslated manual (i.e. Spanish and English), so
they would both have the same structure.  Remove any tags added in
translation (such as copyright notice about translators), so document
structure would be exactly the same for two documents.  Then, run
xml2po like this:

  xml2po -o es.po -r es/planner-manual.xml C/planner-manual.xml

It should give you a reasonable PO file which you can continue using
as above.  If messages are shifted by a certain number, it means
structure is not really the same, so you should probably add a couple
of tags in one document as to compensate for the shift.  In the
future, I plan to add an option for offsetting messages via the
command line.

Another drawback of xml2po is that it cannot cope with some fancy
usage of XML entities (eg. entities are declared in one, toplevel
file, but used in another; I can solve this easily if I sacrifice
ability to merge file-by-file, and simply output entire translation
into one XML file, and Python libxml2 bindings would probably need
some extensions to allow for the proper fix).


  Future.

Future is uncertain, but you already knew that.  Global warming is
creating more and more problems for humanity, yet my guess is we'll
learn to live with that.  This means many unknowns in the future of
Gnome in general, and Gnome Translation Project in particular :-)

Nobody warrants that PO file will be used for translations, but you
benefit in more than one way if you use them: you can get XML file at
any time (except if there're bugs; if there are, I'd like reports
about them) so you're no worse than you're now, you'd probably be able
to easily convert to any format that actually gets used, and to do
that programmaticaly, and it's way easier to keep track of changes
with PO files and to update your translations.  Just ask translators
;-)

So far, I have translated manuals for Bug Buddy and Zenity into
Serbian using xml2po, and it has fared pretty well.  The only
drawback right now is that I have to personally keep track of
sr.po's, instead of simply uploading them on Gnome CVS server, and
letting Shaun's build system take care of the rest.  But that will
come as well, hopefully soon.  [Oh yeah, I have to make figures by
hand, but that's not something xml2po can help with :]

Cheers,
Danilo

PS. Sorry about the long e-mail: I had the choice to either study for
the big exam tommorow (which I'll have another shot at in two weeks),
or to write this e-mail â guess what won :-)