Make Packaging Guide translatable

I've got the basics working, but it's not really ready to land yet.

One thing that I'm not sure how to handle is that in order to build the translated files you seem to need to have the sphinx.mo files for the languages you want. As sphinx is in main, we strip out the .mo files and put them in language-pack-* packages instead. Build-depending on the needed language-packs doesn't really seem right.

We're going to need to figure out the workflow after this lands. As this project is all documentation, we're going to be breaking the translations on nearly every commit. Also, as we'll want the .pot file in version control so it's available to Rosetta, "make gettext" will probably have to be run before every push to trunk to keep it up to date. I wonder if there is some way we can automate that. I don't think bzr has per-branch pre-commit hooks though.

Also, how is this deployed to the website? This is going to change the installed location slightly, so landing it will probably need to be coordinated so as to not break the website.

If you want the translations to be out of the language packs, I believe there is an option on pkgbinarymangler (or perhaps it can be specified in the same package, on the control file?) to blacklist a package from getting its translations. I'd recommend having a word with pitti about it, as he knows the exact details.

In terms of exposing it to translators, if you're not using language packs but rather ship the translations in the package (watch out for it not becoming too big, though), I'd recommend enabling translations in the upstream project, with the following settings:

For the overall project:
- Restricted permissions
- Assigned to Ubuntu translators

Then on the relevant series:
- Enable automatic imports (import only templates)
- Enable automatic exports (for a full automated experience, use the same branch for exports and imports)

In terms of workflow, if you don't want to break translations on every commit, I'd recommend doing .pot file updates only on milestones where you think the documentation is stable, and announce these milestones on the ubuntu-translators mailing list.

And regarding deployment, we've got write access to the directory where the html is published, so if translations can live in the same place and we can write them there, it shouldn't be much of an issue, I think. We'll probably only have to adjust the script that publishes the HTML (and other formats, probably) to ensure translations are pulled too.

Thanks for making the Packaging Guide translatable!

Just a quick update: right now the Packaging Guide is only packaged in a PPA, it's not even in the archive yet. In any case it'd still be nice to solve all the problems mentioned above.

On Thu, Mar 1, 2012 at 4:38 AM, David Planella
<email address hidden> wrote:
> If you want the translations to be out of the language packs, I believe
> there is an option on pkgbinarymangler (or perhaps it can be specified
> in the same package, on the control file?) to blacklist a package from
> getting its translations. I'd recommend having a word with pitti about
> it, as he knows the exact details.

I'll try to talk with pitti. It turns out that there is already an
open bug against sphinx about this. We're not the only ones running
into it. See bug 480913.

Temporarily, this might not be that big of a deal as we're only
releasing to the PPA. We can just provide our own build of sphinx that
won't be stripped.

> In terms of workflow, if you don't want to break translations on every
> commit, I'd recommend doing .pot file updates only on milestones where
> you think the documentation is stable, and announce these milestones on
> the ubuntu-translators mailing list.

Yep. Right now, this is only distributed a daily build and nothing is
particularly stable. We'll need to come up with a release process as
the project grows up either way.

> Thanks for making the Packaging Guide translatable!

Thanks for the feed back!

-- Andrew Starr-Bochicchio

   Ubuntu Developer <https://launchpad.net/~andrewsomething>
   Debian Maintainer
<http://qa.debian.org/developer.php?login=a.starr.b%40gmail.com>
   PGP/GPG Key ID: D53FDCB1

Just a quick update...

This is almost ready to land. I'm just unhappy with the install path, but I can't figure out how to do it differently. Currently, things install with paths like this:

/usr/share/doc/ubuntu-packaging-guide/html/en/ubuntu-packaging-guide/index.html

It's ugly and redundant! I really hate that second "ubuntu-packaging-guide." This is an issue with the "gettext_compact" setting and having to move things into a single directory. Things are getting built to:

_build/html/en/ubuntu-packaging-guide/index.html

And we can't just move things around manually as the static assets end up in directly in "_build/html/en/" So moving the html will break links. I'm think that I might just process it with sed and move the html down one dir in the Makefile.

sed -i 's/href="..\//href=.\/"/g'

It feels really fragile though, so if anyone has a better idea I'd love to hear it.

> sed -i 's/href="..\//href=.\/"/g'

See what I mean by fragile? =) sed -i 's/href="..\//href=".\//g'

I thought about this too and every single solution I could think of was inherently dirty. I was thinking of doing a regular build of everything, then cleaning up and applying some magic to be able to do the gettext build (or the other way around). I don't know how feasible this is though.

Shall we go ahead with this for now and fix it if it breaks?

On Fri, Mar 16, 2012 at 4:15 AM, Daniel Holbach
<email address hidden> wrote:
> Shall we go ahead with this for now and fix it if it breaks?

I'll submit a merge proposal.