forked from Shinonome/dots-hyprland
i18n: update translations/tools/README.md
This commit is contained in:
月月
@@ -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
|
||||||
|
|
||||||
```
|
### 1. `translation-manager.py` - Main Translation Manager
|
||||||
translations/
|
- Extract translatable texts
|
||||||
├── tools/ # Translation management tools directory
|
- Compare and update translation files
|
||||||
│ ├── translation-manager.py # Main translation manager
|
- Interactive addition/removal of translation keys
|
||||||
│ ├── translation-cleaner.py # Translation maintenance tool
|
|
||||||
│ ├── manage-translations.sh # Convenient wrapper script
|
### 2. `translation-cleaner.py` - Translation File Maintenance Tool
|
||||||
│ ├── translation-tools-guide.md # Detailed usage documentation
|
- Clean unused translation keys
|
||||||
│ └── README.md # This file
|
- Synchronize key structure across different language files
|
||||||
├── en_US.json # English translation file
|
|
||||||
├── zh_CN.json # Chinese translation file
|
### 3. `manage-translations.sh` - Convenient Wrapper Script
|
||||||
└── ... # Other language files
|
- Provides a unified command-line interface
|
||||||
```
|
- Displays translation status
|
||||||
|
- Simplifies common operations
|
||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
### Running from tools directory
|
### Using the Wrapper Script (Recommended)
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Enter tools directory
|
# Enter the tools directory
|
||||||
cd .config/quickshell/translations/tools
|
cd .config/quickshell/translations/tools
|
||||||
|
|
||||||
# Check current translation status
|
# Show help
|
||||||
|
./manage-translations.sh --help
|
||||||
|
|
||||||
|
# Show current translation status
|
||||||
./manage-translations.sh status
|
./manage-translations.sh status
|
||||||
|
|
||||||
|
# Extract translatable texts
|
||||||
|
./manage-translations.sh extract
|
||||||
|
|
||||||
# Update all translation files
|
# Update all translation files
|
||||||
./manage-translations.sh update
|
./manage-translations.sh update
|
||||||
|
|
||||||
# Update specific language
|
# Update a specific language
|
||||||
./manage-translations.sh update -l zh_CN
|
./manage-translations.sh update -l zh_CN
|
||||||
|
|
||||||
# Clean unused keys
|
# Clean unused keys
|
||||||
./manage-translations.sh clean
|
./manage-translations.sh clean
|
||||||
|
|
||||||
# Sync all language files
|
# Synchronize keys across all language files
|
||||||
./manage-translations.sh sync
|
./manage-translations.sh sync
|
||||||
```
|
```
|
||||||
|
|
||||||
### Running from project root directory
|
Or run from the project root:
|
||||||
|
|
||||||
```bash
|
```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 status
|
||||||
.config/quickshell/translations/tools/manage-translations.sh update
|
.config/quickshell/translations/tools/manage-translations.sh update
|
||||||
```
|
```
|
||||||
|
|
||||||
## Tool Description
|
## Detailed Usage
|
||||||
|
|
||||||
### 🛠️ `manage-translations.sh` - Main Entry Point
|
### Translation Manager (`translation-manager.py`)
|
||||||
Convenient command-line interface that integrates all translation management functions.
|
|
||||||
|
|
||||||
### 🔍 `translation-manager.py` - Core Manager
|
Basic usage:
|
||||||
- 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
|
|
||||||
```bash
|
```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
|
```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
|
## Workflow
|
||||||
```bash
|
|
||||||
./manage-translations.sh update -l new_language_code
|
|
||||||
```
|
|
||||||
|
|
||||||
### Check translation status
|
### Regular Translation Update Workflow
|
||||||
```bash
|
|
||||||
./manage-translations.sh status
|
|
||||||
```
|
|
||||||
|
|
||||||
## 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
|
### Adding a New Language
|
||||||
2. **Backup**: Cleanup operations automatically create backup files
|
|
||||||
3. **Encoding**: All files use UTF-8 encoding
|
|
||||||
4. **Permissions**: Ensure scripts have execution permissions
|
|
||||||
|
|
||||||
## 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
|
```qml
|
||||||
qsTr("Your text here")
|
// Basic format
|
||||||
qsTr('Single quotes work too')
|
Translation.tr("Hello, world!")
|
||||||
i18n.t("JavaScript translations")
|
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.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user