.. _translations:

============
Translations
============

Adding translatable strings to the project
############################################
Please refer to :ref:`code-style-i18n` section  in code style guide.

Translating
############

.. seealso:: `MEG Internationalisation guide <https://docs.google.com/document/d/15k320VDxHlmIbk5RLdONf8gK6W8n_53b_tR5XlOoM8I/edit?usp=sharing>`_

Adding translations in POEditor
-----------------------------------
Project's translation files are synchronized with `POEditor <https://poeditor.com/projects/view?id=220215>`_.
JavaScript translation strings are stored in a separate `project <https://poeditor.com/projects/view?id=224115>`_.
You will need a POEditor account to edit translations and be added to ``translators@megit.com`` group.

New strings are automatically uploaded to POEditor every time an update is pushed to the ``master`` branch.
Translations are downloaded several times a day with an automated ``sh/update-translations.sh`` script that downloads and validates the translations.
Any errors interrupt the process and a notification is sent to ``translators@megit.com`` address with details.
Translations will not synchronize again until all the issues are resolved.

Un-translatable terms
----------------------
The following terms, when encountered within strings, should be left as-is and never translated:

Placeholders
^^^^^^^^^^^^^^^
These strings are important for correct working of the system, and should always be left as-is, including any words within the brackets.

    * {*placeholder*} - for example: ``{auditor}``
    * {{*placeholder*}} - for example: ``{{auditor}}``
    * %(*placeholder*)s - for example: ``%(auditor)s``
    * %(*placeholder*)d - for example ``%(number)d``


MEG-specific and product names
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The specific terms listed below should never be translated

.. literalinclude:: ../../../locale/notranslate.txt
    :caption: This list can be maintained in :file:`locale/notranslate.txt`

Using translations
######################
`GNU gettext <https://www.gnu.org/software/gettext/>`_ is required to work with translations. Make sure to follow installation instruction specific to your operating system.

To run site with latest translations, compile the messages file::

    ./manage.py compilemessages

All strings displayed to the user should be translatable by using `i18n tools provided by Django <https://docs.djangoproject.com/en/3.2/topics/i18n/translation/>`_.

JavaScript translations
########################
Translations used by front-end JavaScript code that cannot use strings rendered by template, are stored separately, as ``djangojs`` translations.

To use these translations you can call ``gettext`` and its variants within js code.
These are typically available in all pages extending ``base.html`` template, but if you are working on a custom view,
you need to add it separately, by adding ``{% js_catalog %}`` tag. The tag only needs to be included once on the page.
**Note that it replaces django's built-in catalog!**

.. code-block:: html+django

    {% js_catalog %}

    <script>
        alert(gettext("Welcome!"));
    </script>

.. seealso:: `Related django documentation <https://docs.djangoproject.com/en/4.2/topics/i18n/translation/#using-the-javascript-translation-catalog>`_

Adding new language to the project
####################################

Add language to the system
-------------------------------

#. To add support for a language, add it to ``settings.LANGUAGES``. Language code should be *lower case* .
#. Add the language to the respective projects in POEditor
#. For some languages with a country code, it is necessary to edit :file:`poeditor.yaml` for translations to save in a correct folder according to `django specification <https://docs.djangoproject.com/en/5.2/topics/i18n/#term-locale-name>`_

This adds a language option to the user / institution preferences. Some strings may already be translated if Django or 3rd party packages have these strings.

Add language to model translations
-----------------------------------

By default, model translations do not support all the project's languages.
There's a separate setting ``settings.MODELTRANSLATION_LANGUAGES`` where support for individual langages can be added.
The language must already be present in ``settings.LANGUAGES``.

.. note::
    | Adding a language requires schema migrations for all translatable models.
    | To avoid migration conflicts, only add languages when translation is imminent.