Recipe 19.10. Using gettext

19.10.1. Problem

You want a comprehensive system to create, manage, and deploy message catalogs.

19.10.2. Solution

Use PHP's gettext extension, which allows you to use GNU's gettext utilities. Example 19-24 uses the gettext functions to print messages from a custom message catalog.

Using gettext

<?php // Define the directories where the "animals" catalog can be found bindtextdomain('animals','/home/translator/custom/locale'); // Use the 'animals' catalog as a default textdomain('animals'); $languages = array('en_US','fr_FR','de_DE'); foreach ($languages as $language) {     // Change to the appropriate locale     setlocale(LC_ALL, $language);     // And get a localized string     print gettext('Monkey');     print "\n"; } ?>

Example 19-24 prints:

Monkey Singe Affe

19.10.3. Discussion

gettext is a set of tools that makes it easier for your application to produce multilingual messages. Compiling PHP with the --with-gettext option enables functions to retrieve the appropriate text from gettext-format message catalogs, and there are a number of external tools to edit the message catalogs.

With gettext, messages are divided into domains, and all messages for a particular domain are stored in the same file. bindtextdomain( ) tells gettext where to find the message catalog for a particular domain. A call to:

bindtextdomain('animals','/home/translator/custom/locale')

indicates that the message catalog for the animals domain in the en_US locale is in the file /home/translator/custom/locale/en_US/LC_MESSAGES/animals.mo.

The textdomain('animals') function sets the default domain to animals. Calling gettext( ) retrieves a message from the default domain. There are other functions, such as dgettext( ), that let you retrieve a message from a different domain. When gettext( ) (or dgettext( )) is called, it returns the appropriate message for the current locale. If there's no message in the catalog for the current locale that corresponds to the argument passed to it, gettext( ) (or dgettext( )) returns just its argument. As a result, if you haven't translated all your messages, your code prints out in English (or whatever your base language is) for those untranslated messages.

Setting the default domain with textdomain( ) makes each subsequent retrieval of a message from that domain more concise, because you just have to call gettext('Good morning') instead of dgettext('domain','Good morning'). However, if even gettext('Good morning') is too much typing, you can take advantage of an undocumented function alias: _( ) for gettext( ). Instead of gettext('Good morning'), use _('Good morning').

The gettext web site has helpful and detailed information for managing the information flow between programmers and translators and how to efficiently use gettext. It also includes information on other tools you can use to manage your message catalogs, such as a special GNU Emacs mode.

A downside to gettext that you should be aware of: it's not thread safe. If you use gettext in a multithreaded web server, you may run into problems where changing settings in one thread affects other threads.

19.10.4. See Also

Documentation on gettext at http://www.php.net/gettext; the gettext library at http://www.gnu.org/software/gettext/gettext.html. "Gettext," by Joao Prado Maia (http://www.onlamp.com/pub/a/php/2002/06/13/php.html) explores how to use GNU utilities such as xgettext and msgfmt to generate and maintain your own message catalogs.