3.12 Handling Gnulib’s own message translations

Gnulib provides some functions that emit translatable messages using GNU gettext. The ‘gnulib’ domain at the Translation Project collects translations of these messages, which you should incorporate into your own programs.

There are two basic ways to achieve this. The first, and older, method is to list all the source files you use from Gnulib in your own po/POTFILES.in file. This will cause all the relevant translatable strings to be included in your POT file. When you send this POT file to the Translation Project, translators will normally fill in the translations of the Gnulib strings from their “translation memory”, and send you back updated PO files.

However, this process is error-prone: you might forget to list some source files, or the translator might not be using a translation memory and provide a different translation than another translator, or the translation might not be kept in sync between Gnulib and your package. It is also slow and causes substantial extra work, because a human translator must be in the loop for each language and you will need to incorporate their work on request.

For these reasons, a new method was designed and is now recommended. If you pass the --po-base=directory and --po-domain=domain options to gnulib-tool, then gnulib-tool will create a separate directory with its own POTFILES.in, and fetch current translations directly from the Translation Project (using rsync or wget, whichever is available). The POT file in this directory will be called domain-gnulib.pot, depending on the domain you gave to the --po-domain option (typically the same as the package name). This causes these translations to reside in a separate message domain, so that they do not clash either with the translations for the main part of your package nor with those of other packages on the system that use possibly different versions of Gnulib. When you use these options, the functions in Gnulib are built in such a way that they will always use this domain regardless of the default domain set by textdomain.

In order to use this method, you must—in each program that might use Gnulib code—add an extra line to the part of the program that initializes locale-dependent behavior. Where you would normally write something like:

  setlocale (LC_ALL, "");
  bindtextdomain (PACKAGE, LOCALEDIR);
  textdomain (PACKAGE);

you should add an additional bindtextdomain call to inform gettext of where the MO files for the extra message domain may be found:

  bindtextdomain (PACKAGE "-gnulib", LOCALEDIR);

(This example assumes that the domain that you specified to gnulib-tool is the same as the value of the PACKAGE preprocessor macro.)

Since you do not change the textdomain call, the default message domain for your program remains the same and your own use of gettext functions will not be affected.