.. _developers_i18n:

===========================
Internationalization (i18n)
===========================

Backend
=======

For the backend, see the Django `i18n documentation`_.

.. note::

    When re-generating the OAS with the ``generate_oas.sh`` script, the language option is not always respected.
    Therefore, if some fields in the OAS change language after the generation, make sure to run ``python src/manage.py compilemessages``
    before re-generating.


.. _i18n documentation: https://docs.djangoproject.com/en/4.2/topics/i18n/translation/

.. _`Forms Admin`:

Forms Admin
-----------

FormIO uses `i18next <https://www.i18next.com/>`_ to manage the translations. The configuration options for
``i18next`` can be passed to FormIO through the `i18n` option of the ``FormBuilder``. Example:

.. code-block::

    <FormBuilder
        ...
        options={ {language: 'nl', i18n: {'English example': 'Nederlands voorbeeld'}} }
    />

Any string that appears in the ``FormBuilder`` needs to be added **manually** to the JSON translation file,
since we don't yet have a mechanism to extract them from the source code. The translation file can be found at this
path: ``src/openforms/js/lang/formio/nl.json``.


Frontend
========

In the frontend, we use `react-intl`_ to manage translations.

.. seealso::

    See :ref:`developers_frontend_index_i18n` on how to manage translations across
    our (NPM) libraries.

Declaring messages
------------------

The preferred way is to use the ``FormattedMessage`` component. If that's not possible
or inconvevient, the declarative API through the ``const intl = useIntl();`` hook is
available.

Extracting messages
-------------------

To extract messages from the codebase, run:

.. code-block:: bash

    ./bin/makemessages_js.sh

The resulting message catalogs are now available in ``src/openforms/js/lang/{locale}.json``.

Edit these files with the correct translations and then compile them:

.. code-block:: bash

    ./bin/compilemessages_js.sh

If you want to see the results directly, you need to add them to the build but
this is also done by the CI to create the Docker image.

.. code-block:: bash

    npm run build

.. _react-intl: https://formatjs.github.io/docs/getting-started/installation

FormIO
------

The strings used in the FormIO widgets have to be translated using the ``i18next`` mechanism. This happens in the same
way as for the ``FormBuilder`` (see :ref:`Forms Admin`), but here the translations are passed to the ``FormIOWrapper``
(``src/components/FormStep.js``). The translations are managed by the backend and the frontend fetches them.
Therefore, if there are strings that are not yet translated, they have to be added to this translation file:
``src/openforms/js/lang/formio/nl.json``.

.. note:: Currently the Formio builder and renderer are in the process of being replaced
   with a solution that uses react-intl too. So, eventually the Form.io mechanism will
   become obsolete.