Launchpad Help > Translations > Your Project > Best practices

Best practices for translating software projects

About this page

The guide found under Your Project will introduce you to how translations are done in Launchpad Translations. It assumes familiarity with gettext and points to different options as well as suggesting how to do things.

This page is different in that it explains one recommended way to set up your software project for translations using Launchpad. There are other ways of doing things but they will not be mentioned here.

Assumptions

This guide assumes that you have not yet done any internationalization (i18n) on your software project nor that any translations (localization, l10n) have been done yet. You have written a great program using English as its interface language and now you want to have it translated into other languages using Launchpad.

Your project and user name

For demonstration purposes we assume that your project is called "Frobnob" and is available at https://launchpad.net/frobnob on Launchpad. Whenever you see this name replace it with the name of your project. For your user name, we assume "joe" in the same manner.

If you have not yet registered you project on Launchpad, read about it here.

(Now, please don't go and register the frobnob project on Launchpad for fun. You can do that on our sandbox server, if you really want to.)

Prepare the source code

This part is often called the actual "internationalization (i18n)" because it enables the translation of your otherwise monolingual software. Please be aware that Launchpad (and really also gettext) only supports translations from American English (en_US) to other languages. If your software uses a different language you will need to translate it to English first.

GNU gettext

GNU gettext is the standard software used in most Free Software projects for internationalization. You can find it on the GNU website but you can expect it to be available in all modern Linux distributions. It consists of tools to use by developers and translators as well as a library that inserts the translations into the application at run time.

At this point you should familiarize yourself with how to prepare program sources using gettext. The gettext manual explains general aspects of this as well as giving examples in the C programming language. Other programming languages have their own APIs to the gettext library, like the gettext module in Python.

Translation domain

You need to choose a translation domain for your software. This domain is a name that identifies your translations at run time and needs to be unique on any system where your software will be installed. Usually it is identical to the name of the package that your software is distributed as which in turn is commonly reflected in the name of the Launchpad project. Multiple executables can share the same translation domain and usually do if they are from the same package.

The translation domain will be used as the filename for your translation template and Launchpad will use this name when referring to the template. Because it will be used in Launchpad URLs, this name is restricted to lowercase letters (a-z), numbers 0-9), dashes (-), and dots (.).

For our demonstration purposes, "frobnob" would be a fitting translation domain.

Creating translatable strings

The gettext manual explains about pitfalls when marking translatable strings. Please make sure to avoid these and make sure that the string the translator will see in Launchpad is meaningful and therefore translatable. Launchpad supports translation contexts and source comments which are displayed to the translator for help. Placing a comment that begins with "TRANSLATORS:" before a translatable string will create such a comment.

Build the template

Once all English strings in the source code have been marked for translations they need to be extracted into what is called the "translation template". This file will be imported into Launchpad to make these strings available to translation.

Use the xgettext program to create the template. The output file should be renamed to "frobnob.pot". Integrate the creation of the template into your build system, e.g. add the xgettext call to your Makefile.

Place the template into its own directory in your tree. This directory is usually called "po" and found in the root of your package. If you have multiple templates for your software (advanced setup), make sure to place each in its own directory, usually called "po-frobnob", or whatever the other templates are called.

Create a Bazaar branch

Launchpad uses Bazaar for source code repositories and Launchpad Translations makes use of these to import translation templates. Since your project needs to be Open Source in order to use Launchpad for free, you should use this as the way to publish your source code. Do not create a separate repository for your i18n-related files.

If your project is stored locally in the "frobnob" directory, use these commands to create a "trunk" branch on Launchpad:

cd frobnob
bzr init
bzr add
bzr commit -m"Initial commit."
bzr push --remember lp:~joe/frobnob/trunk

Be sure to include the "po" directory and the template file in this branch.

The template file is normally considered a temporary file because it can be created from the sources at any time and holds no separate information. Although this would speak against putting it under version control it is currently necessary in order to provide an easy way of uploading it to Launchpad. Eventually, Launchpad will be able to generate the template by itself from the sources but that feature is still under development.

Whenever the source code changes and you generate a new template file, update the branch on Launchpad with these commands:

cd frobnob
bzr add # Only if new files were created.
bzr commit -m"Description of change."
bzr push

You can view your branch in Launchpad by going to its URL https://code.launchpad.net/~joe/frobnob/trunk.

Set up your project in Launchpad

Enable the translations feature

If not already done, enable translations for your project at this URL: https://launchpad.net/frobnob/+configure-translations.

Set the source code branch

You may have noticed that you pushed the Bazaar branch to a URL under your own name. Now you need to tell Launchpad that this is the main source code location for your "trunk" series. A "trunk" series is always created with your project.

Got to this URL https://launchpad.net/frobnob/trunk/+linkbranch and select the branch named ~joe/frobnob/trunk. To do this, click on "Choose" and search for "joe". Your branch should come right up. Once this is done, you can refer to it as simply "lp:frobnob".

Enable translation imports

