SuperAPI AI 工具集

qt-translation-helper

通用与其它

查看项目

更新于 10-16 04:41

技能介绍

用途

Qt Translation Helper 用于 Qt 项目的本地化翻译工作,主要处理 TS(翻译源)文件。当用户提出“补全翻译”“完成翻译”“translate all”“missing translations”等需求,或项目存在多个带 type="unfinished" 标记的 .ts 文件、需要将 Qt 项目翻译为多种语言、已有翻译不完整或过时时,可使用该技能。它不适用于翻译非 TS 文件、单条字符串翻译或项目特定约定的处理。

主要能力

  • 项目扫描:自动发现 Qt 项目下所有 .ts 文件,按应用分组,识别英文源和目标语言。
  • 翻译文档生成:扫描英文源 TS 文件,提取待翻译字符串,生成规范 YAML 文档。
  • 翻译计划管理:用 Markdown 表格展示所有目标语言及其状态,每完成一个语言就更新。
  • 写回目标文件:将翻译结果写回对应的多语言 .ts 文件,保留 XML 结构。
  • 多 agent 并行:每个 agent 处理一个语言,输出独立的翻译文档,避免并行干扰。
  • 完全在 AI 会话中进行:无需任何外部 API 或配置,利用当前 AI 会话的 LLM 能力。
  • 可迁移:用于任何 Qt 项目,无需修改。

使用方式

技能提供脚本 script/translate.py,核心命令包括:

  • 扫描项目:python script/translate.py scan-project /path/to/qt/project
  • 扫描英文源文件生成翻译文档: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 show-plan
  • 获取下一个待处理任务:python script/translate.py next-task
  • 写回目标文件:python script/translate.py write translated_de.yaml dde-file-manager_de.ts
  • 更新任务状态:python script/translate.py update-task de completed -c 335

典型工作流:扫描项目 → 向用户报告发现的应用及目标语言数量并等待用户选择要翻译的应用 → 扫描待翻译字符串 → 创建计划 → 按计划逐一获取任务、AI 翻译、写回目标文件、更新任务状态,重复直到完成 → 用 Qt 工具(如 lrelease)生成 .qm 文件验证。

适用场景

  • 补全 Qt 项目缺失的翻译。
  • 将 Qt 项目翻译为多种语言。
  • 更新过时或不完整的现有翻译。
  • 需要人工审查翻译文档后再写回的项目。

限制与约束

  • 仅处理 TS 文件,不适用于非 TS 文件或单条字符串翻译。
  • 需要正确的 AI 配置,否则不应进行翻译。
  • 不得在未验证的情况下覆盖现有翻译。
  • 不支持的语言代码无法翻译。
  • 必须备份原始 TS 文件,不得修改英文源文件。
  • 必须保持 UTF-8 编码和特殊字符。
  • 只修改翻译内容,保留 XML 结构;任何其他更改表明存在需要修复的 bug。
  • 特殊占位符(%1、%2、\n、\t 等)必须保持原样,不能翻译或转换,否则会导致 UI 不对齐。
  • HTML 实体("、&、<、> 等)必须保持原样,不能转换为双引号、&、<、> 等,否则会导致 UI 显示错误。
  • 翻译质量需验证,确保准确且符合上下文。
  • 需保持术语一致性。
  • 扫描器依赖源文件中的 type="unfinished" 标记来识别未翻译字符串。
  • 语言代码检测依赖标准命名规范(如 project_zh_CN.ts、project_de.ts)。
  • 多个 agent 并行翻译时,每个 agent 处理一个语言并输出独立翻译文档,最后再写回,以避免冲突。
  • 翻译结果需用 Qt 工具(如 lrelease)生成 .qm 文件验证,确保无语法错误。

架构

该技能采用 AI 会话驱动工作流,支持并行,包含以下组件:

  • ProjectScanner:扫描 Qt 项目,发现所有 .ts 文件,按应用分组。
  • TranslationScanner:扫描英文源 TS 文件,提取待翻译字符串,生成规范 YAML 文档。
  • PlanManager:管理翻译计划(MD 文档),列出所有目标语言,跟踪任务状态。
  • TranslationWriter:将翻译结果写回对应的多语言 TS 文件。

工作流优势包括:可迁移、AI 会话驱动、并行支持、可审查、MD 计划文档、灵活(支持分步执行或一键完成)、保留上下文以提高准确性。