re2zero Qt Translation Helper Skill
Iron Laws
- Never modify original TS files without backup - Always preserve original content
- Validate AI translation quality - Verify translations are accurate and contextually appropriate
- Maintain translation consistency - Use consistent terminology across all translations
- Respect file encoding - Preserve UTF-8 encoding and special characters
- Minimal changes principle - Only modify translation content, preserve XML structure
- Never translate or convert special placeholders -
%1,%2,\n,\t等特殊符号必须保持原样，不能翻译或转换，否则会导致 UI 不对齐 - Never convert HTML entities -
",&,<,>等 HTML 实体必须保持原样，不能转换为双引号、&、<、>等，否则会导致 UI 显示错误
Red Flags
- User requests translation of non-TS files
- User asks to translate without proper AI configuration
- Requests to overwrite existing translations without verification
- Asks to translate to unsupported language codes
When to Use
- User says "补全翻译", "完成翻译", "translate all", "missing translations"
- Project has multiple .ts files with
type="unfinished"markers - Need to translate a Qt project to multiple languages
- Existing translations are incomplete or out of date
- NOT for: translating non-TS files, single string translation, or project-specific conventions
Rationalization Table
| Excuse | Response |
|---|---|
| "Just translate everything quickly" | Quality matters in localization - proper AI configuration and validation required |
| "We don't need consistent terminology" | Inconsistent translations hurt user experience - consistency is critical |
| "Original files don't need backup" | Always preserve originals - translation errors can corrupt content |
| "Rewrite the whole file" | Only translation text should change - git diff will show other modifications |
Quick Reference
完整工作流（可迁移，用于任何 Qt 项目）
# 1. 扫描项目，发现所有 .ts 文件，列出英文源和目标语言
python script/translate.py scan-project /path/to/qt/project
# 2. 扫描英文源文件，生成翻译文档（只包含待翻译字符串）
python script/translate.py scan dde-file-manager.ts -o source_doc.yaml
# 3. 创建翻译计划（列出所有目标语言，MD 文档）
python script/translate.py plan dde-file-manager.ts *.ts
# 4. 显示计划
python script/translate.py show-plan
# 5. 获取下一个待处理任务
python script/translate.py next-task
# 6. 将 AI 翻译后的文档写回目标文件
python script/translate.py write translated_de.yaml dde-file-manager_de.ts
# 7. 更新任务状态
python script/translate.py update-task de completed -c 335
使用场景：用户说“补全翻译”
- 扫描项目：
python script/translate.py scan-project /path/to/qt/project - 报告情况，等待用户确认：向用户报告发现的所有应用及其目标语言数量，明确等待用户选择要翻译哪个应用（如 dde-file-manager、desktop 等），不要自行决定
- 扫描待翻译：
python script/translate.py scan dde-file-manager.ts -o source_doc.yaml - 创建计划：
python script/translate.py plan dde-file-manager.ts *.ts - 严格按计划执行：
- 获取下一个任务：
python script/translate.py next-task - AI 翻译：将翻译文档交给 AI 会话翻译
- 写回目标文件：
python script/translate.py write translated_de.yaml dde-file-manager_de.ts - 更新任务状态：
python script/translate.py update-task de completed -c 335 - 重复步骤 5，直到所有任务完成
- 获取下一个任务：
- 验证：用 Qt 工具（如 lrelease）生成 .qm 文件验证
核心工作流
digraph workflow {
"用户说补全翻译" [shape=box];
"扫描项目 .ts 文件" [shape=box];
"确认英文源文件" [shape=diamond];
"扫描待翻译字符串" [shape=box];
"AI 翻译" [shape=box];
"写回目标文件" [shape=box];
"验证 .qm" [shape=box];
"完成" [shape=box];
"用户说补全翻译" -> "扫描项目 .ts 文件";
"扫描项目 .ts 文件" -> "确认英文源文件";
"确认英文源文件" -> "扫描待翻译字符串" [label="是"];
"确认英文源文件" -> "选择应用" [label="否"];
"扫描待翻译字符串" -> "AI 翻译";
"AI 翻译" -> "写回目标文件";
"写回目标文件" -> "验证 .qm";
"验证 .qm" -> "完成" [label="通过"];
"验证 .qm" -> "AI 翻译" [label="失败"];
}
Common Mistakes & Fixes
错误：多个 agent 并行翻译时产生冲突
修复：每个 agent 处理一个语言，输出独立的翻译文档，最后再写回
错误：扫描器未正确识别未翻译字符串
修复：确保源文件包含 type="unfinished" 标记
错误：语言代码检测不正确
修复：确保 TS 文件遵循标准命名规范（如 project_zh_CN.ts、project_de.ts）
错误：翻译质量问题
修复：AI 翻译时提供足够的上下文信息
错误：Git diff 显示不必要的更改
修复：工具只修改翻译内容 — 任何其他更改表明需要修复的 bug
错误：未验证翻译结果
修复：使用 Qt 工具（如 lrelease）生成 .qm 文件验证，确保翻译无语法错误
错误：直接修改源文件
修复：始终在 AI 会话中生成翻译文档，写回目标文件，不修改英文源文件
错误：翻译或转换特殊占位符（%1、%2、\n 等）
修复：特殊占位符必须保持原样，不能翻译或转换，否则会导致 UI 不对齐
错误：转换 HTML 实体（"、& 等）
修复：HTML 实体必须保持原样，不能转换为双引号、& 等，否则会导致 UI 显示错误
Architecture
这个技能采用AI 会话驱动工作流，支持并行：
- ProjectScanner：扫描 Qt 项目，发现所有 .ts 文件，按应用分组
- TranslationScanner：扫描英文源 TS 文件，提取待翻译字符串，生成规范 YAML 文档
- PlanManager：管理翻译计划（MD 文档），列出所有目标语言，跟踪任务状态
- TranslationWriter：将翻译结果写回对应的多语言 TS 文件
工作流优势
- 可迁移：用于任何 Qt 项目，无需修改
- AI 会话驱动：利用当前 AI 会话的 LLM 能力，无需外部 API
- 并行支持：每个 agent 处理一个语言，输出独立的翻译文档，避免并行干扰
- 可审查：翻译文档可人工审查后再写回
- MD 计划文档：用 Markdown 表格展示所有目标语言及其状态，每完成一个语言就更新
- 灵活：支持分步执行，也可一键完成完整流程
- 保留上下文：翻译时保留上下文信息，提高准确性
Key Features
- 项目扫描：自动发现 Qt 项目下所有 .ts 文件，按应用分组，识别英文源和目标语言
- MD 翻译计划：用 Markdown 表格展示所有目标语言及其状态，每完成一个语言就更新
- 严格执行计划：AI 必须按照计划中的任务逐一完成，不能跳过，每完成一个任务就更新计划
- 多 agent 并行：每个 agent 处理一个语言，输出独立的翻译文档，避免并行干扰
- 写回目标文件：将翻译结果写回对应的多语言 .ts 文件，保留 XML 结构
- 完全在 AI 会话中进行：无需任何外部 API 或配置，利用当前 AI 会话的 LLM 能力
- 可迁移：用于任何 Qt 项目，无需修改，扫描、翻译、写回一气呵成