illogical-impulse/.config/quickshell/translations/tools/translation-tools-guide.md

Translation Management Tool Suite

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

Tool Components

1. translation-manager.py - Main Translation Manager

• Extract translatable texts
• Compare and update translation files
• Interactive adding/removing translation keys

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

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

3. manage-translations.sh - Convenient Wrapper Script

• Provide unified command-line interface
• Display translation status
• Simplify common operations

Quick Start

Check Translation Status

./manage-translations.sh status

Extract Translatable Texts

./manage-translations.sh extract

Update Translation Files

# Update all languages
./manage-translations.sh update

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

Clean Unused Keys

./manage-translations.sh clean

Sync Keys Across Languages

./manage-translations.sh sync

Detailed Usage

translation-manager.py

The main translation management tool that extracts translatable texts from source code and manages translation files.

Command Line Options

python3 translation-manager.py [options]

Options:
  -h, --help            Show help message
  -t, --translations-dir DIR  Translation files directory (default: .config/quickshell/translations)
  -s, --source-dir DIR  Source code directory (default: .config/quickshell)
  -l, --language LANG   Specify language code to process (e.g., zh_CN)
  -e, --extract-only    Only extract translatable texts to temporary file
  --show-temp           Show temporary extracted file content

Features

1. Text Extraction: Uses regex patterns to extract translatable texts from QML and JavaScript files
2. Smart Filtering: Automatically removes duplicates and cleans up extracted texts
3. Interactive Updates: Guides users through adding missing keys and removing extra ones
4. Backup Support: Creates backups before making changes

Supported Text Patterns

• qsTr("text") and qsTr('text')
• i18n.t("text") and i18n.t('text')
• Supports nested quotes and escape characters
• Handles multiline strings

translation-cleaner.py

A maintenance tool for cleaning up and synchronizing translation files.

Command Line Options

python3 translation-cleaner.py [options]

Options:
  -h, --help            Show help message
  -t, --translations-dir DIR  Translation files directory
  -s, --source-dir DIR  Source code directory
  -c, --clean           Clean unused translation keys
  --sync                Sync translation keys
  --source-lang LANG    Source language for syncing (default: en_US)
  --no-backup           Do not create backup files when cleaning

Features

1. Unused Key Cleanup: Identifies and removes translation keys that are no longer used in the source code
2. Key Synchronization: Ensures all language files have the same set of keys
3. Backup Protection: Creates backup files before making destructive changes
4. Interactive Confirmation: Asks for user confirmation before deleting keys

manage-translations.sh

A convenient wrapper script that provides a unified interface to all translation tools.

Commands

./manage-translations.sh [options] <command>

Commands:
  extract      Extract translatable texts to temporary file
  update       Update translation files (add missing/remove extra keys)
  clean        Clean unused translation keys
  sync         Sync keys across all language files
  status       Show translation status

Options:
  -l, --lang LANG     Specify language (e.g.: zh_CN)
  -t, --trans-dir DIR Translation files directory
  -s, --source-dir DIR Source code directory
  -h, --help          Show help message

Workflow Examples

Initial Setup

1. Create translation directory structure
2. Extract all translatable texts: ./manage-translations.sh extract
3. Create initial translation files: ./manage-translations.sh update

Regular Maintenance

1. Check status: ./manage-translations.sh status
2. Update translations after code changes: ./manage-translations.sh update
3. Clean up unused keys periodically: ./manage-translations.sh clean

Adding New Language

1. Create new language file: ./manage-translations.sh update -l new_lang
2. Sync keys if needed: ./manage-translations.sh sync

File Structure

translations/
├── tools/                          # Translation management tools
│   ├── translation-manager.py      # Main extraction and update tool
│   ├── translation-cleaner.py      # Cleanup and sync tool
│   ├── manage-translations.sh      # Wrapper script
│   └── translation-tools-guide.md  # This documentation
├── en_US.json                      # English translations (reference)
├── zh_CN.json                      # Chinese translations
└── [other_lang].json               # Other language files

Configuration

Text Extraction Patterns

The tool uses regex patterns to identify translatable texts. Current patterns include:

1. QML qsTr patterns:

   • qsTr("text") and qsTr('text')
   • Supports escaped quotes and nested quotes

2. JavaScript i18n patterns:

   • i18n.t("text") and i18n.t('text')
   • Supports template literals and complex expressions

3. Custom patterns can be added by modifying the patterns list in translation-manager.py

File Extensions

By default, the tool processes:

• .qml files (QML/QtQuick)
• .js files (JavaScript)

Additional file types can be added by modifying the file extension filters.

Best Practices

1. Regular Updates: Run ./manage-translations.sh status regularly to check for new translatable texts
2. Clean Periodically: Use ./manage-translations.sh clean to remove unused keys
3. Backup Important: Always backup translation files before major changes
4. Consistent Patterns: Use consistent function calls (qsTr, i18n.t) for translatable texts
5. Review Changes: Always review the changes before confirming deletions or additions

Troubleshooting

Common Issues

1. Missing Texts: If some translatable texts are not extracted, check if they match the supported patterns
2. Path Issues: Ensure the source and translation directory paths are correct
3. Permission Errors: Make sure the script has write permissions to the translation directory
4. Encoding Issues: All files should be saved in UTF-8 encoding

Getting Help

For additional help:

• Use --help option with any tool
• Check the console output for error messages
• Verify file paths and permissions

Advanced Usage

Custom Regex Patterns

To add support for new translation function patterns, modify the patterns list in TranslationManager.extract_translatable_texts():

patterns = [
    # Existing patterns...
    r'customTranslate\s*\(\s*(["\'])((?:\\.|(?!\1)[^\\])*?)\1\s*\)',  # Custom pattern
]

Batch Processing

For processing multiple projects or directories:

# Process multiple directories
for dir in project1 project2 project3; do
    ./manage-translations.sh -s "$dir" -t "$dir/translations" update
done

Integration with Build Systems

The tools can be integrated into build systems to automatically update translations:

# In your build script
./manage-translations.sh update --non-interactive

Version History

• v1.0: Initial version with basic extraction and update functionality
• v1.1: Added improved regex patterns for better text extraction
• v1.2: Added cleaning and synchronization tools
• v1.3: Added English output and improved user interface
• v1.4: Moved all tools to dedicated tools directory and improved documentation