illogical-impulse/.config/quickshell/translations/tools

Translation Management Tool Suite

This suite is used to manage project translation files, automatically extract translatable texts, compare differences between language files, and provide maintenance functions.

Tool Components

1. translation-manager.py - Main Translation Manager

• Extract translatable texts
• Compare and update translation files
• Interactive addition/removal of translation keys

2. translation-cleaner.py - Translation File Maintenance Tool

• Clean unused translation keys
• Synchronize key structure across different language files

3. manage-translations.sh - Convenient Wrapper Script

• Provides a unified command-line interface
• Displays translation status
• Simplifies common operations

Quick Start

Using the Wrapper Script (Recommended)

# Enter the tools directory
cd .config/quickshell/translations/tools

# Show help
./manage-translations.sh --help

# Show current translation status
./manage-translations.sh status

# Extract translatable texts
./manage-translations.sh extract

# Update all translation files
./manage-translations.sh update

# Update a specific language
./manage-translations.sh update -l zh_CN

# Clean unused keys
./manage-translations.sh clean

# Synchronize keys across all language files
./manage-translations.sh sync

Or run from the project root:

# Run from the project root
.config/quickshell/translations/tools/manage-translations.sh status
.config/quickshell/translations/tools/manage-translations.sh update

Detailed Usage

Translation Manager (translation-manager.py)

Basic usage:

# Process all languages
./translation-manager.py

# Specify a particular language
./translation-manager.py --language zh_CN

# Extract translatable texts only
./translation-manager.py --extract-only

# Show extracted texts
./translation-manager.py --extract-only --show-temp

Parameter description:

• --translations-dir, -t: Translation files directory (default: .config/quickshell/translations)
• --source-dir, -s: Source code directory (default: .config/quickshell)
• --language, -l: Specify the language code to process
• --extract-only, -e: Only extract translatable texts
• --show-temp: Show the content of the temporary extraction file

Translation Cleaner (translation-cleaner.py)

# Clean unused translation keys
./translation-cleaner.py --clean

# Synchronize translation keys (using en_US as the base)
./translation-cleaner.py --sync

# Specify a different source language for syncing
./translation-cleaner.py --sync --source-lang zh_CN

# Clean without creating backups
./translation-cleaner.py --clean --no-backup

Workflow

Regular Translation Update Workflow

1. Check status:

   ./manage-translations.sh status
   

2. Update translations:

   ./manage-translations.sh update
   

3. Clean unused keys (optional):

   ./manage-translations.sh clean
   

Adding a New Language

1. Create a new language file:

   ./manage-translations.sh update -l new_lang
   

2. Synchronize key structure:

   ./manage-translations.sh sync
   

Cleanup After Large Refactoring

1. Backup translation files:

   cp -r .config/quickshell/translations .config/quickshell/translations.backup
   

2. Clean unused keys:

   ./manage-translations.sh clean
   

3. Synchronize all languages:

   ./manage-translations.sh sync
   

Supported Translatable Text Formats

The tool recognizes the following formats for translatable texts:

// Basic format
Translation.tr("Hello, world!")
Translation.tr('Hello, world!')
Translation.tr(`Hello, world!`)

// With line breaks
Translation.tr("Line 1\nLine 2")

// With escape characters
Translation.tr("Say \"Hello\"")

// With parameter placeholders
Translation.tr("Hello, %1!").arg(name)

Example Output

Status Display

$ ./manage-translations.sh status
Analyzing translation status...
=== Current Project Status ===
166 translatable texts extracted

=== Translation File Status ===
  en_US: 470 keys
  zh_CN: 470 keys

Update Translations

$ ./manage-translations.sh update -l zh_CN
Updating translation files...
==================================================
Processing language: zh_CN
==================================================
Analysis result:
  Missing keys: 5
  Extra keys: 20

Found 5 missing translation keys:
1. "New feature text"
2. "Another new text"
...

Add these 5 missing keys? (y/n): y
5 keys added

Found 20 extra translation keys:
1. "Removed old text" -> "已删除的旧文本"
...

Delete these 20 extra keys? (y/n): y
20 keys deleted

Translation file saved

Clean Unused Keys

$ ./manage-translations.sh clean
Cleaning unused translation keys...
Processing language: zh_CN
Found 50 unused keys:
  1. "old_unused_text"
  2. "deprecated_message"
  ...

Delete these 50 unused keys? (y/n): y
50 keys deleted
Original key count: 470, after cleaning: 420

Advanced Features

Custom Directory Structure

# Use custom directories
./translation-manager.py \
  --translations-dir /path/to/translations \
  --source-dir /path/to/source

Ignore Mark Feature

For dynamic resources or special texts that should not be automatically cleaned, you can add /*keep*/ at the end of the translation value. The tool will automatically ignore these keys and will not delete them during cleaning or syncing.

Example:

{
  "dynamic_key": "Some dynamic value /*keep*/"
}

Notes

1. Backup is important: The tool automatically creates backups before cleaning, but it is recommended to manually back up important files

2. Text extraction limitations:

   • Only supports static strings, not dynamically constructed strings
   • Dynamic resources (such as variable concatenation or runtime-generated text) cannot be automatically extracted. You need to manually add them to the translation file and use the /*keep*/ mark for ignore management.
   • Must use the Translation.tr() format

3. File encoding: All files must use UTF-8 encoding

4. Key naming conventions: It is recommended to use English for key names and avoid special characters

Troubleshooting

Common Issues

Q: Text does not appear after adding Translation.tr? A: You need to import the translation feature in your QML file using import "root:/", otherwise the translation text will not be displayed correctly.

Q: The number of extracted texts does not match expectations? A: Check whether all translatable texts use the Translation.tr() format and ensure there are no dynamically constructed strings.

Q: Some translations are missing after syncing? A: Check whether the source language file contains all necessary keys, and consider using a different source language for syncing.

Q: The cleaning operation deleted needed keys? A: Restore from the automatically created backup file and check whether Translation.tr() is used correctly in the source code.

Restore Backup

# Restore a single file
cp .config/quickshell/translations/zh_CN.json.backup .config/quickshell/translations/zh_CN.json

# Restore all files
cp .config/quickshell/translations.backup/* .config/quickshell/translations/