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 9 (modified by michele, 9 years ago) (diff)

better formatting

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  gettext module. 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").

Encoding

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