1. Introduction

Localization is important for every user who doesn’t speak English fluently. If your native language is not English, then you can help us by translating a few sentences to your native language. If you would like to help, the following steps are necessary:

  • Visit the web interface and register.

  • Select your language (ie. if you would like to contribute French translation, select French). If your language is not listed, then ask for addition on our developer mailing list.

  • Select what projects you would like to translate. It’s good to start with some smaller project like the homepage or the setup. If the given project has no .po file for your language, contact us.

  • Now you can begin translating, but your changes won’t hit the master repo, you need additional permissions to commit from the sandbox. Ask us for commit access.

A few tips if you’re new to pootle:

  • By default you can edit the whole translation, but usually you would like to see only the untranslated and fuzzy strings. You can search for them by clicking on "Show editing functions" then selecting "Quick translate".

  • You can commit a po file by clicking on "Show editing functions" then selecting "Commit".

  • You can search for fuzzy translations by clicking on "Show editing functions", selecting "Show checks" and then the "isfuzzy" check.

2. Rules

There are not many, at the moment.

  • Please don’t translate the == NAME and == SYNOPSIS strings in the manpages, docbook does it already and asciidoc fails to create the manpage if it’s already translated.

  • The first translator for a language (this can be changed if requested) receives all rights for a given project, except: Suggest, Overwrite, Assign, Administrate.

3. Goals

When we created the current mechanism of handling translations, we had the following goals:

  • When we modify source code or documentation, the translators should be able to begin the necessary (if any) translations without any manual action.

  • It would be be nice to overview the localization status of a language.

  • It should be easy to maintain the translation (ie. doing a manual sync for big documents is rather problematic).

  • Translators are not developers, write access to the translations should not require any other access right.

  • It should be possible for anyone to translate, but only given users should be able to push changes.

4. Overview

Now let’s see how all this is possible. We’ll take our asciidoc documentation as an example.

First, we need to extract the translatable strings from the sources. This is an important step since this way a document is split into paragraphs and you can then later translate even a single paragraph rather then choosing between translating a 10-page-length document entirely or not. We use po4a for this purpose. It creates a template, named docs.pot, which is transferred daily to the translation server.

(For source codes we usually use the intltool-update utility to extract translatable strings.)

Right after the transfer, the po localization files are updated using msgmerge from the gettext package: this way the translators do not have to re-translate the strings which are already done.

On that machine, we use a web interface for the translation. This has several advantages:

  • The translators can register and begin their work without any confirmation from our developer team.

  • Those accounts are - of course - not real unix accounts but just virtual ones.

  • We can give commit access for users by specifying their project and language. So everybody can make translations but only users we know can push the changes.

  • Collaboration for people who do not know what a patch or a version control system is now should not be a big problem. This is important since for example the whole documentation is one big file per language.

Once a user with enough privileges pushes the translation to our git version control system, we can use it. The documentation is built daily and we pull the new translations from the dedicated repo before each build.

The output of the English build is available here. If it contains any error or warning, the testsuite will let us know by including them in the daily testsuite mail, sent to the developer mailing list. The log of the localization builds is available here.

There we use po4a again to reconstruct the original (now in some language other than English) document from the translated strings.

For source code we pull the translations right before creating a release tarball so. This has the following benefits:

  • We ship the latest translations

  • Once the tarball is ready, users who would like to compile the source code should not fetch the translations manually.

The proof of concept for this mechanism is our French documentation which is more than 80 pages length and includes zero percent of manual editing by the developers (while till now we had to push the submitted - by email and other undocumented channels - translated documents manually, hoping that the newer version is better than the old was).