SuperAPI AI Directory

qt-translation-helper

General & other

View repository

Updated 10-16 04:41

About this skill

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 Special symbols such as these must remain as-is and must not be translated or converted, otherwise the UI will become misaligned
  7. Never convert HTML entities - &quot;, &amp;, &lt;, &gt; 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"

  1. Scan the project:python script/translate.py scan-project /path/to/qt/project
  2. 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
  3. Scan for items to translate:python script/translate.py scan dde-file-manager.ts -o source_doc.yaml
  4. Create a plan:python script/translate.py plan dde-file-manager.ts *.ts
  5. 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
  6. 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