Localisation on maemo

Localisation

Localisation means translating the application into different languages. In maemo, localisation is based on standard gettext, and all the necessary tools are included in scratchbox. For applications, localisation needs one or two files to work on, which are found in the po/ directory. The following files are used for localisation:

Makefile.am	
en_GB.po
POTFILES.in

POTFILES.in contains the list of source code files that are localised. The en_GB.po file includes translated text.

Adding localisation to your application

To add localisation to your application, you need to set up l10n before gtk.init by including the following headers:

 main.c
 #include 
 #include

To initialise the locale functions you also need to add the following lines:

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

The most important of these are the GETTEXT_PACKAGE and LOCALEDIR that 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

From these, only GETTEXT_PACKAGE requires attention, as it is the l10n domain you want to use. ALL_LINGUAS lists the translations you have available.

If you are building applications for IT OS 2005 edition, set localedir to /var/lib/install/share/locale.

Easing string extraction

In your source code there are strings littered everywhere. These are eventually displayed in the user interface. For example:

	hildon_app_set_title ( app, "maemoPad" );

To make your strings localisable, you need to wrap the strings that you want translated in gettext("String") calls. In practice, writing gettext() for every string is time consuming. The common practice is to set the following #define setting:

	#define _(String) gettext (String)

Therefore, the i18n version of the example is:

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

Creating en_GB.po

Creating po files is straightforward. maemopad is a good example. maemopad only has one localisation file en_GB.po, others like fi_FI.po can be easily made based on this. Localisation .po files are filled with simple structure, which defines the localisation ID and the actual text string. The following is a sample of this structure:

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

The "msgid" indicates the original string (key) used in code and "msgstr" defines the translated string for localisation.

First create a template file with all strings from sources for translation. Use the GNU xgettext command [9] to extract the strings from sources:

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

The "-f POTFILES.in" option uses POTFILES.in to get the files localised. "-C" is for the C-code type of strings, "-a" is to ensure that you get all strings from sources, and "-o template.po" defines the output filename.

This may output some warnings, which are usually not serious, but it is recommended that you check them anyway.

If you want to translate to Finnish, copy the edited po/template.pot to po/fi_FI.po and add fi_FI.po to ALL_LINGUAS in configure.ac.

po/fi_FI.po now includes lines like the following:

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

Translate all msgstrings into the language into which you are translating:

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

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

If you want to do it yourself:

	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 to which you want to install software.

You can find all the necessary files as an example at: stage.maemo.org under maemo testing/maemopad

Testing

Inside the scratchbox, test your translated application by setting LC_ALL enviroinment variable:

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

On the target device, you need a wrapper script to get the same effect.

Improve this page

Register