|
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 |