From: Raphael Collet Date: Thu, 27 Nov 2014 09:35:07 +0000 (+0100) Subject: [IMP] doc: move translations to reference documentation X-Git-Url: http://git.inspyration.org/?p=odoo%2Fodoo.git;a=commitdiff_plain;h=4d6fb49b8f9a18d01b6d17defa21ea1c97940a23 [IMP] doc: move translations to reference documentation --- diff --git a/doc/guides/translations.rst b/doc/guides/translations.rst deleted file mode 100644 index 792caa8..0000000 --- a/doc/guides/translations.rst +++ /dev/null @@ -1,97 +0,0 @@ -.. _guides/translations: - -=================== -Translating Modules -=================== - -Exporting translatable term -=========================== - -A number of terms in your modules are "implicitly translatable" as a result, -even if you haven't done any specific work towards translation you can export -your module's translatable terms and may find content to work with. - -.. todo:: needs technical features - -Translations export is done via the administration interface by logging into -the backend interface and opening :menuselection:`Settings --> Translations ---> Import / Export --> Export Translations` - -* leave the language to the default (new language/empty template) -* select the `PO File`_ format -* select your module -* click :guilabel:`Export` and download the file - -.. image:: translations/po-export.* - :align: center - :width: 75% - -This gives you a file called :file:`{yourmodule}.po` which should be renamed -to :file:`{yourmodule}.pot` and moved to the :file:`{yourmodule}/i18n/` -directory. The file is a *PO Template* which simply lists translatable strings -and from which actual translations (PO files) can be created. PO files can -be created using msginit_, with a dedicated translation tool like POEdit_ or -by simply copying the template to a new file called :file:`{language}.po`. -Translation files should be put in :file:`{yourmodule}/i18n/`, next to -:file:`{yourmodule}.pot`, and will be automatically loaded by Odoo when the -corresponding language is installed (via :menuselection:`Settings --> -Translations --> Load a Translation`) - -.. note:: translations for all loaded languages are also installed or updated - when installing or updating a module - -Implicit exports -================ - -Odoo automatically exports translatable strings from "data"-type content: - -* in non-QWeb views, all text nodes are exported as well as the content of - the ``string``, ``help``, ``sum``, ``confirm`` and ``placeholder`` - attributes -* QWeb templates (both server-side and client-side), all text nodes are - exported except inside ``t-translation="off"`` blocks, the content of the - ``title``, ``alt``, ``label`` and ``placeholder`` attributes are also - exported -* for :class:`~openerp.fields.Field`, unless their model is marked with - ``_translate = False``: - - * their ``string`` and ``help`` attributes are exported - * if ``selection`` is present and a list (or tuple), it's exported - * if their ``translate`` attribute is set to ``True``, all of their existing - values (across all records) are exported -* help/error messages of :attr:`~openerp.models.Model._constraints` and - :attr:`~openerp.models.Model._sql_constraints` are exported - -Explicit exports -================ - -When it comes to more "imperative" situations in Python code or Javascript -code, Odoo is not able to automatically export translatable terms and they -must be marked explicitly for export. This is done by wrapping a literal -string in a function call. - -In Python, the wrapping function is :func:`openerp.tools.translate._`:: - - title = _("Bank Accounts") - -In JavaScript, the wrapping function is generally :js:func:`openerp.web._t`: - -.. code-block:: javascript - - title = _t("Bank Accounts") - -.. warning:: - - only literal strings can be marked for exports, not expressions and not - variables. For situations where strings are formatted, this means the - format string must be marked not the formatted string:: - - # bad, the extract may work but it will not correctly translate the text - _("Scheduled meeting with %s" % invitee.name) - - # good - _("Scheduled meeting with %s") % invitee.name - -.. _PO File: http://en.wikipedia.org/wiki/Gettext#Translating -.. _msginit: http://www.gnu.org/software/gettext/manual/gettext.html#Creating -.. _POEdit: http://poedit.net/ diff --git a/doc/guides/translations/po-export.png b/doc/guides/translations/po-export.png deleted file mode 100644 index 82f8d5a..0000000 Binary files a/doc/guides/translations/po-export.png and /dev/null differ diff --git a/doc/reference.rst b/doc/reference.rst index 3e1597d..9c995ef 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -18,5 +18,6 @@ Reference reference/qweb reference/javascript + reference/translations reference/reports reference/workflows diff --git a/doc/reference/translations.rst b/doc/reference/translations.rst new file mode 100644 index 0000000..45616189 --- /dev/null +++ b/doc/reference/translations.rst @@ -0,0 +1,96 @@ +.. _reference/translations: + +=================== +Translating Modules +=================== + +Exporting translatable term +=========================== + +A number of terms in your modules are "implicitly translatable" as a result, +even if you haven't done any specific work towards translation you can export +your module's translatable terms and may find content to work with. + +.. todo:: needs technical features + +Translations export is done via the administration interface by logging into +the backend interface and opening :menuselection:`Settings --> Translations +--> Import / Export --> Export Translations` + +* leave the language to the default (new language/empty template) +* select the `PO File`_ format +* select your module +* click :guilabel:`Export` and download the file + +.. image:: translations/po-export.* + :align: center + :width: 75% + +This gives you a file called :file:`{yourmodule}.pot` which should be moved to +the :file:`{yourmodule}/i18n/` directory. The file is a *PO Template* which +simply lists translatable strings and from which actual translations (PO files) +can be created. PO files can be created using msginit_, with a dedicated +translation tool like POEdit_ or by simply copying the template to a new file +called :file:`{language}.po`. Translation files should be put in +:file:`{yourmodule}/i18n/`, next to :file:`{yourmodule}.pot`, and will be +automatically loaded by Odoo when the corresponding language is installed (via +:menuselection:`Settings --> Translations --> Load a Translation`) + +.. note:: translations for all loaded languages are also installed or updated + when installing or updating a module + +Implicit exports +================ + +Odoo automatically exports translatable strings from "data"-type content: + +* in non-QWeb views, all text nodes are exported as well as the content of + the ``string``, ``help``, ``sum``, ``confirm`` and ``placeholder`` + attributes +* QWeb templates (both server-side and client-side), all text nodes are + exported except inside ``t-translation="off"`` blocks, the content of the + ``title``, ``alt``, ``label`` and ``placeholder`` attributes are also + exported +* for :class:`~openerp.fields.Field`, unless their model is marked with + ``_translate = False``: + + * their ``string`` and ``help`` attributes are exported + * if ``selection`` is present and a list (or tuple), it's exported + * if their ``translate`` attribute is set to ``True``, all of their existing + values (across all records) are exported +* help/error messages of :attr:`~openerp.models.Model._constraints` and + :attr:`~openerp.models.Model._sql_constraints` are exported + +Explicit exports +================ + +When it comes to more "imperative" situations in Python code or Javascript +code, Odoo is not able to automatically export translatable terms and they +must be marked explicitly for export. This is done by wrapping a literal +string in a function call. + +In Python, the wrapping function is :func:`openerp._`:: + + title = _("Bank Accounts") + +In JavaScript, the wrapping function is generally :js:func:`openerp.web._t`: + +.. code-block:: javascript + + title = _t("Bank Accounts") + +.. warning:: + + Only literal strings can be marked for exports, not expressions and not + variables. For situations where strings are formatted, this means the + format string must be marked, not the formatted string:: + + # bad, the extract may work but it will not correctly translate the text + _("Scheduled meeting with %s" % invitee.name) + + # good + _("Scheduled meeting with %s") % invitee.name + +.. _PO File: http://en.wikipedia.org/wiki/Gettext#Translating +.. _msginit: http://www.gnu.org/software/gettext/manual/gettext.html#Creating +.. _POEdit: http://poedit.net/ diff --git a/doc/reference/translations/po-export.png b/doc/reference/translations/po-export.png new file mode 100644 index 0000000..82f8d5a Binary files /dev/null and b/doc/reference/translations/po-export.png differ