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. |
|
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 Translations in cubicweb-tal template can also be done with TAL tags |
|
54 `i18n:content` and `i18n:replace`. |
|
55 |
|
56 .. note:: |
|
57 |
|
58 We dont need to mark the translation strings of entities/relations |
|
59 used by a particular application's schema as they are generated |
|
60 automatically. |
|
61 |
|
62 |
|
63 Handle the translation catalog |
|
64 ------------------------------ |
|
65 |
|
66 Once the internationalization is done in your application's code, you need |
|
67 to populate and update the translation catalog. Cubicweb provides the |
|
68 following commands for this purpose: |
|
69 |
|
70 |
|
71 * `i18nlibupdate` updates Cubicweb framework's translation |
|
72 catalogs. Unless you work on the framework development, you don't |
|
73 need to use this command. |
|
74 |
|
75 * `i18nupdate` updates the translation catalogs of *one particular |
|
76 component* (or of all components). After this command is |
|
77 executed you must update the translation files *.po* in the "i18n" |
|
78 directory of your template. This command will of course not remove |
|
79 existing translations still in use. |
|
80 |
|
81 * `i18ncompile` recompile the translation catalogs of *one particular |
|
82 instance* (or of all instances) after the translation catalogs of |
|
83 its components have been updated. This command is automatically |
|
84 called every time you create or update your instance. The compiled |
|
85 catalogs (*.mo*) are stored in the i18n/<lang>/LC_MESSAGES of |
|
86 application where `lang` is the language identifier ('en' or 'fr' |
|
87 for exemple). |
|
88 |
|
89 |
|
90 Example |
|
91 ``````` |
|
92 You have added and/or modified some translation strings in your application |
|
93 (after creating a new view or modifying the application's schema for exemple). |
|
94 To update the translation catalogs you need to do: |
|
95 |
|
96 1. `cubicweb-ctl i18nupdate <component>` |
|
97 2. Edit the <component>/xxx.po files and add missing translations (empty `msgstr`) |
|
98 3. `hg ci -m "updated i18n catalogs"` |
|
99 4. `cubicweb-ctl i18ncompile <myapplication>` |
|
100 |
|