diff -r fd8751c3f3ee -r a721966779be doc/book/en/development/devweb/internationalization.rst
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/book/en/development/devweb/internationalization.rst Thu May 07 16:33:22 2009 +0200
@@ -0,0 +1,110 @@
+.. -*- coding: utf-8 -*-
+
+.. _internationalisation:
+
+
+Internationalisation
+---------------------
+
+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'
%s
\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 (it's actually refering to the `unicode` builtin).
+
+In the other hand the request's method `self.req._` is meant to retrieve the
+proper translation of translation strings in the requested language.
+
+Finally you can also use the `__` attribute of request object to get a
+translation for a string *which should not itself added to the catalog*,
+usually in case where the actual msgid is created by string interpolation ::
+
+ self.req.__('This %s' % etype)
+
+In this example `req.__` is used instead of `req._` so we don't have 'This %s' in
+messages catalogs.
+
+
+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//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 `
+2. Edit the /xxx.po files and add missing translations (empty `msgstr`)
+3. `hg ci -m "updated i18n catalogs"`
+4. `cubicweb-ctl i18ncompile `
+