The i18n module uses Python gettext to translate text. The first step
is to localize all your text strings, for example:
@turbogears.expose(html="index")
def index(self):
flash(_('Welcome to TurboGears'))
return dict()
You should then have for example the following files:
my_project/
locales/
messages.pot
en/
LC_MESSAGES/
messages.po
messages.mo
fi/
LC_MESSAGES/
messages.po
messages.mo
The Python tools pygettext.py and msgfmt.py (under Tools/i18n of your
Python distribution) are used to extract and format your text strings.
(Eventually they will be integrated with tg-admin). You can use these
tools to create your translated text strings. See
http://docs.python.org/lib/module-gettext.html for more information on
this. Basically the pygettext.py script creates a file called
<domain>.pot, which has entries like this:
msgid "Welcome to TurboGears"
msgstr ""
You then copy this file to each language in the file structure shown
above, renaming the file <domain>.po and adding your translations, for
example in my_project/locales/fi/LC_MESSAGES/messages.po:
msgid "Welcome to TurboGears"
msgstr "Tervetuloa TurboGearsiin"
NB: make sure the Content-Type line at the top is set correctly ! For
example:
"Content-Type: text/plain; charset=iso-8859-1\n"
You then have to run the msgfmt.py script on this .po file to create a
.mo file, which is used by gettext.
Instead of the standard gettext.gettext function, TurboGears uses a
modified gettext function which gets the user locale from the session.
If the session does not contain the user locale, the HTTP
Accept-Language header is checked, and failing that, the default locale
is used, which can be set in your configuration file as
i18n.defaultLocale. You can also pass the locale in the function, for
example:
_('Welcome to TurboGears', 'fi')
The _ function is an alias for gettext and is added to the builtins
namespace and so can be called from anywhere in your code.
In the present code text inside Kid templates can be handled by using
the following code:
<translate py:match="item.get('lang')" py:replace="translate(item,
'lang')" />
This will match any element with the lang attribute and replace the
text of the element, and any child elements, with the translated
version, for example:
<div lang="fi">Welcome to Turbogears</div>
is translated to <div lang="fi">Tervetuloa TurboGearsiin</div>
However I'd like to replace this code with a filter in the template, so
this boilerplate is unnecessary: you just set in your config file :
i18n.runTemplateFilter=True
and the text in the template will be translated according to the user
locale, although the "lang" attribute can still be used to override
this locale.
There are a few caveats here: first, template attributes are not
affected by the filter, so they have to be translated manually, e.g.:
<img py:attrs="caption=_('My logo')">
I really don't like this, so if any one has any good ideas let me know.
Of course, all attrs could be translated as well, but I'm not sure if
this might be too resource-intensive. Perhaps TAL:like i18n attributes
could be used instead.
Secondly, FormEncode returns untranslated strings, which then have to
be translated. I've added some suggestions for handling gettext on the
FormEncode mailing list, so that we can use TurboGears i18n seamlessly
with FormEncode.
Once the module is a bit more stable I'll get some documentation going.
BTW Elvelind, any feedback/comments ?
