Serial-Studio/app/translations/README.md

Translation Manager

translation_manager.py is a Python script designed to manage Qt translation files (.ts and .qm). It can be used to:

1. Create new translation source (.ts) files for a given language.
2. Update existing .ts files by running lupdate and removing obsolete strings.
3. Compile .ts files into binary .qm files using lrelease.

Prerequisites

Before using this script, ensure the following tools are installed on your system:

• Qt Linguist: The lupdate and lrelease commands are part of the Qt toolchain. Make sure they are available in your system's path.

You can verify the installation by running:

lupdate --version
lrelease --version

Additionally, ensure that you have Python 3.x installed.

Usage

The script provides three main functionalities:

• Create a new .ts file for a language
• Update existing .ts files using lupdate
• Compile .ts files into .qm files using lrelease

1. Creating a New Translation File

To create a new .ts file for a language, use the --new-ts option followed by the language code (e.g., es_MX for Mexican Spanish):

python3 translation_manager.py --new-ts es_MX

This will generate a new es_MX.ts file in the app/translations/ts folder with the source language set to en_US.

2. Updating Existing .ts Files

To update existing .ts files and remove obsolete entries, use the --lupdate option:

python3 translation_manager.py --lupdate

This will scan the source files (both .cpp, .h, and .qml) in the app and lib directories and update the translations in the .ts files located in the app/translations/ts folder.

3. Compiling .ts Files into .qm Files

To compile the .ts files into binary .qm files for use in the application, use the --lrelease option:

python3 translation_manager.py --lrelease

The .qm files will be generated and placed in the app/translations/qm folder.

4. Running Both lupdate and lrelease

You can also combine both updating and compiling into a single command:

python3 translation_manager.py --lupdate --lrelease

5. Help and Usage Instructions

If no arguments are provided, the script will display the help message:

python3 translation_manager.py

This will output the following information:

usage: translation_manager.py [-h] [--new-ts LANGUAGE] [--lupdate] [--lrelease]

Manage translations with lupdate and lrelease.

optional arguments:
  -h, --help           show this help message and exit
  --new-ts LANGUAGE    Create a new .ts file for the given language code (e.g., "es" for Spanish).
  --lupdate            Run lupdate to update all existing .ts files.
  --lrelease           Run lrelease to compile .ts files into .qm files.

Folder Structure

Here’s an example of the folder structure where the script operates:

app/
├── translations/
│   ├── ts/          # Folder containing the .ts files (source translations)
│   │   ├── en_US.ts
│   │   ├── es_MX.ts
│   │   └── ru_RU.ts
│   ├── qm/          # Folder where the .qm files (compiled translations) are stored
│   └── translation_manager.py   # This script

Example Commands

1. Create a new French translation file (fr_FR.ts):

python3 translation_manager.py --new-ts fr_FR

2. Update all existing .ts files:

python3 translation_manager.py --lupdate

3. Compile .ts files into .qm:

python3 translation_manager.py --lrelease

4. Perform both update and compile:

python3 translation_manager.py --lupdate --lrelease

Notes

• The script assumes that your source language is en_US, and this is automatically set when creating new .ts files.
• Make sure that the lib folder (which contains additional source files) exists at the same level as the app folder.