Translation Guide

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

Table of Contents

  1. Translation Guide
    1. Table of Contents
    2. Translation System Overview
    3. Project Structure
    4. Currently Supported Languages
    5. Translation Helper Tool
      1. Available Commands
        1. Interactive Mode (Recommended for New Users)
        2. Basic Commands
        3. Advanced Commands
      2. Command Examples
      3. Features
      4. Advanced Configuration Options
    6. Quick Start
      1. Option 1: Interactive Mode (Recommended for New Users)
      2. Option 2: Command-Line Mode
    7. How to Contribute Translations
      1. Prerequisites
      2. Step 1: Set Up Your Environment
      3. Step 2: Choose Your Contribution Type
        1. Option A: Improve Existing Translation
        2. Option B: Create New Language Translation
      4. Step 3: Translation Process
        1. Using Text Editor (Recommended)
        2. Using Qt Linguist (Optional)
      5. Step 4: Translation Guidelines
        1. Context Understanding
        2. Translation Best Practices
        3. Example Translation
      6. Step 5: Testing Your Translation
        1. 5.1 Validate Translation File
        2. 5.2 Compile and Test Translation
        3. 5.3 Test in Application
      7. Step 6: Submit Your Contribution
    8. Translation Status Tracking
    9. Maintenance and Updates
      1. When Source Code Changes
      2. Translation File Format

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
│   ├── zh_TW.ts      # Traditional Chinese
│   ├── fr_FR.ts      # French
│   ├── de_DE.ts      # German
│   ├── es_ES.ts      # Spanish
│   ├── ja_JP.ts      # Japanese
│   ├── pt_BR.ts      # Portuguese (Brazil)
│   ├── ru_RU.ts      # Russian
│   └── tr_TR.ts      # Turkish
└── app/
    └── controllers/
        └── language_controller.py  # Language management

Currently Supported Languages

Language CodeLanguage NameStatus
en_USEnglishComplete (source)
zh_CN简体中文 (Simplified Chinese)Complete
zh_TW正體中文 (Traditional Chinese)In Progress
fr_FRFrançais (French)Complete
de_DEDeutsch (German)Complete
es_ESEspañol (Spanish)Complete
ja_JP日本語 (Japanese)Complete
pt_BRPortuguês (Brasil)Complete
ru_RUРусский (Russian)Complete
tr_TRTürkçe (Turkish)Complete

Translation Helper Tool

The project provides a comprehensive 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.

Available Commands

The translation helper tool provides the following commands:

  • --interactive or -i: Launch an interactive guided menu for managing translations
    • User-friendly prompts for language selection
    • Service selection with descriptions
    • Configuration options (timeout, retries, concurrency)
    • Confirmation prompts before operations
    • Perfect for non-technical translators

Basic Commands

All basic commands support both single language and batch (all languages) modes:

  • check [language]: Check translation completeness
    • check zh_CN - Check specific language only
    • check - Check all languages at once (batch operation)
    • Option: --json to output structured JSON for programmatic use
  • stats: Show translation statistics for all languages
    • Option: --json to output structured JSON for programmatic use
  • validate [language]: Validate translation file format and content, automatically fixing common issues
    • validate zh_CN - Validate specific language only
    • validate - Validate all languages at once (batch operation)
  • update-ts [language]: Update .ts files with new strings from the source language
    • update-ts zh_CN - Update specific language only
    • update-ts - Update all languages at once (batch operation)
  • compile [language]: Compile .ts files into binary .qm format
    • compile zh_CN - Compile specific language only
    • compile - Compile all languages at once (batch operation)

Advanced Commands

  • auto-translate [language] --service [google|deepl|openai]: Auto-translate unfinished strings using various translation services
    • auto-translate zh_CN --service google - Auto-translate specific language only
    • auto-translate --service google - Auto-translate all languages at once (batch operation)
    • Google Translate: Free, supports all languages, no API key required
    • DeepL: High-quality translations, requires API key, supports major European languages (EN, FR, DE, ES, PT, IT, NL, PL, RU not supported)
    • OpenAI GPT: AI-powered translations, requires API key, supports major languages (RU, TR, PT-BR not supported)
    • Options: --api-key for service authentication, --model for OpenAI model selection, --continue-on-failure to skip failed translations
    • Additional options: --timeout, --max-retries, --max-concurrent, --no-cache for configuration
  • process [language] --service [google|deepl|openai]: One-click workflow that runs update-ts → auto-translate → compile in sequence
    • process zh_CN --service google - Full workflow for specific language only
    • process --service google - Full workflow for all languages at once (batch operation)
    • Uses the same translation services and limitations as auto-translate (Google: all languages, DeepL: major European languages except RU, OpenAI: major languages except RU/TR/PT-BR)
    • Same options as auto-translate: --api-key, --model, --continue-on-failure
    • Configuration options: --timeout, --max-retries, --max-concurrent, --no-cache

Command Examples

# Interactive mode (recommended for new users)
python translation_helper.py --interactive
python translation_helper.py -i

# Check completeness for all languages
python translation_helper.py check

# Check specific language
python translation_helper.py check zh_CN

# Check with JSON output (for programmatic use)
python translation_helper.py check --json
python translation_helper.py check zh_CN --json

# View statistics for all languages
python translation_helper.py stats

