Contributing Translations

We welcome community members to help improve Ghost Downloader's multilingual support! If you want to contribute new translations or update existing ones for the project, please follow these steps:

Environment Setup

You need to install the official Qt translation tools:

1. PySide6: Ensure you have installed PySide6 and its related tools according to the steps in the Building from Source guide. pyside6-lupdate and pyside6-lrelease are usually installed along with PySide6.
2. Qt Linguist: This is a graphical translation editing tool used for editing .ts files. You can download and install Qt from the official Qt website (select Tools -> Qt Linguist), or install it through your package manager (e.g., sudo apt install qt6-tools-dev-tools on Debian/Ubuntu, brew install qt6 on macOS).

Update Translation Source Files (.ts)

The project provides a script sync_i18n_res.py to automatically extract translatable text from the source code (.py files in the app/ directory) and update or create .ts files.

1. Run the script (Windows):

   # Run in the project root directory
   python sync_i18n_res.py

   This will update the gd3.zh_CN.ts and gd3.en_US.ts files in the resources/i18n/ directory.

2. Run the script (macOS/Linux): Currently, the sync_i18n_res.py script does not automatically execute the pyside6-lupdate command on non-Windows platforms. You need to execute it manually:

   # Run in the project root directory
   # Assuming you want to update/create the en_US translation
   pyside6-lupdate app/**/*.py -ts resources/i18n/gd3.en_US.ts -source-language zh_CN -target-language en_US -no-ui-lines

   You need to replace app/**/*.py with the actual list of files to scan (the sync_i18n_res.py script generates this list; you can refer to its logic or specify manually), and replace en_US with the target language code you want to process.

3. Add a New Language: If you want to add a completely new language (e.g., fr_FR for French), you need to:

   • Modify the sync_i18n_res.py script, adding the new language code to the targetLanguages list.
   • Run the script (or manually execute pyside6-lupdate) to generate the new .ts file (e.g., resources/i18n/gd3.fr_FR.ts).
   • Add support for the new language in app/common/config.py (may require modifying enums or lists).
   • Ensure the new language's .qm file can be loaded correctly in Ghost-Downloader-3.py.

Edit Translation Files (.ts)

Use the Qt Linguist tool to open the .ts file you need to edit (located in the resources/i18n/ directory).

• Translate the text from the source code item by item.
• For already translated items, ensure accuracy and update as needed.
• Save the .ts file when finished.

Generate Binary Translation Files (.qm)

After editing and saving the .ts file, you need to compile it into a binary .qm file that the application can load using the pyside6-lrelease tool.

# Run in the project root directory
# Compile all .ts files
pyside6-lrelease resources/i18n/gd3.*.ts

# Or compile a single file
# pyside6-lrelease resources/i18n/gd3.en_US.ts -qm resources/i18n/gd3.en_US.qm

The compiled .qm file will be placed in the same directory as the .ts file.

Submit Contribution

1. Add your modified or new .ts files and the generated .qm files to the Git staging area.
2. Commit your changes.
3. Create a Pull Request to the main Ghost Downloader repository.

Thank you for contributing to the internationalization of Ghost Downloader!