doc/book/devweb/internationalization.rst
author Philippe Pepiot <philippe.pepiot@logilab.fr>
Wed, 18 Mar 2020 13:18:04 +0100
branch3.27
changeset 12919 85284f028266
parent 12582 2b0a3f2607f0
permissions -rw-r--r--
[pkg] version 3.27.3
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     1
.. -*- coding: utf-8 -*-
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     2
2544
282261b26774 [doc] fixed some dangling internal links
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2539
diff changeset
     3
.. _internationalization:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     4
2544
282261b26774 [doc] fixed some dangling internal links
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2539
diff changeset
     5
Internationalization
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     6
---------------------
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     7
2539
0f26a76b0348 [doc] some more rewriting
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2535
diff changeset
     8
Cubicweb fully supports the internalization of its content and interface.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
     9
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    10
Cubicweb's interface internationalization is based on the translation project `GNU gettext`_.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    11
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    12
.. _`GNU gettext`: http://www.gnu.org/software/gettext/
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    13
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    14
Cubicweb' internalization involves two steps:
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    15
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    16
* in your Python code and cubicweb-tal templates : mark translatable strings
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    17
5137
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
    18
* in your instance : handle the translation catalog, edit translations
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    19
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    20
String internationalization
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    21
~~~~~~~~~~~~~~~~~~~~~~~~~~~
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    22
3992
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
    23
User defined string
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
    24
