# HG changeset patch # User Aurelien Campeas # Date 1270209207 -7200 # Node ID efc280ad9898eb1ea4f2a84df059525454accd21 # Parent d795cac8ad40819dfde5ca00edec3dc245d45549 [doc/book] enhance i18n section #656191 diff -r d795cac8ad40 -r efc280ad9898 doc/book/en/development/devweb/internationalization.rst --- a/doc/book/en/development/devweb/internationalization.rst Fri Apr 02 10:04:33 2010 +0200 +++ b/doc/book/en/development/devweb/internationalization.rst Fri Apr 02 13:53:27 2010 +0200 @@ -15,7 +15,7 @@ * in your Python code and cubicweb-tal templates : mark translatable strings -* in your instance : handle the translation catalog +* in your instance : handle the translation catalog, edit translations String internationalization ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -50,8 +50,9 @@ itself, but not its translation (it's actually another name for the `unicode` builtin). -In the other hand the request's method `self._cw._` is meant to retrieve the -proper translation of translation strings in the requested language. +In the other hand the request's method `self._cw._` is also meant to +retrieve the proper translation of translation strings in the +requested language. Finally you can also use the `__` attribute of request object to get a translation for a string *which should not itself added to the catalog*, @@ -62,14 +63,15 @@ In this example ._cw.__` is used instead of ._cw._` so we don't have 'This %s' in messages catalogs. - Translations in cubicweb-tal template can also be done with TAL tags `i18n:content` and `i18n:replace`. - If you need to add messages on top of those that can be found in the source, you can create a file named `i18n/static-messages.pot`. +You could put there messages not found in the python sources or +overrides for some messages of used cubes. + Generated string ```````````````` @@ -80,20 +82,20 @@ For exemple the following schema :: Class EntityA(EntityType): - relationa2b = SubjectRelation('EntityB') + relation_a2b = SubjectRelation('EntityB') class EntityB(EntityType): pass May generate the following message :: - add Execution has_export File subject + add EntityA relation_a2b EntityB subject This message will be used in views of ``EntityA`` for creation of a new ``EntityB`` with a preset relation ``relation_a2b`` between the current ``EntityA`` and the new ``EntityB``. The opposite message :: - add Execution has_export File object + add EntityA relation_a2b EntityB object Is used for similar creation of an ``EntityA`` from a view of ``EntityB``. The title of they respective creation form will be :: @@ -105,8 +107,8 @@ In the translated string you can use ``%(linkto)s`` for reference to the source ``entity``. -Handle the translation catalog -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Handling the translation catalog +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Once the internationalization is done in your code, you need to populate and update the translation catalog. Cubicweb provides the following commands for this @@ -117,11 +119,11 @@ catalogs. Unless you actually work on the framework itself, you don't need to use this command. -* `i18ncube` updates the translation catalogs of *one particular - cube* (or of all cubes). After this command is - executed you must update the translation files *.po* in the "i18n" - directory of your template. This command will of course not remove - existing translations still in use. +* `i18ncube` updates the translation catalogs of *one particular cube* + (or of all cubes). After this command is executed you must update + the translation files *.po* in the "i18n" directory of your + cube. This command will of course not remove existing translations + still in use. It will mark unused translation but not remove them. * `i18ninstance` recompiles the translation catalogs of *one particular instance* (or of all instances) after the translation catalogs of @@ -134,6 +136,7 @@ Example ``````` + You have added and/or modified some translation strings in your cube (after creating a new view or modifying the cube's schema for exemple). To update the translation catalogs you need to do: @@ -143,3 +146,77 @@ 3. `hg ci -m "updated i18n catalogs"` 4. `cubicweb-ctl i18ninstance ` +Editing po files +~~~~~~~~~~~~~~~~ + +Using a PO aware editor +```````````````````````` + +Many tools exist to help maintain .po (PO) files. Common editors or +development environment provides modes for these. One can also find +dedicated PO files editor, such as `poedit`_. + +.. _`poedit`: http://www.poedit.net/ + +While usage of such a tool is commendable, PO files are perfectly +editable with a (unicode aware) plain text editor. It is also useful +to know their structure for troubleshooting purposes. + +Structure of a PO file +`````````````````````` + +In this section, we selectively quote passages of the `GNU gettext`_ +manual chapter on PO files, available there:: + + http://www.gnu.org/software/hello/manual/gettext/PO-Files.html + +One PO file entry has the following schematic structure:: + + white-space + # translator-comments + #. extracted-comments + #: reference... + #, flag... + #| msgid previous-untranslated-string + msgid untranslated-string + msgstr translated-string + + +A simple entry can look like this:: + + #: lib/error.c:116 + msgid "Unknown system error" + msgstr "Error desconegut del sistema" + +It is also possible to have entries with a context specifier. They +look like this:: + + white-space + # translator-comments + #. extracted-comments + #: reference... + #, flag... + #| msgctxt previous-context + #| msgid previous-untranslated-string + msgctxt context + msgid untranslated-string + msgstr translated-string + + +The context serves to disambiguate messages with the same +untranslated-string. It is possible to have several entries with the +same untranslated-string in a PO file, provided that they each have a +different context. Note that an empty context string and an absent +msgctxt line do not mean the same thing. + +Contexts and CubicWeb +````````````````````` + +CubicWeb PO files have both non-contextual and contextual msgids. + +Contextual entries are automatically used in some cases. For instance, +entity.dc_type(), eschema.display_name(req) or display_name(etype, +req, form, context) methods/function calls will use them. + +It is also possible to explicitly use the with _cw.pgettext(context, +msgid).