==========
ICU Format
==========

.. |coverage| image:: .badges/coverage.svg
    :target: https://orus.io/xcg/odoo-modules/icuformat/-/pipelines?ref=branch/16.0
    :alt: Coverage report
.. |pylint| image:: .badges/pylint.svg
    :target: https://orus.io/xcg/odoo-modules/icuformat/-/pipelines?ref=branch/16.0
    :alt: pylint score
.. Update the badge below depending on status
.. |maturity| image:: .badges/maturity.svg
    :target: https://odoo-community.org/page/development-status
    :alt: Alpha
.. |license| image:: .badges/licence-AGPL--3-blue.svg
    :target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
    :alt: License: AGPL-3
.. |black| image:: .badges/code_style-black-000000.svg
    :target: https://github.com/psf/black
    :alt: Black
.. |prettier| image:: .badges/code_style-prettier-ff69b4.svg
    :target: https://github.com/prettier/prettier
    :alt: Prettier

|coverage| |pylint| |maturity| |license| |black| |prettier|

Provides methods that encapsulates PyICU.

ICU provides handling of plural and many other things that are not present in the gettext implementation of Odoo.

This module provides icu_format that can be called from anywhere:

.. code-block:: python

        from odoo.addons.icuformat import icu_format

        icu_format("en", _("A message: {msg}"), {"msg": self.id})

There is also one that is linked to models and extract the language to use from the context, defaulting to the current user lang:

.. code-block:: python

        self.icu_format(_("A message: {msg}"), {"msg": self.id})

The icu_format methods accepts various types in its dictionary, but some of them are converted to avoid errors in ICU:

- dates are converted to datetime.
- bool are converted to strings.

The module also add icu_format_translate to the list of method used in babel to generate the module catalogs.

It also adds ``TRANSLATORS:`` as a tag used to comment translated strings.

Example:

.. code-block:: python

        # TRANSLATORS: b is a boolean, either True or False
        self.icu_format_translate("{b,select,True{This is true.}other{This is false.}}", {"b": value}))

ICU provides a way to format a list of elements, it is also exposed:

.. code-block:: python

        self.icu_list_format(["a", "b", "c"])

.. code-block:: python

        from odoo.addons.icuformat import icu_list_format

        icu_list_format("en_US", self.ids)

There is also a currency formatter helper:

.. code-block:: python

        self.env.ref("base.EUR").icu_format(
            _("Your total is {total, number, currency}"), {"total": 1.25}
        )
        self.currency_id.icu_format_translate(
            "Your total is {total, number, currency}", {"total": 1.25}
        )

There is also a logger to use ICU in log messages:

.. code-block:: python

  from odoo.addons.icuformat import get_logger

  _logger = get_logger(__name__)
  _logger.info("Simple message")
  _logger.info("Value: {value, number}", {"value": 1000})

To Do
-----

- provide a method that use the translated locale of a text. This is to avoid mixing translation and formatting. For example, a user expects “User joined the company in March 2021”, but not “User joined the company in mars 2021” where there is a mix of French formatting of the date while the message is not formatted.
- add number, time and date formatter.

Reference
---------

- `ICU User Guide <https://unicode-org.github.io/icu/userguide/>`_