Maemo Localization How-to

This document has been reviewed for maemo 4.0.

This document describes how to localize maemo applications. Localization is needed to provide native translations of the software. The document contains information on how to localize an application, how to ease extraction of message strings, how to make the translations and how to test the localization.

Changes are presented with code examples to help the localization process. The examples and all necessary files can be found at stage.maemo.org.

Localization means translating the application to different languages. Maemo localization is based on standard gettext package, and all the necessary tools are included in Scratchbox. For applications, localization requires a couple of files in the po/ directory. The following files will be used for localization:

Makefile.am	
en_GB.po
POTFILES.in
			

POTFILES.in contains the list of source code files that will be localized. File en_GB.po includes translated text for target en_GB.

To localize an application, l10n needs to be set up before gtk_init() by including the following headers.

 #include <libintl.h>
 #include <locale.h>

To initialize the locale functions, the following lines need to be added:

 setlocale(LC_ALL, "");
 bindtextdomain(GETTEXT_PACKAGE, LOCALEDIR);
 bind_textdomain_codeset(GETTEXT_PACKAGE, "UTF-8");
 textdomain(GETTEXT_PACKAGE);

The most important of these are GETTEXT_PACKAGE and LOCALEDIR, which come from configure.ac:

 localedir=/usr/share/locale
 AC_PROG_INTLTOOL([0.23])
 GETTEXT_PACKAGE=maemopad
 AC_SUBST( GETTEXT_PACKAGE )
 ALL_LINGUAS="en_GB"
 AM_GLIB_GNU_GETTEXT

Of these, only GETTEXT_PACKAGE needs special attention, as it is the l10n domain that is to be used, and ALL_LINGUAS lists the available translations.

When building applications for maemo, localedir should be set to /var/lib/install/share/locale.

In the source code, there are multiple strings that eventually get shown in the user interface. For example:

	hildon_app_set_title ( app, "MaemoPad" ); 

In order to make the strings localizable, they need to be wrapped in gettext("String") calls. In practice, writing gettext() for every string is tedious. The common practice is to set the following #define

	#define _(String) gettext (String)

Thus, the i18n version of the example would be:

	hildon_app_set_title ( app, _("MaemoPad") );

Creating Translation Files

Creating *.po files is quite straightforward. In this document, Maemopad is used as an example. Maemopad only has one localization file, en_GB.po; others, such as fi_FI.po, can be easily made based on this. Localization .po files are filled with simple structures, defining the localization id and the actual text string, e.g.

#: src/document.c:727 src/document.c:733
msgid "note_ib_autosave_recover_failed"
msgstr "Recovering autosaved file failed"
			

"msgid" defines the original string (key) used in code, and "msgstr" defines the translated string for localization.

First, a template file is created with all strings from sources for translation. GNU xgettext command [9] is used to extract the strings from sources:

"xgettext -f POTFILES.in -C -a -o template.po"

Option "-f POTFILES.in" uses POTFILES.in to get the files to be localized, "-C" is for C-code type of strings, "-a" is for ensuring that all the strings are received from sources, and "-o template.po" defines the output filename.

This may output some warnings. Usually they are not serious, but it is better to check them anyway.

If the translation in question is into Finnish, the edited po/template.po needs to be copied to po/fi_FI.po, and fi_FI.po needs to be added to ALL_LINGUAS in configure.ac.

Now po/fi_FI.po will include lines such as the following:

	#: ../src/ui/interface.c:123
	msgid "maemopad_save_changes_made"
	msgstr "Save changes?"
			

All msgstrings should be translated into the desired language:

	#: ../src/ui/interface.c:123
	msgid "maemopad_save_changes_made"
	msgstr "Tallenna muutokset?"
			

Autotools should now automatically convert the .po file to .mo file during the build process, and install it to the correct location.

To do it manually:

	msgfmt po/fi_FI.po -o debian/maemopad/share/locale/fi_FI/LC_MESSAGES/domain.mo
			

Where "debian/maemopad/share/locale/fi_FI/LC_MESSAGES/" is the directory where the software should be installed to.

All the necessary files can be found as an example in stage.maemo.org.

Testing

Inside scratchbox, the translated application should be tested by setting LC_ALL environment variable to contain the newly created locale (in this example case for Finnish translation, "fi_FI"):

	LC_ALL="fi_FI" run-standalone.sh ./maemopad
			

On the target device, a wrapper script is needed to accomplish this, if the device does not have a locale for the locale identifier used. The script can simply consist of:

	#!/bin/sh
	LC_ALL="fi_FI" /usr/bin/maemopad
			

The example above assumes that the installation package installs the executable into /usr/bin. This script needs then to be configured to be run in the application's .desktop file, instead of the actual executable.