2 files changed, 94 insertions, 6 deletions
diff --git a/doc/reference/translations.rst b/doc/reference/translations.rst
index 16c222ce25c..adfc11a259f 100644
--- a/doc/reference/translations.rst
+++ b/doc/reference/translations.rst
@@ -80,19 +80,107 @@ In JavaScript, the wrapping function is generally :js:func:`odoo.web._t`:
 
 .. code-block:: javascript
 
-    title = _t("Bank Accounts")
+    title = _t("Bank Accounts");
 
 .. warning::
 
     Only literal strings can be marked for exports, not expressions or
     variables. For situations where strings are formatted, this means the
-    format string must be marked, not the formatted string::
+    format string must be marked, not the formatted string
 
-        # bad, the extract may work but it will not translate the text correctly
-        _("Scheduled meeting with %s" % invitee.name)
 
-        # good
-        _("Scheduled meeting with %s") % invitee.name
+Variables
+^^^^^^^^^
+**Don't** the extract may work but it will not translate the text correctly::
+
+    _("Scheduled meeting with %s" % invitee.name)
+
+**Do** set the dynamic variables outside of the translation lookup::
+
+    _("Scheduled meeting with %s") % invitee.name
+
+
+Blocks
+^^^^^^
+**Don't** split your translation in several blocks or multiples lines::
+
+    # bad, trailing spaces, blocks out of context
+    _("You have ") + len(invoices) + _(" invoices waiting")
+
+    # bad, multiple small translations
+    _("Reference of the document that generated ") + \
+    _("this sales order request.")
+
+**Do** keep in one block, giving the full context to translators::
+
+    # good, allow to change position of the number in the translation
+    _("You have %s invoices wainting") % len(invoices)
+
+    # good, full sentence is understandable
+    _("Reference of the document that generated " + \
+      "this sales order request.")
+
+Plural
+^^^^^^
+**Don't** pluralize terms the English-way::
+
+    msg = _("You have %s invoice") % invoice_count
+    if invoice_count > 1:
+      msg += _("s")
+
+**Do** keep in mind every language has different plural forms::
+
+    if invoice_count > 1:
+      msg = _("You have %s invoices") % invoice_count
+    else:
+      msg = _("You have %s invoice") % invoice_count
+
+Read vs Run Time
+^^^^^^^^^^^^^^^^
+
+**Don't** invoke translation lookup at server launch::
+
+    ERROR_MESSAGE = {
+      # bad, evaluated at server launch with no user language
+      access_error: _('Access Error'),
+      missing_error: _('Missing Record'),
+    }
+
+    class Record(models.Model):
+
+      def _raise_error(self, code):
+        raise UserError(ERROR_MESSAGE[code])
+
+**Don't** invoke translation lookup when the javascript file is read::
+
+    # bad, js _t is evaluated too early
+    var core = require('web.core');
+    var _t = core._t;
+    var map_title = {
+        access_error: _t('Access Error'),
+        missing_error: _t('Missing Record'),
+    };
+
+**Do** evaluate dynamically the translatable content::
+
+    # good, evaluated at run time
+    def _get_error_message():
+      return {
+        access_error: _('Access Error'),
+        missing_error: _('Missing Record'),
+      }
+
+**Do** in the case where the translation lookup is done when the JS file is
+*read*, use `_lt` instead of `_t` to translate the term when it is *used*::
+
+    # good, js _lt is evaluated lazily
+    var core = require('web.core');
+    var _lt = core._lt;
+    var map_title = {
+        access_error: _lt('Access Error'),
+        missing_error: _lt('Missing Record'),
+    };
+
 
 .. _PO File: http://en.wikipedia.org/wiki/Gettext#Translating
 .. _msginit: http://www.gnu.org/software/gettext/manual/gettext.html#Creating
diff --git a/doc/reference/translations/po-export.png b/doc/reference/translations/po-export.png
index 82f8d5ad011..bd7fa14c3d8 100644
--- a/doc/reference/translations/po-export.png
+++ b/doc/reference/translations/po-export.png