6.23.3 Internationalizing your programs and modules

Internationalization (I18N) refers to the operation by which a program is made aware of multiple languages. Localization (L10N) refers to the adaptation of your program, once internationalized, to the local language and cultural habits. In order to provide multilingual messages for your Python programs, you need to take the following steps:

prepare your program or module by specially marking translatable strings
run a suite of tools over your marked files to generate raw messages catalogs
create language specific translations of the message catalogs
use the gettext module so that message strings are properly translated

In order to prepare your code for I18N, you need to look at all the strings in your files. Any string that needs to be translated should be marked by wrapping it in _('...') - i.e. a call to the function _(). For example:

filename = 'mylog.txt'
message = _('writing a log message')
fp = open(filename, 'w')
fp.write(message)
fp.close()

In this example, the string 'writing a log message' is marked as a candidate for translation, while the strings 'mylog.txt' and 'w' are not.

The GNU gettext package provides a tool, called xgettext, that scans C and C++ source code looking for these specially marked strings. xgettext generates what are called .pot files, essentially structured human readable files which contain every marked string in the source code. These .pot files are copied and handed over to human translators who write language-specific versions for every supported natural language.

For I18N Python programs however, xgettext won't work; it doesn't understand the myriad of string types support by Python. The standard Python distribution provides a tool called pygettext that does though (found in the Tools/i18n/ directory).^6.3 This is a command line script that supports a similar interface as xgettext; see its documentation for details. Once you've used pygettext to create your .pot files, you can use the standard GNU gettext tools to generate your machine-readable .mo files, which are readable by the GNUTranslations class.

How you use the gettext module in your code depends on whether you are internationalizing your entire application or a single module.

Footnotes

... directory).^6.3: François Pinard has written a program called xpot which does a similar job. It is available as part of his po-utils package at http://www.iro.umontreal.ca/contrib/po-utils/HTML .

Subsections

See About this document... for information on suggesting changes.