```````````````````
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
    25
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    26
In the Python code and cubicweb-tal templates translatable strings can be
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    27
marked in one of the following ways :
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    28
8032
bcb87336c7d2 [doc] fix most of ReST compilation errors and warnings
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 5394
diff changeset
    29
 * by using the *built-in* function `_`:
bcb87336c7d2 [doc] fix most of ReST compilation errors and warnings
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 5394
diff changeset
    30
bcb87336c7d2 [doc] fix most of ReST compilation errors and warnings
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 5394
diff changeset
    31
   .. sourcecode:: python
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    32
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    33
     class PrimaryView(EntityView):
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    34
         """the full view of an non final entity"""
4751
1a9d2c3c7f0c [book] more id -> __regid__
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4442
diff changeset
    35
         __regid__ = 'primary'
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    36
         title = _('primary')
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    37
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    38
  OR
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    39
8032
bcb87336c7d2 [doc] fix most of ReST compilation errors and warnings
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 5394
diff changeset
    40
 * by using the equivalent request's method:
bcb87336c7d2 [doc] fix most of ReST compilation errors and warnings
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 5394
diff changeset
    41
bcb87336c7d2 [doc] fix most of ReST compilation errors and warnings
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 5394
diff changeset
    42
   .. sourcecode:: python
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    43
5222
ed6905d98a5e [doc/book] more flesh to views/primary view
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 5137
diff changeset
    44
     class NoResultView(View):
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    45
         """default view when no result has been found"""
4751
1a9d2c3c7f0c [book] more id -> __regid__
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4442
diff changeset
    46
         __regid__ = 'noresult'
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    47
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    48
         def call(self, **kwargs):
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    49
             self.w(u'<div class="searchMessage"><strong>%s</strong></div>\n'
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4255
diff changeset
    50
                 % self._cw._('No result matching query'))
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    51
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    52
The goal of the *built-in* function `_` is only **to mark the
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    53
translatable strings**, it will only return the string to translate
3258
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2544
diff changeset
    54
itself, but not its translation (it's actually another name for the
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2544
diff changeset
    55
`unicode` builtin).
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    56
5137
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
    57
In the other hand the request's method `self._cw._` is also meant to
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
    58
retrieve the proper translation of translation strings in the
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
    59
requested language.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    60
12581
0951dcdcfd5a [doc] Clarify sentences
Noe Gaumont <ngaumont@logilab.fr>
parents: 12580
diff changeset
    61
Finally you can also use the `__` (two underscores) attribute of request object to get a
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    62
translation for a string *which should not itself added to the catalog*,
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    63
usually in case where the actual msgid is created by string interpolation ::
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    64
4437
21f2e01fdd6a update exemples using the 3.6 api and add/fix some sections (schema, vreg, talk about CW_MODE in concepts...). So much to do :'(
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 4255
diff changeset
    65
  self._cw.__('This %s' % etype)
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    66
12580
f97eba3156c0 [doc] Fix format and typo
Noe Gaumont <ngaumont@logilab.fr>
parents: 11735
diff changeset
    67
In this example `._cw.__` is used instead of `._cw._` so we don't have 'This %s' in
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    68
messages catalogs.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    69
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    70
Translations in cubicweb-tal template can also be done with TAL tags
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    71
`i18n:content` and `i18n:replace`.
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    72
12581
0951dcdcfd5a [doc] Clarify sentences
Noe Gaumont <ngaumont@logilab.fr>
parents: 12580
diff changeset
    73
If you need to mark other messages as translatable,
12582
2b0a3f2607f0 [doc] add a reference to static-messages.pot usage
Noe Gaumont <ngaumont@logilab.fr>
parents: 12581
diff changeset
    74
you can create a file named `i18n/static-messages.pot`, see for example :ref:`translate-application-cube`.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
    75
5137
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
    76
You could put there messages not found in the python sources or
12581
0951dcdcfd5a [doc] Clarify sentences
Noe Gaumont <ngaumont@logilab.fr>
parents: 12580
diff changeset
    77
overrides some messages that are in cubes used in the dependencies.
5137
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
    78
3992
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
    79
Generated string
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
    80
````````````````
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
    81
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
    82
We do not need to mark the translation strings of entities/relations used by a
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
    83
particular instance's schema as they are generated automatically. String for
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
    84
various actions are also generated.
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
    85
8032
bcb87336c7d2 [doc] fix most of ReST compilation errors and warnings
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 5394
diff changeset
    86
For exemple the following schema:
3992
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
    87
8032
bcb87336c7d2 [doc] fix most of ReST compilation errors and warnings
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 5394
diff changeset
    88
.. sourcecode:: python
bcb87336c7d2 [doc] fix most of ReST compilation errors and warnings
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 5394
diff changeset
    89
bcb87336c7d2 [doc] fix most of ReST compilation errors and warnings
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 5394
diff changeset
    90
bcb87336c7d2 [doc] fix most of ReST compilation errors and warnings
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 5394
diff changeset
    91
  class EntityA(EntityType):
5137
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
    92
      relation_a2b = SubjectRelation('EntityB')
3992
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
    93
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
    94
  class EntityB(EntityType):
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
    95
      pass
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
    96
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
    97
May generate the following message ::
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
    98
5137
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
    99
  add EntityA relation_a2b EntityB subject
3992
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
   100
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
   101
This message will be used in views of ``EntityA`` for creation of a new
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
   102
``EntityB`` with a preset relation ``relation_a2b`` between the current
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
   103
``EntityA`` and the new ``EntityB``. The opposite message ::
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
   104
5137
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   105
  add EntityA relation_a2b EntityB object
3992
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
   106
4255
9d9400cb3f8c update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3992
diff changeset
   107
Is used for similar creation of an ``EntityA`` from a view of ``EntityB``. The
9d9400cb3f8c update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3992
diff changeset
   108
title of they respective creation form will be ::
9d9400cb3f8c update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3992
diff changeset
   109
9d9400cb3f8c update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3992
diff changeset
   110
  creating EntityB (EntityA %(linkto)s relation_a2b EntityB)
9d9400cb3f8c update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3992
diff changeset
   111
9d9400cb3f8c update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3992
diff changeset
   112
  creating EntityA (EntityA relation_a2b %(linkto)s EntityA)
3992
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
   113
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
   114
In the translated string you can use ``%(linkto)s`` for reference to the source
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
   115
``entity``.
4c98f0e28429 update i18n doc
Pierre-Yves David <pierre-yves.david@logilab.fr>
parents: 3581
diff changeset
   116
5137
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   117
Handling the translation catalog
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   118
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   119
2476
1294a6bdf3bf application -> instance where it makes sense
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1898
diff changeset
   120
Once the internationalization is done in your code, you need to populate and
1294a6bdf3bf application -> instance where it makes sense
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1898
diff changeset
   121
update the translation catalog. Cubicweb provides the following commands for this
1294a6bdf3bf application -> instance where it makes sense
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1898
diff changeset
   122
purpose:
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   123
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   124
1898
39b37f90a8a4 [cw-ctl] rename i18n commands (see #342889)
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1714
diff changeset
   125
* `i18ncubicweb` updates Cubicweb framework's translation
3258
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2544
diff changeset
   126
  catalogs. Unless you actually work on the framework itself, you
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2544
diff changeset
   127
  don't need to use this command.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   128
5137
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   129
* `i18ncube` updates the translation catalogs of *one particular cube*
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   130
  (or of all cubes). After this command is executed you must update
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   131
  the translation files *.po* in the "i18n" directory of your
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   132
  cube. This command will of course not remove existing translations
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   133
  still in use. It will mark unused translation but not remove them.
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   134
3258
6536ee4f37f7 update the documentation
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 2544
diff changeset
   135
* `i18ninstance` recompiles the translation catalogs of *one particular
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   136
  instance* (or of all instances) after the translation catalogs of
2476
1294a6bdf3bf application -> instance where it makes sense
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1898
diff changeset
   137
  its cubes have been updated. This command is automatically
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   138
  called every time you create or update your instance. The compiled
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   139
  catalogs (*.mo*) are stored in the i18n/<lang>/LC_MESSAGES of
2476
1294a6bdf3bf application -> instance where it makes sense
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1898
diff changeset
   140
  instance where `lang` is the language identifier ('en' or 'fr'
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   141
  for exemple).
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   142
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   143
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   144
Example
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   145
```````
5137
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   146
2476
1294a6bdf3bf application -> instance where it makes sense
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1898
diff changeset
   147
