[doc] Renaming for advanced thematic.
.. -*- coding: utf-8 -*-
.. _internationalization:
Internationalization
====================
Cubicweb fully supports the internalization of it's content and interface.
Cubicweb's interface internationalization is based on the translation project `GNU gettext`_.
.. _`GNU gettext`: http://www.gnu.org/software/gettext/
Cubicweb' internalization involves two steps:
* in your Python code and cubicweb-tal templates : mark translatable strings
* in your application : handle the translation catalog
String internationalization
---------------------------
In the Python code and cubicweb-tal templates translatable strings can be
marked in one of the following ways :
* by using the *built-in* function `_` ::
class PrimaryView(EntityView):
"""the full view of an non final entity"""
id = 'primary'
title = _('primary')
OR
* by using the equivalent request's method ::
class NoResultView(EmptyRsetView):
"""default view when no result has been found"""
id = 'noresult'
def call(self, **kwargs):
self.w(u'<div class="searchMessage"><strong>%s</strong></div>\n'
% self.req._('No result matching query'))
The goal of the *built-in* function `_` is only **to mark the
translatable strings**, it will only return the string to translate
it-self, but not its translation.
In the other hand the request's method `self.req._` is meant to retrieve the
proper translation of translation strings in the requested language.
Translations in cubicweb-tal template can also be done with TAL tags
`i18n:content` and `i18n:replace`.
.. note::
We dont need to mark the translation strings of entities/relations
used by a particular application's schema as they are generated
automatically.
Handle the translation catalog
------------------------------
Once the internationalization is done in your application's code, you need
to populate and update the translation catalog. Cubicweb provides the
following commands for this purpose:
* `i18nlibupdate` updates Cubicweb framework's translation
catalogs. Unless you work on the framework development, you don't
need to use this command.
* `i18nupdate` updates the translation catalogs of *one particular
component* (or of all components). After this command is
executed you must update the translation files *.po* in the "i18n"
directory of your template. This command will of course not remove
existing translations still in use.
* `i18ncompile` recompile the translation catalogs of *one particular
instance* (or of all instances) after the translation catalogs of
its components have been updated. This command is automatically
called every time you create or update your instance. The compiled
catalogs (*.mo*) are stored in the i18n/<lang>/LC_MESSAGES of
application where `lang` is the language identifier ('en' or 'fr'
for exemple).
Example
```````
You have added and/or modified some translation strings in your application
(after creating a new view or modifying the application's schema for exemple).
To update the translation catalogs you need to do:
1. `cubicweb-ctl i18nupdate <component>`
2. Edit the <component>/xxx.po files and add missing translations (empty `msgstr`)
3. `hg ci -m "updated i18n catalogs"`
4. `cubicweb-ctl i18n compile <myapplication>`