Programming

Typical gettext workflow. The de.po instance on the left shows a "renewing" of translations via msgmerge.

The basic interface of gettext is the gettext(const char*) function, which accepts a string that the user will see in the original language, usually English. To save typing time and reduce code clutter, this function is commonly aliased to _:

printf(gettext("My name is %s.\n"), my_name);
printf(_("My name is %s.\n"), my_name); // same, but shorter

gettext() then uses the supplied strings as keys for looking up translations, and will return the original string when no translation is available. This is in contrast to POSIX catgets(),^[12] AmigaOS GetString(),^[13] or Microsoft Windows LoadString() where a programmatic ID (often an integer) is used. To handle the case where the same original-language text can have different meanings, gettext has functions like cgettext() that accept an additional "context" string.

xgettext is run on the sources to produce a .pot (Portable Object Template) file, which contains a list of all the translatable strings extracted from the sources. Comments starting with /// are used to give translators hints, although other prefixes are also configurable to further limit the scope. One such common prefix is TRANSLATORS:.

For example, an input file with a comment might look like:

/// TRANSLATORS: %s contains the user's name as specified in Preferences
printf(_("My name is %s.\n"), my_name);

xgettext is run using the command:

xgettext -c /

The resultant .pot file looks like this with the comment (note that xgettext recognizes the string as a C-language printf format string):

#. TRANSLATORS: %s contains the user's name as specified in Preferences
#, c-format
#: src/name.c:36
msgid "My name is %s.\n"
msgstr ""

In POSIX shell script, gettext provides a gettext.sh library one can include that provides the many same functions gettext provides in similar languages.^[14] GNU bash also has a simplified construct $"msgid" for the simple gettext function, although it depends on the C library to provide a gettext() function.^[15]

Translating

The translator derives a .po (Portable Object) file from the template using the msginit program, then fills out the translations.^[16] msginit initializes the translations so, for instance, for a French language translation, the command to run would be:^[5]

msginit --locale=fr --input=name.pot

This will create fr.po. The translator then edits the resultant file, either by hand or with a translation tool like Poedit, or Emacs with its editing mode for .po files. An edited entry will look like:

#: src/name.c:36
msgid "My name is %s.\n"
msgstr "Je m'appelle %s.\n"

Finally, the .po files are compiled with msgfmt into binary .mo (Machine Object) files. GNU gettext may use its own file name extension .gmo on systems with another gettext implementation.^[17] These are now ready for distribution with the software package.

GNU msgfmt can also perform some checks relevant to the format string used by the programming language. It also allows for outputting to language-specific formats other than MO;^[18] the X/Open equivalent is gencat.

In later phases of the developmental workflow, msgmerge can be used to "update" an old translation to a newer template. There is also msgunfmt for reverse-compiling .mo files, and many other utilities for batch processing.

Running

The user, on Unix-type systems, sets the environment variable LC_MESSAGES, and the program will display strings in the selected language, if there is an .mo file for it.

Users on GNU variants can also use the environment variable LANGUAGE instead. Its main difference from the Unix variable is that it supports multiple languages, separated with a colon, for fallback.^[19]