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 before a translatable string that begins with "TRANSLATORS:" 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 viewed as 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 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

Review translations

Export translations from Launchpad

Deploy the translations

What if ... ?