serverguide.pot file and .po files

[Matthew East]

Hi Doug,

On 25 March 2013 19:19, Doug Smythies <dsmythies at telus.net> wrote:
> I know these e-mails have been going out to the list, because
> I can find them in the archives. So why no replies?
>
> It is my impression that those that know how all of this stuff
> works have largely backed of from the doc projects, leaving a
> knowledge gap.
>
> In my opinion, this waste tons (and I mean tons) of time trying
> to figure things out for yourself approach, does not maximize
> the use of ones volunteer hours.

Yes, it's a fair point. I was involved in setting up most of these
mechanisms and do not contribute much any more. I still lurk around
the list but as you've already experienced am not good at responding
promptly to queries about how things work. I'll try and do better at
that, but don't expect to invest any time in the project in the future
apart from that.

What I would suggest is that you take a look at these pages, and see
if they help you understand the process:

https://wiki.ubuntu.com/DocumentationTeam/Translation
https://help.launchpad.net/Translations

The first page may have elements to it which are out of date, and
elements which do not answer all of your questions, but ultimately if
you are interested in getting up to speed on how translations are
generated and imported, there will be very little substitute for
reading the scripts and learning about how they work.

I'll try and answer specific questions below.

> I have been struggling to understand the process of when to update
> the serverguide.pot file and when and how the .po files get updated.
> (Actually, I have been struggling to understand many many things.)
>
> If we use as an example case [1] and look at the various files we
> see that the serverguide.pot file became current as of that commit,
> 2012.10.22. However the various .po files were based on the previous
> severguide.pot file of 2012.04.03 and seem to take quite awhile, a month
> or more, to get updated. (Which makes sense, because doesn't someone
> else in the chain of events actually update the .po file? (in launchpad,
> not in the main BZR branch))

Correct, po files are updated by translators working in Launchpad,
either directly through the web interface or by uploading po files to
Launchpad manually. However when there is a new pot template in
Launchpad, Launchpad updates the po files automatically so that any
new strings in the pot template show as new strings to be translated.
Launchpad takes care of automatically merging po files.

> Does updating the serverguide.pot file, in the main BZR branch,
> trigger a chain of events leading to new .po files, in launchpad?

Yes, it should do if the Launchpad project is set up correctly.
Launchpad now pulls pot files from bzr branches if those branches are
linked properly to the relevant series in the upstream project. See
for example this page: https://translations.launchpad.net/ubuntu-docs.
Then, as I noted above, Launchpad automatically updates the po files.
The translators still need to add translations of any new strings
though.

> I have updated the 12.04 serverguide.pot file twice in
> the last few days. The first time was in response to [2], where it was
> significantly outdated. The second time was just because I was accepting
> a merge proposal anyway. Maybe I should have only updated it once, and
> then leave it for a chunk of time.
>
> Why do we bother to update the .po files during a commit, albeit rarely?

The idea of updating po files is to get any new translations that
exist in Launchpad into the released package. We would generally do it
after string freeze and just prior to a release.

> They are already out of date at the time of the commit anyhow, if the update
> also includes an update to serverguide.pot at the same (which all of
> the examples I have found do).

If the pot file is out of date in Launchpad, then the po file export
can still be useful because any strings that are still in the pot file
that have been translated in Launchpad since the last export will be
picked up.

Bear in mind that when you export po files from Launchpad, if you
export the whole list of translations, you also get a pot file
exported, and if you add that to the bzr branch, it will look as
though you have changed the pot file. That is simply because for some
reason pot files do not always look the same when generated, sometimes
strings appear in a completely different order. So if you see a diff
that shows changes to the pot file, that doesn't necessarily mean that
there are any substantive changes, it could just be that it has been
generated by Launchpad and the strings are in a different order. I
don't know why this happens, I think the translation technology
(gettext) is not very compatible with revision control technologies
generally.

One other thing to bear in mind, although it probably doesn't affect
the server guide in the way that it affects packages that are in
Ubuntu, is that Launchpad differentiates between upstream projects and
Ubuntu packages. Translation is available for both of them, and
although we try to use upstream projects for translation in the
docteam, this isn't always followed by translators. This is ultimately
dealt with by linking the upstream project and the Ubuntu package,
such that Launchpad automatically shares translations that are added
in each place.

> For this line from the example commit [1]: "Import translations from LP"
> How does one do it?

Hopefully the pages I've linked to will answer this.

> [4] suggests that quantal has automated .po file import. As far as I
> have determined that is incorrect, and Jeremy did it manually.

Launchpad supports either option now. I've personally found the
automated .po file import very laborious, because it results in vast
amounts of diffs on a daily basis which hugely increase the size of
the branch. This can be (partially) handled by maintaining a separate
translations branch and merging it in manually, but I think that also
has its own issues. Personally I've always found it easier to import
translations manually.

> However they are still out of date, as there is a one cycle lag
> between serverguide.pot and the .po files. Is that correct?

This is probably due to a lack of contribution on the part of docteam
members so that either the pot file is not updated in bzr frequently
enough, or translations are not exported at the appropriate time.

Hope some of this helps.

Matt