
Translating GUI strings
=======================

The GUI strings for the tuning utility are managed using the Qt
translation system. The translations are stored in ``.ts`` files, which
are XML files containing the strings used in the GUI and their
translations.

To ensure a string is in the translation system, it must be wrapped in the
``QCoreApplication.translate()`` function. For ease of use when using
parameter names from lib_audio_dsp, the function ``tuning_utility.translations.tr_str``
is provided. This wraps the ``QCoreApplication.translate()`` function in a Python
dictionary, allowing strings from lib_audio_dsp to be translated.

.. code-block:: Python

    from tuning_utility.translations import tr_str

    # Example usage
    label_text = tr_str("Parameter Name")

    # Alternatively, you can use the QCoreApplication.translate() directly
    from PySide6.QtCore import QCoreApplication
    label_text = QCoreApplication.translate("Context", "Parameter Name")

If the translation does not exist in the dictionary, the original string
will be returned, and a warning will be logged to the console.

Note that on WSL, Chinese fonts are not installed by default, so they may need to
be installed by calling::

    sudo apt-get update
    sudo apt-get install fonts-noto-cjk

Adding/updating new locales
===========================

To generate a new locale or update an existing one, you can use the ``translations.py`` script.
This script will extract the strings from the GUI and generate a new locale file or update an existing one.

The locale files are stored in the ``locale`` directory, and the script will update a ``.ts`` file.
To update all the locales if the GUI has been modified, run the following command:

.. code-block:: PowerShell

    python translations.py -generate

This will update all the .ts files in the locale folder. To create a new locale, copy the ``en.ts``
file and rename it to the desired locale code (e.g., ``fr.ts`` for French). Then, you can translate
the strings in that file.

The .ts files are XML files that contain the strings used in the GUI. For ease of translation, these
can be converted to .csv files using the ``ts2csv.py`` script. This will create a CSV file with the
strings and their translations, which can be edited in a spreadsheet application.
Note the file encoding is UTF-8.

After editing, you can convert the CSV file back to a .ts file using the ``csv2ts.py`` script. This 
will generate a new .ts file with the updated translations. Ensure the language tag
``<TS version="2.1" language="fr">`` line in the .ts file is updated to reflect the correct language code.

Once the translations are in the .ts files, they can be be compiled using the command:

.. code-block:: PowerShell

    python translations.py -compile

This will compile the .ts files into .qm binary files, which are used by the application for translations.