# Qt Translation Helper

> Use when user requests translating Qt project localization files (TS files), automating translation workflows, or setting up multilingual support for Qt applications. Triggers: 补全翻译, 完成翻译, 翻译所有语言, translate all, missing translations, unfinished strings, Qt localization, TS file translation, 多语言支持, 翻译补全, 批量翻译, 翻译工作流.

- Skill: `re2zero/qt-translation-helper` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add re2zero/qt-translation-helper`
- Raw SKILL.md: https://api.skillmd.com/api/skills/re2zero/qt-translation-helper/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: re2zero (https://skillmd.com/u/re2zero)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/re2zero/qt-translation-helper

---


# Qt Translation Helper Skill

## Iron Laws

1. **Never modify original TS files without backup** - Always preserve original content
2. **Validate AI translation quality** - Verify translations are accurate and contextually appropriate
3. **Maintain translation consistency** - Use consistent terminology across all translations
4. **Respect file encoding** - Preserve UTF-8 encoding and special characters
5. **Minimal changes principle** - Only modify translation content, preserve XML structure
6. **Never translate or convert special placeholders** - `%1`, `%2`, `\n`, `\t` 等特殊符号必须保持原样，不能翻译或转换，否则会导致 UI 不对齐
7. **Never convert HTML entities** - `&quot;`, `&amp;`, `&lt;`, `&gt;` 等 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 项目）
```bash
# 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
```

### 使用场景：用户说“补全翻译”
1. **扫描项目**：`python script/translate.py scan-project /path/to/qt/project`
2. **报告情况，等待用户确认**：向用户报告发现的所有应用及其目标语言数量，**明确等待用户选择要翻译哪个应用**（如 dde-file-manager、desktop 等），**不要自行决定**
3. **扫描待翻译**：`python script/translate.py scan dde-file-manager.ts -o source_doc.yaml`
4. **创建计划**：`python script/translate.py plan dde-file-manager.ts *.ts`
5. **严格按计划执行**：
   - 获取下一个任务：`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，直到所有任务完成**
6. **验证**：用 Qt 工具（如 lrelease）生成 .qm 文件验证

### 核心工作流
```dot
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 实体（&quot;、&amp; 等）
**修复**：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 项目，无需修改，扫描、翻译、写回一气呵成