publish: the public projection begins here
This is a projection, not a development branch. The tree above was constructed from the internal source named below under a manifest that decides which paths may leave, then scanned as a whole tree rather than as a series of patches, and only then published. Public history starts here because the history before it was not admissible, and neither was the tree. What used to stand in this repository included a rescue copy of another machine, a directory of phone handoffs, deployment wired to one house, and a submodule pointing at a forge no stranger can reach. None of that was ever the product. It stays in the private forge, which is allowed to hold the whole working organism, and this is what was deliberately sent out instead. Three mechanisms produced this tree, in decreasing order of trust. A top-level path the manifest does not name never arrives at all, which is the one that catches directories nobody has thought of yet. Named internal files inside admitted roots are dropped. A short, reviewed table replaces deployment defaults that a public build must not carry -- an endpoint aimed at one LAN, a VPN profile belonging to one phone, packaging built from one checkout path. Everything after this commit is an ordinary publication with the same three trailers, so a force push stops being routine and starts meaning that something deliberate happened. The trailers bind the projection to its source without pretending the public SHA is the private one: same lineage, different tree, and the record says so. Source-Sha: 8f27b1e76a8fef560a336aba18e6990713ff1047 Policy-Sha: 6b261d2f3e6e1fb19874846ba4bb1dfe15565d25b8618c1c1afba0419c101d27 Tree-Digest: 18ec3563c5e5ef9a414993a9f6734b251ff9ed3cd56eebdd6cac01e45c6e3067
This commit is contained in:
Fimeg
commit
8f42fc953d
1476 changed files with 238455 additions and 0 deletions
|
|
@ -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/
|
||||
```
|
||||
Loading…
Reference in a new issue