doc/guides/translations.rst

   1 .. _guides/translations:
   2
   3 ===================
   4 Translating Modules
   5 ===================
   6
   7 Exporting translatable term
   8 ===========================
   9
  10 A number of terms in your modules are "implicitly translatable" as a result,
  11 even if you haven't done any specific work towards translation you can export
  12 your module's translatable terms and may find content to work with.
  13
  14 .. todo:: needs technical features
  15
  16 Translations export is done via the administration interface by logging into
  17 the backend interface and opening :menuselection:`Settings --> Translations
  18 --> Import / Export --> Export Translations`
  19
  20 * leave the language to the default (new language/empty template)
  21 * select the `PO File`_ format
  22 * select your module
  23 * click :guilabel:`Export` and download the file
  24
  25 .. image:: translations/po-export.*
  26     :align: center
  27     :width: 75%
  28
  29 This gives you a file called :file:`{yourmodule}.po` which should be renamed
  30 to :file:`{yourmodule}.pot` and moved to the :file:`{yourmodule}/i18n/`
  31 directory. The file is a *PO Template* which simply lists translatable strings
  32 and from which actual translations (PO files) can be created. PO files can
  33 be created using msginit_, with a dedicated translation tool like POEdit_ or
  34 by simply copying the template to a new file called :file:`{language}.po`.
  35 Translation files should be put in :file:`{yourmodule}/i18n/`, next to
  36 :file:`{yourmodule}.pot`, and will be automatically loaded by Odoo when the
  37 corresponding language is installed (via :menuselection:`Settings -->
  38 Translations --> Load a Translation`)
  39
  40 .. note:: translations for all loaded languages are also installed or updated
  41           when installing or updating a module
  42
  43 Implicit exports
  44 ================
  45
  46 Odoo automatically exports translatable strings from "data"-type content:
  47
  48 * in non-QWeb views, all text nodes are exported as well as the content of
  49   the ``string``, ``help``, ``sum``, ``confirm`` and ``placeholder``
  50   attributes
  51 * QWeb templates (both server-side and client-side), all text nodes are
  52   exported except inside ``t-translation="off"`` blocks, the content of the
  53   ``title``, ``alt``, ``label`` and ``placeholder`` attributes are also
  54   exported
  55 * for :class:`~openerp.fields.Field`, unless their model is marked with
  56   ``_translate = False``:
  57
  58   * their ``string`` and ``help`` attributes are exported
  59   * if ``selection`` is present and a list (or tuple), it's exported
  60   * if their ``translate`` attribute is set to ``True``, all of their existing
  61     values (across all records) are exported
  62 * help/error messages of :attr:`~openerp.models.Model._constraints` and
  63   :attr:`~openerp.models.Model._sql_constraints` are exported
  64
  65 Explicit exports
  66 ================
  67
  68 When it comes to more "imperative" situations in Python code or Javascript
  69 code, Odoo is not able to automatically export translatable terms and they
  70 must be marked explicitly for export. This is done by wrapping a literal
  71 string in a function call.
  72
  73 In Python, the wrapping function is :func:`openerp.tools.translate._`::
  74
  75     title = _("Bank Accounts")
  76
  77 In JavaScript, the wrapping function is generally :js:func:`openerp.web._t`:
  78
  79 .. code-block:: javascript
  80
  81     title = _t("Bank Accounts")
  82
  83 .. warning::
  84
  85     only literal strings can be marked for exports, not expressions and not
  86     variables. For situations where strings are formatted, this means the
  87     format string must be marked not the formatted string::
  88
  89         # bad, the extract may work but it will not correctly translate the text
  90         _("Scheduled meeting with %s" % invitee.name)
  91
  92         # good
  93         _("Scheduled meeting with %s") % invitee.name
  94
  95 .. _PO File: http://en.wikipedia.org/wiki/Gettext#Translating
  96 .. _msginit: http://www.gnu.org/software/gettext/manual/gettext.html#Creating
  97 .. _POEdit: http://poedit.net/