author | Julien Jehannet <julien.jehannet@logilab.fr> |
Thu, 19 Feb 2009 12:09:01 +0100 | |
changeset 856 | fdd1743c57ce |
parent 288 | 487bcc269d50 |
child 1075 | 19fe9184a8bb |
permissions | -rw-r--r-- |
74
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
1 |
.. -*- coding: utf-8 -*- |
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
2 |
|
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
3 |
.. _internationalization: |
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
4 |
|
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
5 |
|
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
6 |
Internationalization |
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
7 |
==================== |
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
8 |
|
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
9 |
Cubicweb fully supports the internalization of it's content and interface. |
74
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
10 |
|
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
11 |
Cubicweb's interface internationalization is based on the translation project `GNU gettext`_. |
74
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
12 |
|
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
13 |
.. _`GNU gettext`: http://www.gnu.org/software/gettext/ |
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
14 |
|
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
15 |
Cubicweb' internalization involves two steps: |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
16 |
|
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
17 |
* in your Python code and cubicweb-tal templates : mark translatable strings |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
18 |
|
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
19 |
* in your application : handle the translation catalog |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
20 |
|
197
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
21 |
String internationalization |
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
22 |
--------------------------- |
74
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
23 |
|
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
24 |
In the Python code and cubicweb-tal templates translatable strings can be |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
25 |
marked in one of the following ways : |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
26 |
|
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
27 |
* by using the *built-in* function `_` :: |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
28 |
|
197
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
29 |
class PrimaryView(EntityView): |
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
30 |
"""the full view of an non final entity""" |
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
31 |
id = 'primary' |
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
32 |
title = _('primary') |
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
33 |
|
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
34 |
OR |
74
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
35 |
|
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
36 |
* by using the equivalent request's method :: |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
37 |
|
197
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
38 |
class NoResultView(EmptyRsetView): |
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
39 |
"""default view when no result has been found""" |
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
40 |
id = 'noresult' |
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
41 |
|
197
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
42 |
def call(self, **kwargs): |
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
43 |
self.w(u'<div class="searchMessage"><strong>%s</strong></div>\n' |
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
44 |
% self.req._('No result matching query')) |
74
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
45 |
|
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
46 |
The goal of the *built-in* function `_` is only **to mark the |
197
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
47 |
translatable strings**, it will only return the string to translate |
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
48 |
it-self, but not its translation. |
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
49 |
|
197
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
50 |
In the other hand the request's method `self.req._` is meant to retrieve the |
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
51 |
proper translation of translation strings in the requested language. |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
52 |
|
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
53 |
Translations in cubicweb-tal template can also be done with TAL tags |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
54 |
`i18n:content` and `i18n:replace`. |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
55 |
|
197
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
56 |
.. note:: |
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
57 |
|
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
58 |
We dont need to mark the translation strings of entities/relations |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
59 |
used by a particular application's schema as they are generated |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
60 |
automatically. |
74
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
61 |
|
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
62 |
|
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
63 |
Handle the translation catalog |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
64 |
------------------------------ |
74
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
65 |
|
197
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
66 |
Once the internationalization is done in your application's code, you need |
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
67 |
to populate and update the translation catalog. Cubicweb provides the |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
68 |
following commands for this purpose: |
74
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
69 |
|
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
70 |
|
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
71 |
* `i18nlibupdate` updates Cubicweb framework's translation |
197
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
72 |
catalogs. Unless you work on the framework development, you don't |
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
73 |
need to use this command. |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
74 |
|
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
75 |
* `i18nupdate` updates the translation catalogs of *one particular |
197
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
76 |
component* (or of all components). After this command is |
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
77 |
executed you must update the translation files *.po* in the "i18n" |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
78 |
directory of your template. This command will of course not remove |
197
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
79 |
existing translations still in use. |
74
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
80 |
|
197
1632e01a58a9
[doc] Translation to english.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
127
diff
changeset
|
81 |
* `i18ncompile` recompile the translation catalogs of *one particular |
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
82 |
instance* (or of all instances) after the translation catalogs of |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
83 |
its components have been updated. This command is automatically |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
84 |
called every time you create or update your instance. The compiled |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
85 |
catalogs (*.mo*) are stored in the i18n/<lang>/LC_MESSAGES of |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
86 |
application where `lang` is the language identifier ('en' or 'fr' |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
87 |
for exemple). |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
88 |
|
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
89 |
|
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
90 |
Example |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
91 |
``````` |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
92 |
You have added and/or modified some translation strings in your application |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
93 |
(after creating a new view or modifying the application's schema for exemple). |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
94 |
To update the translation catalogs you need to do: |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
95 |
|
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
96 |
1. `cubicweb-ctl i18nupdate <component>` |
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
97 |
2. Edit the <component>/xxx.po files and add missing translations (empty `msgstr`) |
74
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
98 |
3. `hg ci -m "updated i18n catalogs"` |
79
fd20ff4e8fa0
english translation
Katia Saurfelt <katia.saurfelt@logilab.fr>
parents:
74
diff
changeset
|
99 |
4. `cubicweb-ctl i18n compile <myapplication>` |
74
9a9fe515934d
[doc] reuse the lax book
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents:
diff
changeset
|
100 |