From 0c2b807447a94ac7bce58c4f117a9c2a3485c5c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9C=88=E6=9C=88?= <3600911665@qq.com> Date: Sun, 13 Jul 2025 15:24:29 +0800 Subject: [PATCH] i18n: update translations/tools/README.md --- .../quickshell/translations/tools/README.md | 305 ++++++++++++++---- 1 file changed, 241 insertions(+), 64 deletions(-) diff --git a/.config/quickshell/translations/tools/README.md b/.config/quickshell/translations/tools/README.md index 1840f6c3d..e41c742e9 100644 --- a/.config/quickshell/translations/tools/README.md +++ b/.config/quickshell/translations/tools/README.md @@ -1,111 +1,288 @@ -# Translation Management Tools +# Translation Management Tool Suite -This directory contains a toolset for managing project translation files. +This suite is used to manage project translation files, automatically extract translatable texts, compare differences between language files, and provide maintenance functions. -## Directory Structure +## Tool Components -``` -translations/ -├── tools/ # Translation management tools directory -│ ├── translation-manager.py # Main translation manager -│ ├── translation-cleaner.py # Translation maintenance tool -│ ├── manage-translations.sh # Convenient wrapper script -│ ├── translation-tools-guide.md # Detailed usage documentation -│ └── README.md # This file -├── en_US.json # English translation file -├── zh_CN.json # Chinese translation file -└── ... # Other language files -``` +### 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 -### Running from tools directory +### Using the Wrapper Script (Recommended) ```bash -# Enter tools directory +# Enter the tools directory cd .config/quickshell/translations/tools -# Check current translation status +# 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 specific language +# Update a specific language ./manage-translations.sh update -l zh_CN # Clean unused keys ./manage-translations.sh clean -# Sync all language files +# Synchronize keys across all language files ./manage-translations.sh sync ``` -### Running from project root directory - +Or run from the project root: ```bash -# Run from project root directory (recommended to use relative paths) +# Run from the project root .config/quickshell/translations/tools/manage-translations.sh status .config/quickshell/translations/tools/manage-translations.sh update ``` -## Tool Description +## Detailed Usage -### 🛠️ `manage-translations.sh` - Main Entry Point -Convenient command-line interface that integrates all translation management functions. +### Translation Manager (`translation-manager.py`) -### 🔍 `translation-manager.py` - Core Manager -- Extract translatable texts -- Compare translation file differences -- Interactive translation updates - -### 🧹 `translation-cleaner.py` - Maintenance Tool -- Clean unused translation keys -- Sync language file structure -- Create backup files - -## Common Workflows - -### After adding new translatable texts +Basic usage: ```bash -./manage-translations.sh update +# 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 ``` -### Clean up after code refactoring +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`) + ```bash -./manage-translations.sh clean +# 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 ``` -### Add new language -```bash -./manage-translations.sh update -l new_language_code -``` +## Workflow -### Check translation status -```bash -./manage-translations.sh status -``` +### Regular Translation Update Workflow -## Documentation +1. **Check status**: + ```bash + ./manage-translations.sh status + ``` -- 📖 [Detailed Usage Guide](./translation-tools-guide.md) +2. **Update translations**: + ```bash + ./manage-translations.sh update + ``` -## Important Notes +3. **Clean unused keys** (optional): + ```bash + ./manage-translations.sh clean + ``` -1. **Running Location**: Tools automatically detect relative paths, can be run from tools directory or project root -2. **Backup**: Cleanup operations automatically create backup files -3. **Encoding**: All files use UTF-8 encoding -4. **Permissions**: Ensure scripts have execution permissions +### Adding a New Language -## Supported Translation Formats +1. **Create a new language file**: + ```bash + ./manage-translations.sh update -l new_lang + ``` + +2. **Synchronize key structure**: + ```bash + ./manage-translations.sh sync + ``` + +### Cleanup After Large Refactoring + +1. **Backup translation files**: + ```bash + cp -r .config/quickshell/translations .config/quickshell/translations.backup + ``` + +2. **Clean unused keys**: + ```bash + ./manage-translations.sh clean + ``` + +3. **Synchronize all languages**: + ```bash + ./manage-translations.sh sync + ``` + +## Supported Translatable Text Formats + +The tool recognizes the following formats for translatable texts: -The tool recognizes translatable texts in the following formats: ```qml -qsTr("Your text here") -qsTr('Single quotes work too') -i18n.t("JavaScript translations") +// 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) +Translation.tr("{0} files selected").arg(count) ``` ---- +## 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 + +```bash +# Use custom directories +./translation-manager.py \ + --translations-dir /path/to/translations \ + --source-dir /path/to/source +``` + +### Batch Processing + +```bash +# Create a processing script +cat > update-all-translations.sh << 'EOF' +#!/bin/bash +for lang in zh_CN ja_JP ko_KR; do + echo "Processing $lang..." + ./manage-translations.sh update -l $lang +done +EOF + +chmod +x update-all-translations.sh +./update-all-translations.sh +``` + +## 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 + - 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: 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 + +```bash +# 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/ +``` -If you have any issues, please refer to the detailed documentation or check error messages in script output.