Internationalization¶
Table of Contents
A practical example¶
Supporting I18N in your module is very simple. All you need is an instance of a translator (an instance of an object that implements Erebot_Interface_I18n) for the module. A translator for the module is automatically created along instances of your module.
Once equipped with a translator, just call its gettext() method, passing the string to translate to it. Therefore, translating a string is as simple as the following snippet:
<?php
$translator = $this->getTranslator($chan);
$translator->gettext('This text will be translated');
?>
Module developpers may also be interested in the other methods provided by the translator object, presented in the API documentation for that class.
Managing translations¶
In the previous section, we saw how to integrate strings that will be translated. So... how does Erebot finds out the correct translation?
There is another special file in data/i18n/module.po where module is the name of your module (eg. Erebot_Module_XYZ). This file uses the gettext format and lists all messages marked as requiring a translation (as extracted from your source code when running phing i18n).
Also, every Erebot module contains a set of translations in data/i18n/locale/LC_MESSAGES/module.po, where locale is some locale identifier, expressed using the following format: xx_YY (where xx is the ISO 639-1 code for the language [1] and yy is the code for the country, eg. en_US) and module is the name of your module (eg. Erebot_Module_XYZ). Those files use the same format as the previous file and provide the translations for the messages listed in data/i18n/module.po.
To ease management of the translations, and especially the PO files (also called “catalogs”), a few tools are provided by Erebot as phing targets. These tools are discussed below.
| [1] | See http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes |
Extracting strings marked for translation¶
The extract_messages target can be used to parse the code of your module and extract strings marked for translation. This will write out every string marked for translation into data/i18n/module.po. Example:
$ phing extract_messages
Adding translations for a new locale¶
Translations for a new locale can be added by using the init_catalog target and passing a locale parameter, like so:
# Creates a new translation catalog for the "de_DE" locale (german).
$ phing init_catalog -Dlocale=de_DE
Updating existing catalogs¶
Updating the catalogs is quite simple, just use the update_catalog target:
$ phing update_catalog
Compiling the catalogs¶
Last but not least, the catalog files cannot be used directly by the bot. You first need to compile them using the compile_catalog phing target:
$ phing compile_catalog
This will generate MO files for the miscellaneous PO files described above.
Plurals¶
Correct pluralization of sentences is a big challenge when dealing with i18n.
Warning
Even though the gettext family of tools has some (incomplete, at least from my point of view) support for plurals, the original feature from gettext is not used by Erebot.
Erebot handles plurals in an elegant way, using a special set of markup in the styling API. Readers may be interested in the documentation on styling for more information on plurals support.