wiki:Internationalization
Warning: Can't synchronize with repository "(default)" (Unsupported version control system "svn": No module named svn). Look in the Trac log for more information.

Version 4 (modified by anonymous, 9 years ago) (diff)

--

To internationalize your application, you have to make sure of the following steps:

1 That you mark your text strings using the _() function.

2 That you have create message catalogs in the right directory structure for all your text strings and supported languages.

3 That any date or number strings are formatted using the turbogears.i18n formatting functions.

1. Mark your text strings with _()

All text strings you want translated should be included in the _() function. This function is builtin to turbogears, so you don't need to import it specifically into your module, if you have already called "import turbogears".

For example: import turbogears from turbogears import controllers

class Controller(controllers.Root):

@turbogears.expose(html="myapp.templates.welcome.kid") def index(self):

return dict(message=_("Welcome"))

If you want to explicitly pass in the locale in the _() call, you can do this:

print _("Welcome", "de")

Handling text strings in Kid templates is somewhat easier. If you set the cherrypy configuration setting "i18n.runTemplateFilter" to True, all text inside your Kid templates will be passed through _() automatically. The user locale (see below) can be overriden in your template by using the "lang" attribute, for example:

<div>

<p>Welcome</p> <p lang="de">Welcome</p>

</div>

The first "Welcome" will be translated using the user locale setting, the second using the German locale. Assuming your user locale is English, you would see:

<div>

<p>Welcome</p> <p lang="de">Willkommen</p>

</div>

However, attribute values are not translated and so have to be handled explicitly by using the _() call:

<img py:attrs="src=_('flag_icon_gb.bmp')" />

Note that text inside widget templates, etc. will also be translated.

2. Create your message catalogs

Use the Python scripts in tools/i18n, pygettext.py and msgfmt.py, to create your .po file and .mo files. For details on using this tool and creating your message catalogs, see http://docs.python.org/lib/module-gettext.html. Basically you should have a directory structure like this:

myapp/

locales/

messages.pot en/

LC_MESSAGES/

messages.po

messages.mo

de/

LC_MESSAGES/

messages.po

messages.mo

Eventually we should have tools in tg-admin to handle text extraction and compilation.

By default, _() looks for subdirectory "locales" and domain "messages" in your project directory. You can override these settings in your config file by setting "i18n.localeDir" and "i18n.domain" respectively.

If a language file(.mo) is not found, the _() call will return the plain text string.

3. Localize your dates and numbers

The i18n package has a number of useful functions for handling date, location and number formats. Data for these formats are located in LDML (Locale Data Markup Language) files under turbogears/i18n/data; if you wish to use your own files, set the config setting i18n.dataDir. When searching for a format, the full locale name (e.g. en_CA for Canadian English) is used; if no matching format is found then the fallback locale(e.g. en for English) is used. These functions are found in i18n/formats.py. They include:

format_date: returns a localized date string get_countries: returns a list of tuples, with the international country code and localized name (e.g. ("AU", "Australia")) format_currency: returns a formatted currency value (e.g. in German 56.89 > 56,89)

Finding the user locale

The default locale function, _get_locale, can be overriden by your own locale using the config setting "i18n.getLocale". This default function finds the locale setting in the following order:

1 By looking for a session value. By default this is "locale", but can be changed in the config setting "i18n.sessionKey".

2 By looking in the HTTP Accept-Language header for the most preferred language.

3 By using the default locale (config setting "i18n.defaultLocale", by default "en").