Preparing your project

In the instructions below we will assume that you will not be using gettext directly, but intltool, which was written specifically for GNOME. intltool uses gettext(), which extracts strings from source code, but intltool can also combine strings from other files, for example from desktop menu details, and GUI resource files such as Glade files, into standard gettext .pot/.po files.

We also assume that you are using autotools (e.g. automake and autoconf) to build your project, and that you are using https://gitlab.gnome.org/GNOME/gnome-common/blob/master/autogen.sh or a similar autogen.sh file, which, among other things, takes care of some intltool initialization.

An alternative to gnome-common's autogen.sh may look like this:

#! /bin/sh -e
test -n "$srcdir" || srcdir=`dirname "$0"`
test -n "$srcdir" || srcdir=.

autoreconf --force --install --verbose --warnings=all "$srcdir"
echo "Running intltoolize --copy --force --automake"
intltoolize --copy --force --automake
test -n "$NOCONFIGURE" || "$srcdir/configure" "$@"

Create a sub-directory named po in your project's root directory. This directory will eventually contain all of your translations. Within it, create a file named LINGUAS and a file named POTFILES.in. It is common practice to also create a ChangeLog file in the po directory so that translators can keep track of translation changes.

LINGUAS contains an alphabetically sorted list of codes identifying the languages for which your program is translated (comment lines starting with a # are ignored). Each language code listed in the LINGUAS file must have a corresponding .po file. So, if your program has German and Japanese translations, your LINGUAS file would look like this:

# keep this file sorted alphabetically, one language code per line
de
ja

(In addition, you'd have the files ja.po and de.po in your po directory which contain the German and Japanese translations, respectively.)

POTFILES.in is a list of paths to all files which contain strings marked up for translation, starting from the project root directory. So for example, if your project sources were located in a subdirectory named src, and you had two files that contained strings that should be translated, your POTFILES.in file might look like this:

src/main.cc
src/other.cc

If you are using gettext directly, you can only mark strings for translation if they are in source code file. However, if you use intltool, you can mark strings for translation in a variety of other file formats, including Glade UI files, xml, .desktop files and several more. So, if you have designed some of the application UI in Glade then also add your .glade files to the list in POTFILES.in.

Now that there is a place to put your translations, you need to initialize intltool and gettext. Add the following code to your configure.ac, substituting 'programname' with the name of your program:

IT_PROG_INTLTOOL([0.35.0])

GETTEXT_PACKAGE=programname
AC_SUBST(GETTEXT_PACKAGE)
AC_DEFINE_UNQUOTED([GETTEXT_PACKAGE], ["$GETTEXT_PACKAGE"],
                   [The domain to use with gettext])
AM_GNU_GETTEXT([external])
AM_GNU_GETTEXT_VERSION([0.17])

PROGRAMNAME_LOCALEDIR=[${datadir}/locale]
AC_SUBST(PROGRAMNAME_LOCALEDIR)

This PROGRAMNAME_LOCALEDIR variable will be used later in the Makefile.am file, to define a macro that will be used when you initialize gettext in your source code.

AM_GLIB_GNU_GETTEXT has been an alternative to AM_GNU_GETTEXT and AM_GNU_GETTEXT_VERSION, but AM_GLIB_GNU_GETTEXT is now deprecated, and shall not be used in new code.

In the top-level Makefile.am:

  • Add po to the SUBDIRS variable. Without this, your translations won't get built and installed when you build the program
  • Define INTLTOOL_FILES as:
    INTLTOOL_FILES = intltool-extract.in \
                     intltool-merge.in \
                     intltool-update.in
  • Add INTLTOOL_FILES to the EXTRA_DIST list of files. This ensures that when you do a make dist, these files will be included in the source tarball.
  • Update your DISTCLEANFILES:
    DISTCLEANFILES = ... intltool-extract \
                     intltool-merge \
                     intltool-update \
                     po/.intltool-merge-cache
  • Depending on the types of files that contain translatable strings, add code such as
    desktopdir = $(datadir)/applications
    desktop_in_files = programname.desktop.in
    desktop_DATA = $(desktop_in_files:.desktop.in=.desktop)
    @INTLTOOL_DESKTOP_RULE@

In your src/Makefile.am, update your AM_CPPFLAGS to add the following preprocessor macro definition:

AM_CPPFLAGS = ... -DPROGRAMNAME_LOCALEDIR=\"${PROGRAMNAME_LOCALEDIR}\"

This macro will be used when you initialize gettext in your source code.