add-ui-translation

name	add-ui-translation
description	Add a new translation language to the application. Use when adding support for a new locale/language code, creating .po files from the .pot template, registering language codes in internationalization.py, LANGUAGE_CHOICES, tasks.json, pyproject.toml classifiers, and the Windows installer.

Translate the user interface

Adding a translation

To add a new translation language to the Ardupilot Methodic Configurator, follow the steps below. This process involves creating a new language folder in the locale directory and generating the necessary translation files. You will use the create_pot_file.py script to extract the strings that need translation and create a .pot file, which serves as a template for the translation.

1. Set Up Your Local Code Repository

If not done already navigate to a directory where you want to checkout the git repository and execute:

git clone https://github.com/ArduPilot/MethodicConfigurator.git
cd MethodicConfigurator

On Windows do:

.\SetupDeveloperPC.bat
.\install_msgfmt.bat
.\install_wsl.bat

On Linux and macOS do:

./SetupDeveloperPC.sh

2. Create a New Language Directory

Navigate to the locale directory inside your project:

cd ardupilot_methodic_configurator/locale

Create a new folder for the language you want to add. The name of the folder should follow the standard language code format (e.g., de for German, fr for French).

mkdir <language_code>

For example, to add support for German:

mkdir de

Add the language to the end of the LANGUAGE_CHOICES array in the ardupilot_methodic_configurator/internationalization.py file.

For example, to add support for German:

LANGUAGE_CHOICES = ["en", "zh_CN", "pt", "de", "it", "ja"]

Add it also to the test on tests\test_internationalization.py file:

    def test_language_choices(self) -> None:
        expected_languages = ["en", "zh_CN", "pt", "de", "it", "ja"]
        assert expected_languages == LANGUAGE_CHOICES

and .vscode\tasks.json file:

            "description": "Select language code:",
            "options": ["all", "zh_CN", "pt", "de", "it", "ja"],

and add the language as Natural Language :: to the classifiers array in the ardupilot_methodic_configurator/pyproject.toml file.

3. Create a New PO File

Inside your newly created language directory, create a new .po file using the .pot template:

cd de
mkdir LC_MESSAGES
cp ../ardupilot_methodic_configurator.pot LC_MESSAGES/ardupilot_methodic_configurator.po

4. Bulk translate the strings (optional)

You can bootstrap your translation using translation services that translate full files. To do so navigate to the project root and issue:

cd ..\..\..
python extract_missing_translations.py --lang-code=de

It will store the result of the bulk translations into n missing_translations_de[_n].txt file(s).

Now translate that file(s), or feed it to on-line translation service. Put all missing translations into a single missing_translations_de.txt Once done, insert the translations into the .po file:

python insert_missing_translations.py --lang-code=de

5. Translate the Strings

Open the ardupilot_methodic_configurator.po file in a text editor or a specialist translation tool (e.g., Poedit). You will see the extracted strings, which you can begin translating.

Each entry will look like this:

msgid "Original English String"
msgstr ""

Fill in the msgstr lines with your translations:

msgid "Original English String"
msgstr "Translated String"

6. Compile the PO File

Once you have completed your translations, you will need to compile the .po file into a binary .mo file. This can be done using the command:

On Windows:

python create_mo_files.py

On Linux or macOS:

python3 create_mo_files.py

Make sure you have msgfmt installed, which is part of the GNU gettext package. On Windows use the .\install_msgfmt.bat command.

7. Test the New Language

Add it to the [Languages] and [Icons] sections of the windows/ardupilot_methodic_configurator.iss file.

[Languages]
Name: "en"; MessagesFile: "compiler:Default.isl"
Name: "zh_CN"; MessagesFile: "compiler:Languages\ChineseSimplified.isl"
Name: "pt"; MessagesFile: "compiler:Languages\Portuguese.isl"
Name: "de"; MessagesFile: "compiler:Languages\German.isl"
...

With the new .mo file created, you should ensure the software correctly loads the new language. Update the software's configuration to set the desired language and run the application to test your translations.

8. Review and Refine

Once the new language is running in the software, review the translations within the application for clarity and correctness. Make adjustments as needed in the .po file and recompile to an .mo file.

Following these steps should enable you to successfully add support for any new translation language within the Ardupilot Methodic Configurator.

Update an existing translation

There is a github action to automatically update the translations using AI. To manually update an existing translation do the following steps:

1. Install Poedit and open the .po and pot files

Install Poedit v3.5.2 or greater on your PC.

Open the existing .po file for your language. Either download the file from the locale directory in github.com or if you have a local git checkout of ardupilot_methodic_configurator/locale use it.

Here is an example for the italian translation:

Update the translation by importing the latest .pot file.

Either download the file from the locale directory in github.com or if you have a local git checkout of ardupilot_methodic_configurator/locale use it.

Validate the translation

2. Update and improve each translation string

Search the table for strings that have not been translated yet and translate them. Update and improve each translation string.

Save the result and either send the .po file to the team, or create a gitlab Pull request with the changes to the .po file. The github robot will automatically convert that .po file into a .mo file and create an ArduPilot methodic configurator installer that you can use to test the translations.