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,\tSpecial symbols such as these must remain as-is and must not be translated or converted, otherwise the UI will become misaligned - Never convert HTML entities -
",&,<,>HTML entities such as these must remain as-is and must not be converted to double quotes,&、<、>etc., otherwise the UI will display incorrectly
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 "Complete the translation", "Finish the translation", "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
Complete workflow (portable, usable for any Qt project)
# 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
Use case: the user says "complete translations"
- Scan the project:
python script/translate.py scan-project /path/to/qt/project - Report the situation and wait for user confirmation: report to the user all discovered applications and their target language counts,explicitly wait for the user to choose which application to translate(such as dde-file-manager, desktop, etc.),do not decide on your own
- Scan for items to translate:
python script/translate.py scan dde-file-manager.ts -o source_doc.yaml - Create a plan:
python script/translate.py plan dde-file-manager.ts *.ts - Execute strictly according to the plan:
- Get the next task:
python script/translate.py next-task - AI translation: hand the translation document to the AI session for translation
- Write back to the target file:
python script/translate.py write translated_de.yaml dde-file-manager_de.ts - Update task status:
python script/translate.py update-task de completed -c 335 - Repeat step 5 until all tasks are complete
- Get the next task:
- Verify: use Qt tools (such as lrelease) to generate .qm files for verification
Core workflow
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
Error: conflicts occur when multiple agents translate in parallel
Fix: each agent handles one language, outputs an independent translation document, and writes back at the end
Error: the scanner does not correctly identify untranslated strings
Fix: ensure the source file contains the type="unfinished" marker
Error: language code detection is incorrect
Fix: ensure TS files follow the standard naming convention (such as project_zh_CN.ts、project_de.ts)
Error: translation quality issues
Fix: provide sufficient context information during AI translation
Error: Git diff shows unnecessary changes
Fix: the tool only modifies translation content — any other changes indicate a bug that needs fixing
Error: translation results not verified
Fix: use Qt tools (such as lrelease) to generate .qm files for verification, ensuring the translations have no syntax errors
Error: directly modifying source files
Fix: always generate the translation document in the AI session, write back to the target file, and do not modify the English source file
Error: translating or converting special placeholders (%1, %2, \n, etc.)
Fix: special placeholders must remain as-is and must not be translated or converted, otherwise the UI will become misaligned
Error: converting HTML entities (", &, etc.)
Fix: HTML entities must remain as-is and must not be converted to double quotes,& etc., otherwise the UI will display incorrectly
Architecture
This skill usesan AI session-driven workflow, supporting parallelism:
- ProjectScanner: scan the Qt project, discover all .ts files, and group them by application
- TranslationScanner: scan the English source TS files, extract untranslated strings, and generate standardized YAML documents
- PlanManager: manage the translation plan (MD document), list all target languages, and track task status
- TranslationWriter: write the translation results back to the corresponding multilingual TS files
Workflow advantages
- Portable: Works with any Qt project, no modifications needed
- AI session-driven: Leverages the LLM capabilities of the current AI session, no external API needed
- Parallel support: Each agent handles one language and outputs an independent translation document, avoiding parallel interference
- Reviewable: Translation documents can be manually reviewed before being written back
- MD plan document: Uses a Markdown table to display all target languages and their status, updating each time a language is completed
- Flexible: Supports step-by-step execution, or completing the entire workflow with one click
- Preserve context: Preserves context information during translation to improve accuracy
Key Features
- Project scanning: Automatically discovers all .ts files under a Qt project, groups them by application, and identifies English source and target languages
- MD translation plan: Uses a Markdown table to display all target languages and their status, updating each time a language is completed
- Strictly execute the plan: The AI must complete the tasks in the plan one by one without skipping any, and update the plan each time a task is completed
- Multi-agent parallel: Each agent handles one language and outputs an independent translation document, avoiding parallel interference
- Write back to target files: Writes the translation results back to the corresponding multilingual .ts files, preserving the XML structure
- Entirely within the AI session: No external API or configuration needed, leveraging the LLM capabilities of the current AI session
- Portable: Works with any Qt project, no modifications needed, with scanning, translation, and write-back completed in one go