I18nQuickstart

The purpose of this page is to guide UME apps developers in the implementation of i18n support.

Stack

UME is mainly built on the Hildon and GMAE (GNOME Mobile) stacks.

GNOME modules rely mostly on gettext for i18n and GLib provides some gettext support macros.

The glib-gettextize command as well as the glib-gettext m4 macros were meant to wrap gettextize and gettext macros in a more convenient way, but the same functionality is now in gettext proper.

The intltool suite wraps gettext too and helps with the translation of more objects such as desktop entry files, GConf schema files, XML files etc.

gettext

The traditional way to translate messages is to use gettext.

Header usage

To use GNU gettext functions such as gettext() for translation, it is enough to #include <libintl.h> and it is common to wrap gettext functions with _() and N_() to keep i18nized source code short; both can be achieved manually, but it's best to use GLib's gettext support macros.

Programs

For programs, it's the most straightforward:

#include <glib/gi18n-lib.h>

NB: gettext calls will use the current (default) textdomain, set by textdomain(), as discussed later.

Libraries

For libraries you need to ensure that GETTEXT_PACKAGE is properly defined; this will pass the name of your library's gettext message domain for gettext calls originating from your library:

#ifdef HAVE_CONFIG_H
#include "config.h"
#endif /* HAVE_CONFIG_H */

#include <glib/gi18n-lib.h>

Startup and initialization

In all cases, at initialization (or startup) time, gettext needs to be told about the location of message catalogs for the message domains used in later gettext calls. This is achieved with:

#ifdef HAVE_CONFIG_H
#include "config.h"
#endif /* HAVE_CONFIG_H */

#include <libintl.h>

int
main (int argc, char *argv[])
{
    bindtextdomain (GETTEXT_PACKAGE, FOO_LOCALEDIR);

    [...]
}

where FOO is the name of the module and SOMENAME_LOCALEDIR is defined by the build process, for example for Automake packages you might use this Makefile.am snippet:

INCLUDES = -DFOO_LOCALEDIR=\""$(prefix)/$(DATADIRNAME)/locale"\"

By default, translated strings come in the locale's encoding; depending on what you want to do with translated strings, this might be fine (for example if you need to send them to the console), but if for example you want to use them in Gtk+ interfaces, you'll need to transcode them to UTF-8 -- most GNOME functions assume UTF-8. It's common to request gettext to transcode strings from the locale's encoding into UTF-8 and it is achieved per message domain with:

    bind_textdomain_codeset (GETTEXT_PACKAGE, "UTF-8");

Programs

For programs, one additional startup task is to set the current (default) message domain; this is done with:

    textdomain (GETTEXT_PACKAGE);

Autoconf / Automake integration

The gettext package ships m4 macros recommended for Autoconf and Automake integration; simply include the following m4 macro call in your configure.ac (or configure.in):

AM_GNU_GETTEXT(external)

NB: external means that this software doesn't have a builtin libintl copy.

If you rely on a particular gettext version, or if you want to use autopoint as proposed later on, you should call the following m4 macro:

AM_GNU_GETTEXT_VERSION(0.14.5)

NB: gettext 0.17's autopoint supports gettext back to 0.10.35, but the corresponding macros are too old for current aclocal; 0.14.5 is the gettext version in Ubuntu 6.06.

As already discussed, it is useful to define the name of the message domain for this software with the GETTEXT_PACKAGE macro which will be defined when including config.h:

GETTEXT_PACKAGE=foo
AC_SUBST(GETTEXT_PACKAGE)
AC_DEFINE_UNQUOTED(GETTEXT_PACKAGE, ["$GETTEXT_PACKAGE"], [Name of the gettext message domain])

where foo is usually the name of the software.

Bootstrapping gettext support (autogen)

The autopoint program comes with gettext and will copy gettext infrastructure into your source package. It is usually invoked from a bootstrap script (often called autogen.sh).

The GNOME bootstrap script is named gnome-autogen.sh and is distributed in gnome-common; it will automatically call autopoint if AM_GNU_GETTEXT and AM_GNU_GETTEXT_VERSION are found in your configure.ac (or .in).

The first time you run autopoint, it will copy over documentation such as ABOUT-NLS, Autoconf support files such as config.rpath, create a po directory with a Makefile template (Makefile.in.in), a template (Makevars.template) for its configuration file (Makevars), and misc support files.

The Files You Must Create or Alter section in the gettext manual covers how to integrate gettext support in your application.

Example

A sample package demonstrating gettext integration is GNU hello.

GLib-Gettext

GLib-Gettext was meant to wrap gettext in convenient ways, but support for the additional features is now in gettext proper; glib-gettext is probably useless with a modern gettext. gnome-autogen has glib-gettext support.

Intltool

Intltool adds support for the translation of more file types; it's commonly used in GNOME projects. gnome-autogen has intltool support.

Since intltool is built on top of gettext, gettext documentation applies most of the time.

Autoconf / Automake integration

The intltool package ships m4 macros recommended for Autoconf and Automake integration; simply include the following m4 macro call in your configure.ac (or configure.in):

IT_PROG_INTLTOOL(0.35.0)

NB: Version 0.35.0 is the first version of intltool adding support for the po/LINGUAS as recommended by GNOME translators.

Bootstrapping gettext support (autogen)

The GNOME bootstrap script, gnome-autogen.sh, will automatically call intltoolize if IT_PROG_INTLTOOL is found in your configure.ac (or .in).

Example

A sample package demonstrating intltool integration is GNOME Hello. However it relies on glib-gettext; to use standard gettext in place of glib-gettext change AM_GLIB_GNU_GETTEXT into:

AM_GNU_GETTEXT(external)
AM_GNU_GETTEXT_VERSION(0.14.5)

MobileAndEmbedded/I18nQuickstart (last edited 2008-08-06 16:23:58 by localhost)