[IMP] core: Environment._ for translations

odoo/odoo#174844

closes odoo/documentation#10421

Related: odoo/enterprise#67528
Signed-off-by: Krzysztof Magusiak (krma) <krma@odoo.com>

content/contributing/development/coding_guidelines.rst

@@ -725,14 +725,10 @@ they can and will be removed !
 Use translation method correctly
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Odoo uses a GetText-like method named "underscore" ``_( )`` to indicate that
-a static string used in the code needs to be translated at runtime using the
-language of the context. This pseudo-method is accessed within your code by
-importing as follows:
-
-.. code-block:: python
-
-    from odoo import _
+Odoo uses a GetText-like method named "underscore" ``_()`` to indicate that
+a static string used in the code needs to be translated at runtime.
+That method is available at ``self.env._`` using the language of the
+environment.
 
 A few very important rules must be followed when using it, in order for it to
 work and to avoid filling the translations with useless junk.
@@ -744,10 +740,12 @@ field.
 
 The method accepts optional positional or named parameter
 The rule is very simple: calls to the underscore method should always be in
-the form ``_('literal string')`` and nothing else:
+the form ``self.env._('literal string')`` and nothing else:
 
 .. code-block:: python
 
+    _ = self.env._
+
     # good: plain strings
     error = _('This record is locked!')
 

content/developer/howtos/translations.rst

@@ -74,8 +74,15 @@ code, Odoo cannot automatically export translatable terms so 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:`odoo._`::
+In Python, the wrapping function is :func:`odoo.api.Environment._`
+and :func:`odoo.tools.translate._`:
 
+.. code-block:: python
+
+    title = self.env._("Bank Accounts")
+
+    # old API for backward-compatibility
+    from odoo.tools import _
     title = _("Bank Accounts")
 
 In JavaScript, the wrapping function is generally :js:func:`odoo.web._t`:
@@ -90,11 +97,18 @@ In JavaScript, the wrapping function is generally :js:func:`odoo.web._t`:
     variables. For situations where strings are formatted, this means the
     format string must be marked, not the formatted string
 
-The lazy version of `_` and `_t` is :func:`odoo._lt` in python and
-:js:func:`odoo.web._lt` in javascript. The translation lookup is executed only
+The lazy version of `_` and `_t` is the :class:`odoo.tools.translate.LazyTranslate`
+factory in python and :js:func:`odoo.web._lt` in javascript.
+The translation lookup is executed only
 at rendering and can be used to declare translatable properties in class methods
 of global variables.
 
+.. code-block:: python
+
+    from odoo.tools import LazyTranslate
+    _lt = LazyTranslate(__name__)
+    LAZY_TEXT = _lt("some text")
+
 .. note::
 
     Translations of a module are **not** exposed to the front end by default and
@@ -115,6 +129,26 @@ of global variables.
                 modules = super()._get_translation_frontend_modules_name()
                 return modules + ['your_module']
 
+Context
+-------
+
+To translate, the translation function needs to know the *language* and the
+*module* name. When using ``Environment._`` the language is known and you
+may pass the module name as a parameter, otherwise it's extracted from the
+caller.
+
+In case of ``odoo.tools.translate._``, the language and the module are
+extracted from the context. For this, we inspect the caller's local variables.
+The drawback of this method is that it is error-prone: we try to find the
+context variable or ``self.env``, however these may not exist if you use
+translations outside of model methods; i.e. it does not work inside regular
+functions or python comprehensions.
+
+Lazy translations are bound to the module during their creation and the
+language is resolved when evaluating using ``str()``.
+Note that you can also pass a lazy translation to ``Envionrment._``
+to translate it without any magic language resolution.
+
 Variables
 ---------
 

content/developer/reference/backend/orm/changelog.rst

@@ -12,6 +12,7 @@ Odoo version 18.0
 - New methods to check access rights and rules now combine both access rights
   and rules: `check_access`, `has_access` and `_filtered_access`.
   See `#179148 <https://github.com/odoo/odoo/pull/179148>`_.
+- Translations are made available from the `Environment` with `#174844 <https://github.com/odoo/odoo/pull/174844>`_.
 
 
 Odoo Online version 17.4