You have added and/or modified some translation strings in your cube
1294a6bdf3bf application -> instance where it makes sense
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1898
diff changeset
   148
(after creating a new view or modifying the cube's schema for exemple).
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   149
To update the translation catalogs you need to do:
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   150
2476
1294a6bdf3bf application -> instance where it makes sense
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1898
diff changeset
   151
1. `cubicweb-ctl i18ncube <cube>`
12580
f97eba3156c0 [doc] Fix format and typo
Noe Gaumont <ngaumont@logilab.fr>
parents: 11735
diff changeset
   152
2. Edit the `<cube>/i18n/xxx.po` files and add missing translations (those with an empty `msgstr`)
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   153
3. `hg ci -m "updated i18n catalogs"`
2476
1294a6bdf3bf application -> instance where it makes sense
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 1898
diff changeset
   154
4. `cubicweb-ctl i18ninstance <myinstance>`
1714
a721966779be new book layout, do not compile yet
sylvain.thenault@logilab.fr
parents:
diff changeset
   155
11735
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   156
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   157
Customizing the messages extraction process
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   158
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   159
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   160
The messages extraction performed by the ``i18ncommand`` collects messages
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   161
from a few different sources:
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   162
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   163
- the schema and application definition (entity names, docstrings,
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   164
  help messages, uicfg),
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   165
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   166
- the source files:
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   167
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   168
  - ``i18n:content`` or ``i18n:replace`` directives from TAL files (with ``.pt`` extension),
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   169
  - strings prefixed by an underscore (``_``) in python files,
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   170
  - strings with double quotes prefixed by an underscore in javascript files.
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   171
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   172
The source files are collected by walking through the cube directory,
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   173
but ignoring a few directories like ``.hg``, ``.tox``, ``test`` or
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   174
``node_modules``.
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   175
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   176
If you need to customize this behaviour in your cube, you have to
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   177
extend the ``cubicweb.devtools.devctl.I18nCubeMessageExtractor``. The
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   178
example below will collect strings from ``jinja2`` files and ignore
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   179
the ``static`` directory during the messages collection phase::
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   180
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   181
  # mymodule.py
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   182
  from cubicweb.devtools import devctl
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   183
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   184
  class MyMessageExtractor(devctl.I18nCubeMessageExtractor):
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   185
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   186
      blacklist = devctl.I18nCubeMessageExtractor | {'static'}
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   187
      formats = devctl.I18nCubeMessageExtractor.formats + ['jinja2']
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   188
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   189
      def collect_jinja2(self):
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   190
          return self.find('.jinja2')
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   191
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   192
      def extract_jinja2(self, files):
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   193
          return self._xgettext(files, output='jinja.pot',
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   194
                                extraopts='-L python --from-code=utf-8')
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   195
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   196
Then, you'll have to register it with a ``cubicweb.i18ncube`` entry point
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   197
in your cube's setup.py::
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   198
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   199
  setup(
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   200
      # ...
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   201
      entry_points={
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   202
          # ...
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   203
          'cubicweb.i18ncube': [
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   204
              'mycube=cubicweb_mycube.mymodule:MyMessageExtractor',
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   205
          ],
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   206
      },
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   207
      # ...
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   208
  )
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   209
7a170207acbf [devtools] make i18ncube customizable in a cube
Adrien Di Mascio <Adrien.DiMascio@logilab.fr>
parents: 11337
diff changeset
   210
5137
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   211
Editing po files
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   212
~~~~~~~~~~~~~~~~
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   213
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   214
Using a PO aware editor
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   215
````````````````````````
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   216
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   217
Many tools exist to help maintain .po (PO) files. Common editors or
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   218
development environment provides modes for these. One can also find
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   219
dedicated PO files editor, such as `poedit`_.
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   220
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   221
.. _`poedit`:  http://www.poedit.net/
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   222
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   223
While usage of such a tool is commendable, PO files are perfectly
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   224
editable with a (unicode aware) plain text editor. It is also useful
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   225
to know their structure for troubleshooting purposes.
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   226
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   227
Structure of a PO file
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   228
``````````````````````
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   229
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   230
In this section, we selectively quote passages of the `GNU gettext`_
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   231
manual chapter on PO files, available there::
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   232
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   233
 http://www.gnu.org/software/hello/manual/gettext/PO-Files.html
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   234
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   235
One PO file entry has the following schematic structure::
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   236
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   237
     white-space
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   238
     #  translator-comments
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   239
     #. extracted-comments
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   240
     #: reference...
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   241
     #, flag...
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   242
     #| msgid previous-untranslated-string
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   243
     msgid untranslated-string
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   244
     msgstr translated-string
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   245
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   246
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   247
A simple entry can look like this::
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   248
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   249
     #: lib/error.c:116
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   250
     msgid "Unknown system error"
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   251
     msgstr "Error desconegut del sistema"
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   252
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   253
It is also possible to have entries with a context specifier. They
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   254
look like this::
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   255
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   256
     white-space
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   257
     #  translator-comments
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   258
     #. extracted-comments
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   259
     #: reference...
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   260
     #, flag...
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   261
     #| msgctxt previous-context
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   262
     #| msgid previous-untranslated-string
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   263
     msgctxt context
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   264
     msgid untranslated-string
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   265
     msgstr translated-string
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   266
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   267
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   268
The context serves to disambiguate messages with the same
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   269
untranslated-string. It is possible to have several entries with the
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   270
same untranslated-string in a PO file, provided that they each have a
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   271
different context. Note that an empty context string and an absent
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   272
msgctxt line do not mean the same thing.
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   273
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   274
Contexts and CubicWeb
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   275
`````````````````````
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   276
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   277
CubicWeb PO files have both non-contextual and contextual msgids.
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   278
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   279
Contextual entries are automatically used in some cases. For instance,
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   280
entity.dc_type(), eschema.display_name(req) or display_name(etype,
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   281
req, form, context) methods/function calls will use them.
efc280ad9898 [doc/book] enhance i18n section #656191
Aurelien Campeas <aurelien.campeas@logilab.fr>
parents: 4751
diff changeset
   282
12580
f97eba3156c0 [doc] Fix format and typo
Noe Gaumont <ngaumont@logilab.fr>
parents: 11735
diff changeset
   283
It is also possible to explicitly use a context with `_cw.pgettext(context,
f97eba3156c0 [doc] Fix format and typo
Noe Gaumont <ngaumont@logilab.fr>
parents: 11735
diff changeset
   284
msgid)`.
11337
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   285
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   286
12582
2b0a3f2607f0 [doc] add a reference to static-messages.pot usage
Noe Gaumont <ngaumont@logilab.fr>
parents: 12581
diff changeset
   287
.. _translate-application-cube:
2b0a3f2607f0 [doc] add a reference to static-messages.pot usage
Noe Gaumont <ngaumont@logilab.fr>
parents: 12581
diff changeset
   288
11337
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   289
Specialize translation for an application cube
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   290
``````````````````````````````````````````````
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   291
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   292
Every cube has its own translation files. For a specific application cube
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   293
it can be useful to specialize translations of other cubes. You can either mark
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   294
those strings for translation using `_` in the python code, or add a
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   295
`static-messages.pot` file into the `i18n` directory. This file
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   296
looks like: ::
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   297
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   298
    msgid ""
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   299
    msgstr ""
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   300
    "PO-Revision-Date: YEAR-MO-DA HO:MI +ZONE\n"
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   301
    "MIME-Version: 1.0\n"
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   302
    "Content-Type: text/plain; charset=UTF-8\n"
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   303
    "Content-Transfer-Encoding: 8bit\n"
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   304
    "Generated-By: pygettext.py 1.5\n"
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   305
    "Plural-Forms: nplurals=2; plural=(n > 1);\n"
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   306
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   307
    msgig "expression to be translated"
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   308
    msgstr ""
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   309
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   310
Doing this, ``expression to be translated`` will be taken into account by
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   311
the ``i18ncube`` command and additional messages will then appear in `.po` files
60369010c49e [doc] add documentation for specializing translation of other cubes in an application cube
Alexandre Richardson <alexandre.richardson@logilab.fr>
parents: 10491
diff changeset
   312
of the cube.