[MERGE] tools: better placeholder support for _

Support two new syntaxes with `_()` method:

_("This is so %s") % 2019
_("Text with %s placeholders", 42)
_("Text with %(num)s placeholders %(symbol)s", num=42, symbol="🧀")

The main benefit is to have a fallback on the source string if formating the
translated string fails (e.g. "Foo %s" translated "Foo s%").

This PR converted most (but not all) calls to _ using placeholders to use the
new syntax. Hopefully, the remaining ones will be converted in the future and
avoid technical debt.

Use named placeholders when needed. If more than one placeholder is present in a
string, using named placeholder can be beneficial to reorder the placehodler
position (for languages like Japanese that do not use the same phrase
construction). On some sentences, it also brings clarity on the meaning of the
placeholders.

closes odoo/odoo#52155

Task-id: 1853119
Signed-off-by: Martin Trigaux (mat) <mat@odoo.com>

1 files changed, 18 insertions, 14 deletions

diff --git a/doc/reference/guidelines.rst b/doc/reference/guidelines.rst
index 2b6dc4a0a23..6ffd19f5c78 100644
--- a/doc/reference/guidelines.rst
+++ b/doc/reference/guidelines.rst
@@ -837,6 +837,7 @@ in the code, it will not work to translate field values, such as Product names,
 etc. This must be done instead using the translate flag on the corresponding
 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:
 
@@ -846,19 +847,23 @@ the form ``_('literal string')`` and nothing else:
     error = _('This record is locked!')
 
     # good: strings with formatting patterns included
-    error = _('Record %s cannot be modified!') % record
+    error = _('Record %s cannot be modified!', record)
 
     # ok too: multi-line literal strings
     error = _("""This is a bad multiline example
-                 about record %s!""") % record
+                 about record %s!""", record)
     error = _('Record %s cannot be modified' \
-              'after being validated!') % record
+              'after being validated!', record)
 
     # bad: tries to translate after string formatting
     #      (pay attention to brackets!)
     # This does NOT work and messes up the translations!
     error = _('Record %s cannot be modified!' % record)
 
+    # bad: formatting outside of translation
+    # This won't benefit from fallback mechanism in case of bad translation
+    error = _('Record %s cannot be modified!') % record
+
     # bad: dynamic string, string concatenation, etc are forbidden!
     # This does NOT work and messes up the translations!
     error = _("'" + que_rec['question'] + "' \n")
@@ -869,32 +874,31 @@ the form ``_('literal string')`` and nothing else:
     # and the following will of course not work as already explained:
     error = _("Product %s is out of stock!" % product.name)
 
-    # bad: field values are automatically translated by the framework
-    # This is useless and will not work the way you think:
-    error = _("Product %s is not available!") % _(product.name)
-    # and the following will of course not work as already explained:
-    error = _("Product %s is not available!" % product.name)
-
     # Instead you can do the following and everything will be translated,
     # including the product name if its field definition has the
     # translate flag properly set:
-    error = _("Product %s is not available!") % product.name
+    error = _("Product %s is not available!", product.name)
 
 
 Also, keep in mind that translators will have to work with the literal values
 that are passed to the underscore function, so please try to make them easy to
 understand and keep spurious characters and formatting to a minimum. Translators
-must be aware that formatting patterns such as %s or %d, newlines, etc. need
-to be preserved, but it's important to use these in a sensible and obvious manner:
+must be aware that formatting patterns such as ``%s`` or ``%d``, newlines, etc.
+need to be preserved, but it's important to use these in a sensible and obvious
+manner:
 
 .. code-block:: python
 
     # Bad: makes the translations hard to work with
     error = "'" + question + _("' \nPlease enter an integer value ")
 
-    # Better (pay attention to position of the brackets too!)
+    # Ok (pay attention to position of the brackets too!)
     error = _("Answer to question %s is not valid.\n" \
-              "Please enter an integer value.") % question
+              "Please enter an integer value.", question)
+
+    # Better
+    error = _("Answer to question %(title)s is not valid.\n" \
+              "Please enter an integer value.", title=question)
 
 In general in Odoo, when manipulating strings, prefer ``%`` over ``.format()``
 (when only one variable to replace in a string), and prefer ``%(varname)`` instead