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.

Demo 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.

(Now, please don't go and create that 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 itself 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

Import the template into Launchpad

Review translations

Export translations from Launchpad

Deploy the translations

What if ... ?