Translation Guide

This guide explains how to contribute translations to RimSort. The project uses PySide6’s Qt internationalization (i18n) system with QTranslator.

Translation System Overview
Project Structure
Currently Supported Languages
Translation Helper Tool
Quick Start
How to Contribute Translations
Translation Status Tracking
Maintenance and Updates
1. When Source Code Changes

Translation System Overview

RimSort uses Qt’s translation system with the following components:

.ts files: Source translation files (XML format) that translators edit
.qm files: Compiled binary translation files used by the application
QTranslator: Qt’s translation engine that loads and applies translations

Project Structure

RimSort/
├── locales/           # Translation files directory
│   ├── en_US.ts      # English (source language)
│   ├── zh_CN.ts      # Simplified Chinese
│   ├── fr_FR.ts      # French
│   ├── de_DE.ts      # German
│   ├── es_ES.ts      # Spanish
│   └── ja_JP.ts      # Japanese
└── app/
    └── controllers/
        └── language_controller.py  # Language management

Currently Supported Languages

Language Code	Language Name	Status
`en_US`	English	Complete (source)
`zh_CN`	简体中文 (Simplified Chinese)	Partial
`fr_FR`	Français (French)	Needs translation
`de_DE`	Deutsch (German)	Needs translation
`es_ES`	Español (Spanish)	Needs translation
`ja_JP`	日本語 (Japanese)	Needs translation

Translation Helper Tool

The project provides a translation_helper.py script to assist with translation work.

Important Note: This tool is implemented using PySide6 commands and requires a properly configured development environment. Please refer to the Development Setup Guide to set up your environment before using this tool.

Main features include:

Check translation completeness
Show translation statistics
Validate translation file format
Update translation files
Compile translation files

For specific usage methods, please refer to the “Testing Your Translation” section.

Quick Start

If you want to get started quickly with translation work, you can follow this simplified process:

Fork and clone the project
Set up development environment (following the Development Setup Guide)
Choose language file: Open locales/YOUR_LANGUAGE.ts
Edit translations: Find entries marked as type="unfinished" and translate them
Compile and test: Run python translation_helper.py compile YOUR_LANGUAGE
Submit code: Commit both .ts and .qm files

For detailed steps, please refer to the complete guide below.

How to Contribute Translations

Prerequisites

Before starting translation work, you need to prepare the following:

Development Environment (Required)
- Set up the project development environment following the Development Setup Guide
- This includes installing Python 3.12, PySide6, and project dependencies
Translation Editor
- Recommended: Text editor with XML syntax highlighting (VS Code, Sublime Text, Notepad++, etc.)
- Optional: Qt Linguist (requires separate Qt development environment installation)
Version Control Tools
- Git version control system
- GitHub account for contributing code

Step 1: Set Up Your Environment

Fork the RimSort repository on GitHub

Clone your fork:

git clone https://github.com/YOUR_USERNAME/RimSort.git
cd RimSort

Create a new branch for your translation:

git checkout -b translation-LANGUAGE_CODE
# Example: git checkout -b translation-pt_BR

Step 2: Choose Your Contribution Type

Option A: Improve Existing Translation

Navigate to the locales/ directory
Open the existing .ts file for your language (e.g., en_US.ts)
Look for entries marked as type="unfinished" or empty <translation> tags

Option B: Create New Language Translation

Use PySide6 tools to generate new translation file:
Linux/macOS systems:
```
pyside6-lupdate $(find app -name "*.py") -ts locales/NEW_LANGUAGE_CODE.ts -no-obsolete
# Example:
pyside6-lupdate $(find app -name "*.py") -ts locales/pt_BR.ts -no-obsolete
```
Windows systems (recommended to use translation helper tool):
```
# Use translation helper tool (recommended, simpler)
python translation_helper.py update-ts pt_BR
```
If you need to manually use PySide6 tools, you can refer to the Linux/macOS command format, but using the translation helper tool is recommended to avoid complex path handling.
Update the language attribute in the file:
```
<TS version="2.1" language="pt_BR">
```
Register the new language in the language controller:
Open the file app/controllers/language_controller.py and find the language_map dictionary in the populate_languages_combobox method, add your language:
```
language_map = {
    "en_US": "English",
    "es_ES": "Español", 
    "fr_FR": "Français",
    "de_DE": "Deutsch",
    "zh_CN": "简体中文",
    "ja_JP": "日本語",
    "pt_BR": "Português (Brasil)",  # Add new language entry
}
```
Where "pt_BR" is the language code and "Português (Brasil)" is the language name that will be displayed in the settings interface.

Step 3: Translation Process

Using Text Editor (Recommended)

Open the .ts file in your preferred text editor

Find <message> blocks that need translation:

<message>
    <location filename="../app/views/settings_dialog.py" line="896"/>
    <source>Select Language (Restart required to apply changes)</source>
    <translation type="unfinished"></translation>
</message>

Replace the empty translation with your text and remove type="unfinished":

<message>
    <location filename="../app/views/settings_dialog.py" line="896"/>
    <source>Select Language (Restart required to apply changes)</source>
    <translation>Selecionar Idioma (Reinicialização necessária para aplicar as alterações)</translation>
</message>

Using Qt Linguist (Optional)

If you already have Qt Linguist installed, you can also use it:

Open Qt Linguist
File → Open → Select your .ts file
Translate each string:
- Select an untranslated item from the list
- Enter your translation in the “Translation” field
- Mark as “Done” when satisfied
- Add translator comments if needed
Save your work: File → Save

Step 4: Translation Guidelines

Context Understanding

Each translatable string has context information:

Filename: Shows which file contains the string
Line number: Exact location in the source code
Context name: Usually the class name (e.g., “SettingsDialog”, “ModInfo”)

Translation Best Practices

Preserve formatting:
- Keep \n for line breaks
- Maintain %s, %d, {0}, {variable_name} placeholders
- Preserve HTML tags if present
UI considerations:
- Keep translations concise for button labels
- Consider text expansion (some languages need more space)
- Maintain the tone consistent with the application
Technical terms handling principles:
- “Mod”: Keep as “Mod” in all languages (has become an internationally accepted term)
- “Workshop”: Can be translated to localized terms or kept as original
- Software-specific terms: Maintain consistency, recommend checking existing translations as reference
- UI element names: Such as “Settings”, “Options” should be translated to corresponding language
- File formats and extensions: Such as “.ts”, “.qm” should be kept as original

Example Translation

<!-- English source -->
<source>Sort mods</source>
<translation>Ordenar mods</translation>

<!-- With placeholders -->
<source>Found {count} mods</source>
<translation>Encontrados {count} mods</translation>

<!-- With line breaks -->
<source>Click OK to save settings
and restart the application</source>
<translation>Haz clic en Aceptar para guardar la configuración
y reiniciar la aplicación</translation>

Step 5: Testing Your Translation

5.1 Validate Translation File

Use the translation helper tool for file validation:

   # Check translation completeness for a specific language
   python translation_helper.py check YOUR_LANGUAGE
   # Example: python translation_helper.py check zh_CN

   # Validate translation file format and content
   python translation_helper.py validate YOUR_LANGUAGE
   # This checks for placeholder mismatches, HTML tag issues, etc.

   # View completion status for all languages
   python translation_helper.py stats

5.2 Compile and Test Translation

Compile translation file:
```
# Using translation helper tool (recommended)
python translation_helper.py compile YOUR_LANGUAGE
# Example: python translation_helper.py compile zh_CN
   
# Or use PySide6 tools directly
pyside6-lrelease locales/YOUR_LANGUAGE.ts
```
Note: Compilation generates corresponding .qm files in the locales/ directory. In this project, these .qm files are also committed to version control to ensure users can directly use translation features after downloading without additional compilation steps.

5.3 Test in Application

Launch RimSort and switch language:
- Run python -m app to start the application
- Click “Settings” in the menu bar
- Find the “Language” option
- Select your language from the dropdown menu
- Restart the application when prompted to apply changes
Functional testing:
- Main interface: Check menu bar, toolbar, and status bar text
- Settings dialog: Verify all options and buttons are translated
- Mod management: Test mod list, sorting, and filtering function labels
- Error messages: Trigger some warnings or errors to check if messages are translated
Visual inspection:
- Text adaptation: Ensure translated text displays completely in UI elements
- Button sizing: Check if buttons can accommodate longer translated text
- Dialog layout: Verify dialogs remain properly sized after displaying translations
- Tooltips: Hover over various elements to check tooltip translations

Step 6: Submit Your Contribution

Commit your changes:

# Add translation files (including .ts source files and compiled .qm files)
git add locales/YOUR_LANGUAGE.ts
git add locales/YOUR_LANGUAGE.qm
# If you added a new language, also update the language controller
git add app/controllers/language_controller.py
git commit -m "Add/Update [Language Name] translation"

Note: Both .ts source files and compiled .qm files need to be committed in this project to ensure users can directly use translation features without additional compilation steps.

Push to your fork:

git push origin translation-LANGUAGE_CODE

Create Pull Request:
- Go to your fork on GitHub
- Click “Compare & pull request” or “New Pull Request”
- Select your translation branch as the source branch
- Write a clear title in the format: “Add Portuguese translation” or “Update Chinese translation”
- In the description, mention:
  - Translation completion percentage (e.g., “Completed 80% of string translations”)
  - Main changes
  - Whether further testing is needed

Pull Request Title Examples:

Add French translation (fr_FR)
Improve German translation - Fix interface terminology
Update Japanese translation - Add settings page translations

Translation Status Tracking

You can check translation completeness by looking for:

type="unfinished" entries (need translation)
Empty <translation></translation> tags
type="obsolete" entries (may need review)

Maintenance and Updates

When Source Code Changes

When RimSort’s source code is updated, there may be new translatable strings added or existing strings modified. You will need to update translation files:

# Update translation files to include the latest translatable strings
python translation_helper.py update-ts YOUR_LANGUAGE

After updating, you only need to translate new or modified strings; existing translations will be preserved.

Translation File Format

The .ts files use XML format with this structure:

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE TS>
<TS version="2.1" language="LANGUAGE_CODE">
<context>
    <name>ClassName</name>
    <message>
        <location filename="../path/to/file.py" line="123"/>
        <source>English text</source>
        <translation>Translated text</translation>
    </message>
</context>
</TS>

Thank you for helping make RimSort accessible to users worldwide! 🌍