Now you are ready to tell Launchpad to import your translation template from the branch you pushed to Launchpad. Go to this URL to do so: https://translations.launchpad.net/frobnob/trunk/+translations-settings

At the bottom of the left side of the page select the second option: "Import template files". Above that you see a reference to the official Bazaar branch you created in the last step. Click on "Save settings" to activate the import.

Import the template into Launchpad

The import of your template happens automatically whenever the file is update in the Bazaar branch. You can watch the progress of the import on the import queue page for your project: https://translations.launchpad.net/frobnob/+imports. It will initially be marked as "Approved" and later change to "Imported". Depending on the server load, the import may take a few hours but usually happens much quicker.

Once your template has been imported, you can see it in Launchpad at this URL: https://translations.launchpad.net/frobnob/trunk/+pots/frobnob

Translation permission and group

You as the maintainer are most likely not the one doing the translations into all the different languages. In fact, you came to Launchpad Translations for the very reason to find translators in its community. But how do you know the translations contributed from community members are correct and of good quality? That's what translation groups are for. When you look at the Launchpad translators group you see that it consists of translation teams for quite a few languages. The members of these teams are experts for translations to their language and usually native speakers. These are the people that will help you ensure good quality translations.

Go to https://translations.launchpad.net/frobnob/+settings and chose "Launchpad Translators" as the translation group and "Structured" as the translation permission. Then set the translation focus to "Frobnob trunk" and click "Change". Now translations for the languages covered by Launchpad Translators can only be approved by the members of the respective language team. Any registered user of Launchpad can still make suggestions, but it is the teams that review and accept or decline them.

Translate!

Now the actual translating can start!

Please read the Launchpad Translators instructions for project maintainers. You should also join the team on Launchpad and subscribe to the mailing list. On this list you can announce your new project and ask people to translate it.

Export translations from Launchpad

Setup export to your branch

Translations done in Launchpad need to be exported back to your project branch so that you can include them in releases of your software. Launchpad provides automatic daily export of new translations to your branch. Go to the settings page to enable this: https://translations.launchpad.net/frobnob/trunk/+translations-settings

In the right column click "Choose a target branch", then enter "lp:frobnob" as the branch name and click "Update". This directs Launchpad to export the translations into the same branch where it imports the template from. You can await the export on the branches page under "Recent revisions": https://code.launchpad.net/~joe/frobnob/trunk Please remember that exports only happen once a day and only if there are any new translations to export.

Update your local branch

To download the translations to your local copy of the branch, simply pull in the changes from Launchpad:

cd frobnob
bzr pull

The translations will be placed in the "po" directory where your template file resides. They are in PO format and are named according to the language code, e.g. "po/fr.po" for the French translations.

Deploy the translations

The translations are shipped with binary packages in the also binary MO format. MO files are created from PO files using the gettext msgfmt utility. MO files are usually installed as "/usr/share/locale/ll/LC_MESSAGES/frobnob.mo" where "ll" is the respective language code. Remember that "frobnob" here is the translation domain that you chose in the beginning. You should integrate the MO file creation into the install portion of your build system, i.e. include it in you Makefile.

What if ... ?

Some help for special situations or hick-ups you might encounter.

What if I made changes to my local copy of the branch while translations were exported into the Launchpad copy?

When ever you make changes to your source code you should commit those changes as described earlier. If Launchpad exported translations while you committed to your local branch, the two copies will differ. A subsequent "bzr push" or "bzr pull" will complain about the branches having diverged. This is no big problem as you can simply merge the changes that Launchpad made to your branch into your local copy and then push that updated version back out to Launchpad. These are the commands to do that.

cd frobnob
bzr  merge lp:frobnob
bzr commit -m"Merged translation exports."
bzr push

Now both your branches will be identical again. You should not encounter any conflicts during the merge because the translations export will only touch PO files in the "po" directory which you should not be editing manually when working with Launchpad.

What if the translation statistics never show my strings as "translated"?

On the translations overview page for your project, project series or template, i.e. https://translations.launchpad.net/frobnob/trunk, you see a color-coded status bar for each language. As they start out red when all strings are untranslated, maintainers expect these to turn green as translation work progresses. For projects that work entirely on Launchpad, though, the target color is purple which means "Newly translated in Launchpad".

There is work under way that will redefine and simplify the different statuses.

What if I already have translations for my project?

It is least error-prone to do a full switch to using Launchpad Translations. Any translations that you may already have when you begin using Launchpad Translations can be imported, though, so they are not lost. This assumes that these are already available in PO files.

Place the PO files into your "po" directory, named the same way as Launchpad would do, e.g. "po/fr.po" for the French translations. Use "bzr add", "bzr commit" and "bzr push" as described earlier to copy them to Launchpad. Now go to this page on Launchpad: https://translations.launchpad.net/frobnob/trunk/+request-bzr-import and click "Request one-time import". This will place all the translation files into the import queue from where they will eventually be imported.

Please be aware that although all translations done in Launchpad are BSD-licensed, translations imported like this retain their original license.