translating gnome-user-docs

[Danilo Šegan]

Hi Matthew,

Yesterday at 22:06, Matthew East wrote:

> The problem is that the Ubuntu changes aren't really suitable for
> using <xinclude>. They range from really small changes (menu path
> changes) to really big ones (complete reorganisation of the
> accessibility guide). Also, we'll probably remove text, and generally
> do other things that we can't use xinclude for.

Yeah, I get the idea.

>> Then, when building translated documentation, you'd first merge all
>> the downloaded PO files from Launchpad with the ones from the package:
>>
>>   msgcat --use-first sr/sr.po launchpad-pos/sr.po > new-sr.po
>
> Can this technique be used or modified even if we don't create
> separate ubuntu-changes pot templates? So, if we build pot templates
> using the existing gnome-user-docs build system and upload them to
> Rosetta, those will have the new strings, and translators can
> translate them. Then, we can slip the po files into the directory
> structure as they are now, and the xml can be built using the existing
> build process.

Well, it almost can.  In practice, you can do with PO files a lot of
things but you have to use gettext tools instead (but, they can do
just basic operations, so you have to combine them in funny ways to
get what you want, but then it's easy to make that a script).

For example, you can easily separate out the changes done in Ubuntu if
you keep the upstream POT as well, i.e.

  # mark all messages in upstream.pot as translated (to English, but whatever)
  msgen upstream.pot >upstream-en.po
  # mark as translated messages existing in both upstream.pot and ubuntu.pot
  msgmerge -N -o ubuntu-en.po upstream-en.po ubuntu.pot
  # get only untranslated messages
  msgattrib --untranslated ubuntu-en.po > ubuntu-changes.pot

Basically, the idea is this: msg* tools allow us to filter by
translated/untranslated messages, and to merge existing translations.
With that, we create a fully translated upstream POT, merge it in
Ubuntu POT, which now only has changed messages untranslated.  Then,
it's easy to filter it using msgattrib.

The big advantage of a set-up like this is that real upstream GNOME
User Docs would be translatable as part of a package in Ubuntu, and
Ubuntu changes would be in a separate template.  And I think that
would be cool, but I understand it may be too complicated on your end.

> The only tricky part is merging new translations from upstream: is
> there a way to do this? So, if I use "bzr merge" from upstream and get
> a conflict, is there a way to merge the updated po files?

It is easy to do it in that direction (it's just that bzr won't be
able to do it for you, *and* you'll have to clean up files to not have
any conflicts first [usually by just checking them out again, or
keeping separate directory trees]):

  msgmerge -C de.po upstream-de.po ubuntu.pot > new-de.po

(we are using existing Ubuntu translation as "compendium", so they
don't overwrite translations in upstream-de.po; if you want to give
precedence to the other [risking losing updates from upstream], just
swap them out)

It's also easy to do it in other direction using similar command (if
you want to contribute back to GNOME), except that your PO file won't
have all the messages, so you can't translate gnome-users-docs
completely using Launchpad.

>> Well, another reason for allowing GNOME manual translations using
>> Launchpad is that translations there are lacking.  I do, however,
>> understand that those teams with very succesful teams (yeah Daniel,
>> talking about you :) need no such help, but others might indeed need
>> and want it.
>
> Yeah, I think we should do this if we can.

Agreed, so lets just figure out a set-up for that.  If you need more
step-by-step help, you know where to find me :)

Cheers,
Danilo