21. INTERNATIONALIZATION AND LOCALIZATION

After assigning _ to the result of a TranslationStringFactory(), the subsequent result of calling _ will be a TranslationString instance. Even though a domain value was not passed to _ (as would have been necessary if the TranslationString constructor were used instead of a translation string factory), the domain attribute of the resulting translation string will be pyramid. As a result, the previous code example is completely equivalent (except for spelling) to:

You can set up your own translation string factory much like the one provided above by using the TranslationStringFactory class. For example, if you’d like to create a translation string factory which presets the domain value of generated translation strings to form, you’d do something like this:

Creating a unique domain for your application via a translation string factory is best practice. Using your own unique translation domain allows another person to reuse your application without needing to merge your translation files with his own. Instead, he can just include your package’s translation directory via the pyramid.config.Configurator.add_translation_dirs() method.

latex-note.png

For people familiar with Zope internationalization, a TranslationStringFactory is a lot like a zope.i18nmessageid.MessageFactory object. It is not a subclass, however.

21.2 Working With gettext Translation Files

The basis of Pyramid translation services is GNU gettext. Once your application source code files and templates are marked up with translation markers, you can work on translations by creating various kinds of gettext files.

232

21.2. WORKING WITH GETTEXT TRANSLATION FILES

latex-note.png

The steps a developer must take to work with gettext message catalog files within a Pyramid application are very similar to the steps a Pylons developer must take to do the same. See the Pylons internationalization documentation for more information.

GNU gettext uses three types of files in the translation framework, .pot files, .po files and .mo files.

.pot (Portable Object Template) files

A .pot file is created by a program which searches through your project’s source code and which picks out every message identifier passed to one of the _() functions (eg. translation string constructions). The list of all message identifiers is placed into a .pot file, which serves as a template for creating .po files.

.po (Portable Object) files

The list of messages in a .pot file are translated by a human to a particular language; the result is saved as a .po file.

.mo (Machine Object) files

A .po file is turned into a machine-readable binary file, which is the .mo file. Compiling the translations to machine code makes the localized program run faster.

The tools for working with gettext translation files related to a Pyramid application is Babel and Lingua. Lingua is a Babel extension that provides support for scraping i18n references out of Python and Chameleon files.

21.2.1 Installing Babel and Lingua

In order for the commands related to working with gettext translation files to work properly, you will need to have Babel and Lingua installed into the same environment in which Pyramid is installed.

Installation on UNIX

If the virtualenv into which you’ve installed your Pyramid application lives in /my/virtualenv, you can install Babel and Lingua like so:

233

21. INTERNATIONALIZATION AND LOCALIZATION

$ cd /my/virtualenv

$ bin/easy_install Babel lingua

Installation on Windows

If the virtualenv into which you’ve installed your Pyramid application lives in C:\my\virtualenv, you can install Babel and Lingua like so:

C> cd \my\virtualenv

C> Scripts\easy_install Babel lingua

Changing the setup.py

You need to add a few boilerplate lines to your application’s setup.py file in order to properly generate gettext files from your application.

latex-note.png

See Creating a Pyramid Project to learn about about the composition of an application’s setup.py file.

In particular, add the Babel and lingua distributions to the install_requires list and insert a set of references to Babel message extractors within the call to setuptools.setup() inside your application’s setup.py file:

1setup(name="mypackage",

2# ...

3install_requires = [

8message_extractors = { ’.’: [

234

21.2. WORKING WITH GETTEXT TRANSLATION FILES

The message_extractors stanza placed into the setup.py file causes the Babel message catalog extraction machinery to also consider *.pt files when doing message id extraction.

21.2.2 Extracting Messages from Code and Templates

Once Babel and Lingua are installed and your application’s setup.py file has the correct message extractor references, you may extract a message catalog template from the code and Chameleon templates which reside in your Pyramid application. You run a setup.py command to extract the messages:

$ cd /place/where/myapplication/setup.py/lives $ mkdir -p myapplication/locale

$ $myvenv/bin/python setup.py extract_messages

The message catalog .pot template will end up in:

myapplication/locale/myapplication.pot.

Translation Domains

The name myapplication above in the filename myapplication.pot denotes the translation domain of the translations that must be performed to localize your application. By default, the translation domain is the project name of your Pyramid application.

To change the translation domain of the extracted messages in your project, edit the setup.cfg file of your application, The default setup.cfg file of a pcreate -generated Pyramid application has stanzas in it that look something like the following:

235