doc/reference/translations.rst

   1 .. _reference/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}.pot` which should be moved to
  30 the :file:`{yourmodule}/i18n/` directory. The file is a *PO Template* which
  31 simply lists translatable strings and from which actual translations (PO files)
  32 can be created. PO files can be created using msginit_, with a dedicated
  33 translation tool like POEdit_ or by simply copying the template to a new file
  34 called :file:`{language}.po`. Translation files should be put in
  35 :file:`{yourmodule}/i18n/`, next to :file:`{yourmodule}.pot`, and will be
  36 automatically loaded by Odoo when the corresponding language is installed (via
  37 :menuselection:`Settings --> Translations --> Load a Translation`)
  38
  39 .. note:: translations for all loaded languages are also installed or updated
  40           when installing or updating a module
  41
  42 Implicit exports
  43 ================
  44
  45 Odoo automatically exports translatable strings from "data"-type content:
  46
  47 * in non-QWeb views, all text nodes are exported as well as the content of
  48   the ``string``, ``help``, ``sum``, ``confirm`` and ``placeholder``
  49   attributes
  50 * QWeb templates (both server-side and client-side), all text nodes are
  51   exported except inside ``t-translation="off"`` blocks, the content of the
  52   ``title``, ``alt``, ``label`` and ``placeholder`` attributes are also
  53   exported
  54 * for :class:`~openerp.fields.Field`, unless their model is marked with
  55   ``_translate = False``:
  56
  57   * their ``string`` and ``help`` attributes are exported
  58   * if ``selection`` is present and a list (or tuple), it's exported
  59   * if their ``translate`` attribute is set to ``True``, all of their existing
  60     values (across all records) are exported
  61 * help/error messages of :attr:`~openerp.models.Model._constraints` and
  62   :attr:`~openerp.models.Model._sql_constraints` are exported
  63
  64 Explicit exports
  65 ================
  66
  67 When it comes to more "imperative" situations in Python code or Javascript
  68 code, Odoo is not able to automatically export translatable terms and they
  69 must be marked explicitly for export. This is done by wrapping a literal
  70 string in a function call.
  71
  72 In Python, the wrapping function is :func:`openerp._`::
  73
  74     title = _("Bank Accounts")
  75
  76 In JavaScript, the wrapping function is generally :js:func:`openerp.web._t`:
  77
  78 .. code-block:: javascript
  79
  80     title = _t("Bank Accounts")
  81
  82 .. warning::
  83
  84     Only literal strings can be marked for exports, not expressions and not
  85     variables. For situations where strings are formatted, this means the
  86     format string must be marked, not the formatted string::
  87
  88         # bad, the extract may work but it will not correctly translate the text
  89         _("Scheduled meeting with %s" % invitee.name)
  90
  91         # good
  92         _("Scheduled meeting with %s") % invitee.name
  93
  94 .. _PO File: http://en.wikipedia.org/wiki/Gettext#Translating
  95 .. _msginit: http://www.gnu.org/software/gettext/manual/gettext.html#Creating
  96 .. _POEdit: http://poedit.net/