Internationalizing your application

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:

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

Handling text strings in Kid templates is somewhat easier. If you set the cherrypy configuration setting i18n.run_template_filter 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:

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:

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

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

2. Create your message catalogs

TurboGears ships with a suite of tools that help you to build and maintain message catalogs. One is "admi18n" from the Toolbox and another is part of tg-admin command.

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 is contained in Python modules under turbogears/i18n/data, for example the module for Danish is turbogears/i18n/data/da.py. The functions 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").

Encoding

The _() and all formatting functions return unicode strings.

Handling international (UTF-8) form data

TurboGears automatically sets correct charset info in Content-Type HTTP header and it just works (usually).

If you prefer you may add the following to your HTML (kid) templates to enforce it:

When the browser sends unicode data in a request (via a textarea, for example), CherryPy gives you the string as is.

By default TurboGears uses a CherryPy filter to decode all of the incoming request parameters into unicode strings using a given encoding. In most cases you would just keep it that way.

To get Kid to work, you may want to tweak kid.encoding option (which defaults to utf8) though using utf-8 is advised.