1 .. -*- coding: utf-8 -*-

     2 

     3 .. _internationalisation:

     4 

     5 

     6 Internationalisation

     7 ---------------------

     8 

     9 Cubicweb fully supports the internalization of it's content and interface.

    10 

    11 Cubicweb's interface internationalization is based on the translation project `GNU gettext`_.

    12 

    13 .. _`GNU gettext`: http://www.gnu.org/software/gettext/

    14 

    15 Cubicweb' internalization involves two steps:

    16 

    17 * in your Python code and cubicweb-tal templates : mark translatable strings

    18 

    19 * in your application : handle the translation catalog

    20 

    21 String internationalization

    22 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

    23 

    24 In the Python code and cubicweb-tal templates translatable strings can be

    25 marked in one of the following ways :

    26 

    27  * by using the *built-in* function `_` ::

    28 

    29      class PrimaryView(EntityView):

    30          """the full view of an non final entity"""

    31          id = 'primary'

    32          title = _('primary')

    33 

    34   OR

    35 

    36  * by using the equivalent request's method ::

    37 

    38      class NoResultView(EmptyRsetView):

    39          """default view when no result has been found"""

    40          id = 'noresult'

    41 

    42          def call(self, **kwargs):

    43              self.w(u'<div class="searchMessage"><strong>%s</strong></div>\n'

    44                  % self.req._('No result matching query'))

    45 

    46 The goal of the *built-in* function `_` is only **to mark the

    47 translatable strings**, it will only return the string to translate

    48 it-self, but not its translation (it's actually refering to the `unicode` builtin).

    49 

    50 In the other hand the request's method `self.req._` is meant to retrieve the

    51 proper translation of translation strings in the requested language.

    52 

    53 Finally you can also use the `__` attribute of request object to get a

    54 translation for a string *which should not itself added to the catalog*,

    55 usually in case where the actual msgid is created by string interpolation ::

    56 

    57   self.req.__('This %s' % etype)

    58 

    59 In this example `req.__` is used instead of `req._` so we don't have 'This %s' in

    60 messages catalogs.

    61 

    62 

    63 Translations in cubicweb-tal template can also be done with TAL tags

    64 `i18n:content` and `i18n:replace`.

    65 

    66 .. note::

    67 

    68    We dont need to mark the translation strings of entities/relations

    69    used by a particular application's schema as they are generated

    70    automatically.

    71 

    72 

    73 Handle the translation catalog

    74 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    75 

    76 Once the internationalization is done in your application's code, you need

    77 to populate and update the translation catalog. Cubicweb provides the

    78 following commands for this purpose:

    79 

    80 

    81 * `i18nlibupdate` updates Cubicweb framework's translation

    82   catalogs. Unless you work on the framework development, you don't

    83   need to use this command.

    84 

    85 * `i18nupdate` updates the translation catalogs of *one particular

    86   component* (or of all components). After this command is

    87   executed you must update the translation files *.po* in the "i18n"

    88   directory of your template. This command will of course not remove

    89   existing translations still in use.

    90 

    91 * `i18ncompile` recompile the translation catalogs of *one particular

    92   instance* (or of all instances) after the translation catalogs of

    93   its components have been updated. This command is automatically

    94   called every time you create or update your instance. The compiled

    95   catalogs (*.mo*) are stored in the i18n/<lang>/LC_MESSAGES of

    96   application where `lang` is the language identifier ('en' or 'fr'

    97   for exemple).

    98 

    99 

   100 Example

   101 ```````

   102 You have added and/or modified some translation strings in your application

   103 (after creating a new view or modifying the application's schema for exemple).

   104 To update the translation catalogs you need to do:

   105 

   106 1. `cubicweb-ctl i18nupdate <component>`

   107 2. Edit the <component>/xxx.po  files and add missing translations (empty `msgstr`)

   108 3. `hg ci -m "updated i18n catalogs"`

   109 4. `cubicweb-ctl i18ncompile <myapplication>`

   110