# View statistics as JSON
python translation_helper.py stats --json

# Validate and auto-fix all languages (batch operation)
python translation_helper.py validate

# Validate specific language only
python translation_helper.py validate zh_CN

# Update translation files for all languages (batch operation)
python translation_helper.py update-ts

# Update translation file for specific language
python translation_helper.py update-ts zh_CN

# Auto-translate specific language using Google (free, no API key needed)
python translation_helper.py auto-translate zh_CN --service google

# Auto-translate ALL languages using Google (batch operation)
python translation_helper.py auto-translate --service google

# Auto-translate using DeepL (requires API key)
python translation_helper.py auto-translate zh_CN --service deepl --api-key YOUR_DEEPL_KEY

# Auto-translate all languages using DeepL (batch operation, requires API key)
python translation_helper.py auto-translate --service deepl --api-key YOUR_DEEPL_KEY

# Auto-translate using OpenAI (requires API key)
python translation_helper.py auto-translate zh_CN --service openai --api-key YOUR_OPENAI_KEY --model gpt-4

# Auto-translate all languages using OpenAI (batch operation, requires API key)
python translation_helper.py auto-translate --service openai --api-key YOUR_OPENAI_KEY --model gpt-4

# Auto-translate with configuration options
python translation_helper.py auto-translate zh_CN --service google --timeout 30 --max-retries 5 --max-concurrent 10

# Auto-translate without using cache (fresh translations only)
python translation_helper.py auto-translate zh_CN --service google --no-cache

# One-click complete workflow for specific language
python translation_helper.py process zh_CN --service google

# One-click complete workflow for all languages (batch operation)
python translation_helper.py process --service google

# Compile specific language
python translation_helper.py compile zh_CN

# Compile all languages (batch operation)
python translation_helper.py compile

Features

  • Interactive Mode: User-friendly guided workflow perfect for new users and non-technical translators
  • Batch Operations: Most commands support operating on all languages when no specific language is provided
  • Auto-Fixing Validation: The validate command automatically fixes placeholder and HTML tag mismatches
  • Multiple Translation Services: Support for Google Translate (free), DeepL, and OpenAI with configurable models
  • Error Handling: Robust error handling with retry logic and SSL fixes for Google Translate
  • JSON Output: Structured JSON output for programmatic use and CI/CD integration
  • Progress Tracking: Real-time progress bars and detailed statistics
  • Configuration Options: Customizable timeout, retry attempts, and concurrent request limits
  • Concurrency: Optimized parallel processing for faster bulk operations

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

Advanced Configuration Options

The translation helper supports several advanced options for fine-tuning behavior:

  • --timeout (float, default: 10.0): Request timeout in seconds. Increase for slower networks.
  • --max-retries (int, default: 3): Maximum number of retry attempts for failed requests with exponential backoff.
  • --max-concurrent (int, default: 5): Maximum concurrent API requests. Balance speed vs API rate limits.
  • --no-cache: Skip using the translation cache for the current run. Useful for forcing fresh translations.
  • --continue-on-failure: By default enabled. Disable with --no-continue-on-failure to abort on first failure.

Cache Management:

The translation helper maintains a persistent cache file (.translation_cache.json) to reduce API calls and costs. Cached translations are reused automatically across runs. To clear the cache and request fresh translations:

# Clear cache and disable it for this run
python translation_helper.py auto-translate zh_CN --service google --no-cache

Quick Start

If you want to get started quickly with translation work, you have two options:

  1. Fork and clone the project
  2. Set up development environment (following the Development Setup Guide)
  3. Launch interactive mode: Run python translation_helper.py --interactive
  4. Follow the guided menu:
    • Select “Check translation completeness” to see what needs translation
    • Select “Auto-translate missing strings” to fill in gaps with AI
    • Select “Full process” to update, translate, and compile all at once
  5. Submit code: Commit both .ts and .qm files

Option 2: Command-Line Mode

  1. Fork and clone the project
  2. Set up development environment (following the Development Setup Guide)
  3. Choose language file: Open locales/YOUR_LANGUAGE.ts
  4. Edit translations: Find entries marked as type="unfinished" and translate them
  5. Auto-translate remaining strings (optional): Run python translation_helper.py auto-translate YOUR_LANGUAGE --service google
  6. Compile and test: Run python translation_helper.py compile YOUR_LANGUAGE
  7. 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:

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

Step 1: Set Up Your Environment

  1. Fork the RimSort repository on GitHub

  2. Clone your fork:

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

  3. 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

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

Option B: Create New Language Translation

  1. 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.

  2. Update the language attribute in the file:

    <TS version="2.1" language="pt_BR">

  3. 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)

  1. Open the .ts file in your preferred text editor

  2. 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>

  3. 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:

  1. Open Qt Linguist
  2. File → Open → Select your .ts file
  3. 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
  4. 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

  1. Preserve formatting:
    • Keep \n for line breaks
    • Maintain %s, %d, {0}, {variable_name} placeholders
    • Preserve HTML tags if present
  2. UI considerations:
    • Keep translations concise for button labels
    • Consider text expansion (some languages need more space)
    • Maintain the tone consistent with the application
  3. 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

  1. 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

  1. 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
  2. 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
  3. 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

  1. 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.

  2. Push to your fork:

    git push origin translation-LANGUAGE_CODE

  3. 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! 🌍