forked from Shinonome/dots-hyprland
i18n: Refactor translation management tools and add ignore feature for dynamic resources
- Updated README.md to reflect changes in translation management tools and added ignore mark feature for dynamic resources. - Created Chinese translation guide for the translation management tools. - Created English translation guide for the translation management tools. - Enhanced translation-cleaner.py to skip keys marked with /*keep*/ during cleanup. - Improved translation-manager.py to create backups only when updating keys interactively. - Updated zh_CN.json with new translations and added ignore marks for dynamic values.
This commit is contained in:
月月
@@ -0,0 +1,286 @@
|
||||
# 翻译管理工具套件
|
||||
|
||||
这套工具用于管理项目的翻译文件，自动提取可翻译文本，比较不同语言文件之间的差异，并提供维护功能。
|
||||
|
||||
## 工具组成
|
||||
|
||||
### 1. `translation-manager.py` - 主要翻译管理器
|
||||
- 提取可翻译文本
|
||||
- 比较和更新翻译文件
|
||||
- 交互式添加/删除翻译键
|
||||
|
||||
### 2. `translation-cleaner.py` - 翻译文件维护工具
|
||||
- 清理不再使用的翻译键
|
||||
- 同步不同语言文件的键结构
|
||||
|
||||
### 3. `manage-translations.sh` - 便捷包装脚本
|
||||
- 提供统一的命令行界面
|
||||
- 显示翻译状态
|
||||
- 简化常用操作
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 使用便捷脚本（推荐）
|
||||
|
||||
```bash
|
||||
# 进入工具目录
|
||||
cd .config/quickshell/translations/tools
|
||||
|
||||
# 查看帮助
|
||||
./manage-translations.sh --help
|
||||
|
||||
# 显示当前翻译状态
|
||||
./manage-translations.sh status
|
||||
|
||||
# 提取可翻译文本
|
||||
./manage-translations.sh extract
|
||||
|
||||
# 更新所有翻译文件
|
||||
./manage-translations.sh update
|
||||
|
||||
# 更新特定语言
|
||||
./manage-translations.sh update -l zh_CN
|
||||
|
||||
# 清理不再使用的键
|
||||
./manage-translations.sh clean
|
||||
|
||||
# 同步所有语言文件的键
|
||||
./manage-translations.sh sync
|
||||
```
|
||||
|
||||
或者从项目根目录运行：
|
||||
```bash
|
||||
# 从项目根目录运行
|
||||
.config/quickshell/translations/tools/manage-translations.sh status
|
||||
.config/quickshell/translations/tools/manage-translations.sh update
|
||||
```
|
||||
|
||||
## 详细使用说明
|
||||
|
||||
### 翻译管理器 (`translation-manager.py`)
|
||||
|
||||
基本用法：
|
||||
```bash
|
||||
# 处理所有语言
|
||||
./translation-manager.py
|
||||
|
||||
# 指定特定语言
|
||||
./translation-manager.py --language zh_CN
|
||||
|
||||
# 仅提取可翻译文本
|
||||
./translation-manager.py --extract-only
|
||||
|
||||
# 显示提取的文本
|
||||
./translation-manager.py --extract-only --show-temp
|
||||
```
|
||||
|
||||
参数说明：
|
||||
- `--translations-dir`, `-t`: 翻译文件目录（默认：`.config/quickshell/translations`）
|
||||
- `--source-dir`, `-s`: 源代码目录（默认：`.config/quickshell`）
|
||||
- `--language`, `-l`: 指定要处理的语言代码
|
||||
- `--extract-only`, `-e`: 仅提取可翻译文本
|
||||
- `--show-temp`: 显示临时提取文件的内容
|
||||
|
||||
### 翻译清理器 (`translation-cleaner.py`)
|
||||
|
||||
```bash
|
||||
# 清理不再使用的翻译键
|
||||
./translation-cleaner.py --clean
|
||||
|
||||
# 同步翻译键（以 en_US 为基准）
|
||||
./translation-cleaner.py --sync
|
||||
|
||||
# 指定不同的源语言进行同步
|
||||
./translation-cleaner.py --sync --source-lang zh_CN
|
||||
|
||||
# 清理时不创建备份
|
||||
./translation-cleaner.py --clean --no-backup
|
||||
```
|
||||
|
||||
## 工作流程
|
||||
|
||||
### 日常翻译更新流程
|
||||
|
||||
1. **检查状态**：
|
||||
```bash
|
||||
./manage-translations.sh status
|
||||
```
|
||||
|
||||
2. **更新翻译**：
|
||||
```bash
|
||||
./manage-translations.sh update
|
||||
```
|
||||
|
||||
3. **清理无用键**（可选）：
|
||||
```bash
|
||||
./manage-translations.sh clean
|
||||
```
|
||||
|
||||
### 新增语言流程
|
||||
|
||||
1. **创建新语言文件**：
|
||||
```bash
|
||||
./manage-translations.sh update -l new_lang
|
||||
```
|
||||
|
||||
2. **同步键结构**：
|
||||
```bash
|
||||
./manage-translations.sh sync
|
||||
```
|
||||
|
||||
### 大规模重构后的清理流程
|
||||
|
||||
1. **备份翻译文件**：
|
||||
```bash
|
||||
cp -r .config/quickshell/translations .config/quickshell/translations.backup
|
||||
```
|
||||
|
||||
2. **清理无用键**：
|
||||
```bash
|
||||
./manage-translations.sh clean
|
||||
```
|
||||
|
||||
3. **同步所有语言**：
|
||||
```bash
|
||||
./manage-translations.sh sync
|
||||
```
|
||||
|
||||
## 支持的翻译文本格式
|
||||
|
||||
工具可以识别以下格式的可翻译文本：
|
||||
|
||||
```qml
|
||||
// 基本格式
|
||||
Translation.tr("Hello, world!")
|
||||
Translation.tr('Hello, world!')
|
||||
Translation.tr(`Hello, world!`)
|
||||
|
||||
// 带换行符
|
||||
Translation.tr("Line 1\nLine 2")
|
||||
|
||||
// 带转义字符
|
||||
Translation.tr("Say \"Hello\"")
|
||||
|
||||
// 带参数占位符
|
||||
Translation.tr("Hello, %1!").arg(name)
|
||||
```
|
||||
|
||||
## 示例输出
|
||||
|
||||
### 状态显示
|
||||
```
|
||||
$ ./manage-translations.sh status
|
||||
正在分析翻译状态...
|
||||
=== 当前项目状态 ===
|
||||
提取到 166 个可翻译文本
|
||||
|
||||
=== 翻译文件状态 ===
|
||||
en_US: 470 个键
|
||||
zh_CN: 470 个键
|
||||
```
|
||||
|
||||
### 更新翻译
|
||||
```
|
||||
$ ./manage-translations.sh update -l zh_CN
|
||||
更新翻译文件...
|
||||
==================================================
|
||||
处理语言: zh_CN
|
||||
==================================================
|
||||
分析结果:
|
||||
缺少的键: 5
|
||||
多余的键: 20
|
||||
|
||||
发现 5 个缺少的翻译键：
|
||||
1. "New feature text"
|
||||
2. "Another new text"
|
||||
...
|
||||
|
||||
是否添加这 5 个缺少的键？ (y/n): y
|
||||
已添加 5 个键
|
||||
|
||||
发现 20 个多余的翻译键：
|
||||
1. "Removed old text" -> "已删除的旧文本"
|
||||
...
|
||||
|
||||
是否删除这 20 个多余的键？ (y/n): y
|
||||
已删除 20 个键
|
||||
|
||||
已保存翻译文件
|
||||
```
|
||||
|
||||
### 清理无用键
|
||||
```
|
||||
$ ./manage-translations.sh clean
|
||||
清理不再使用的翻译键...
|
||||
处理语言: zh_CN
|
||||
发现 50 个不再使用的键:
|
||||
1. "old_unused_text"
|
||||
2. "deprecated_message"
|
||||
...
|
||||
|
||||
是否删除这 50 个不再使用的键？ (y/n): y
|
||||
已删除 50 个键
|
||||
原始键数: 470, 清理后: 420
|
||||
```
|
||||
|
||||
## 高级功能
|
||||
|
||||
### 自定义目录结构
|
||||
|
||||
```bash
|
||||
# 使用自定义目录
|
||||
./translation-manager.py \
|
||||
--translations-dir /path/to/translations \
|
||||
--source-dir /path/to/source
|
||||
```
|
||||
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **备份重要**：在执行清理操作前，工具会自动创建备份，但建议手动备份重要文件
|
||||
|
||||
2. **文本提取限制**：
|
||||
- ~~只支持静态字符串，不支持动态构建的字符串~~
|
||||
- 动态资源（如变量拼接、运行时生成的文本）无法自动提取，需要在翻译文件中手动添加，并使用 `/*keep*/` 标记进行忽略管理。
|
||||
- 必须使用 `Translation.tr()` 格式
|
||||
### 忽略标记功能
|
||||
|
||||
对于动态资源或特殊文本，如果不希望被自动清理，可在翻译值末尾添加 `/*keep*/`，工具会自动忽略这些键，不会在清理和同步时删除。
|
||||
|
||||
示例：
|
||||
```json
|
||||
{
|
||||
"dynamic_key": "Some dynamic value /*keep*/"
|
||||
}
|
||||
```
|
||||
|
||||
3. **文件编码**：所有文件必须使用 UTF-8 编码
|
||||
|
||||
4. **键名规范**：建议使用英文作为键名，避免使用特殊字符
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
|
||||
**Q: 添加了 Translation.tr 后文字不显示？**
|
||||
A: 需要在 QML 文件中使用 `import "root:/"` 导入翻译功能，否则无法正常显示翻译文本。
|
||||
|
||||
**Q: 提取的文本数量与预期不符？**
|
||||
A: 检查是否所有可翻译文本都使用了 `Translation.tr()` 格式，确保没有动态构建的字符串。
|
||||
|
||||
**Q: 同步后某些翻译丢失？**
|
||||
A: 检查源语言文件是否包含所有必要的键，考虑使用不同的源语言进行同步。
|
||||
|
||||
**Q: 清理操作删除了需要的键？**
|
||||
A: 从自动创建的备份文件中恢复，检查源代码中是否正确使用了 `Translation.tr()`。
|
||||
|
||||
### 恢复备份
|
||||
|
||||
```bash
|
||||
# 恢复单个文件
|
||||
cp .config/quickshell/translations/zh_CN.json.backup .config/quickshell/translations/zh_CN.json
|
||||
|
||||
# 恢复所有文件
|
||||
cp .config/quickshell/translations.backup/* .config/quickshell/translations/
|
||||
```
|
||||
@@ -0,0 +1,285 @@
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
# 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`)
|
||||
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
./manage-translations.sh status
|
||||
```
|
||||
|
||||
2. **Update translations**:
|
||||
```bash
|
||||
./manage-translations.sh update
|
||||
```
|
||||
|
||||
3. **Clean unused keys** (optional):
|
||||
```bash
|
||||
./manage-translations.sh clean
|
||||
```
|
||||
|
||||
### Adding a New Language
|
||||
|
||||
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:
|
||||
|
||||
```qml
|
||||
// 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```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/
|
||||
```
|
||||
Reference in New Issue
Block a user