i18n 翻译检查与补充

快速开始（推荐安全用法）

强制前提：先用 Git 保证当前工作区是干净的（或至少 locales 相关改动可回滚），再运行下面任何脚本。

1. 只在必要范围格式化翻译文件（建议从后端/英文开始）

   • 后端 JSON 一般是纯英文，占位少，优先安全：

   python .cursor/skills/i18n-check/scripts/format_frontend.py
   python .cursor/skills/i18n-check/scripts/format_backend.py
   

   • format_frontend.py

     会重写所有

     frontend/src/locales/*.ts

     ：
     • 仅做语法级重排与缩进，不再对字符做任何再编码；
     • 仍然建议：先只在当前分支本地运行，确认 diff 可接受后再提交。

2. 对比翻译差异（只读，不改文件）:

   python .cursor/skills/i18n-check/scripts/compare_frontend.py
   python .cursor/skills/i18n-check/scripts/compare_backend.py
   

3. 补全缺失的 key（使用中文作为占位符）

   • 推荐做法：先只对英文和后端补全，再视情况扩展到其他语言。

   # 仅补前端英文（安全范围小）
   python .cursor/skills/i18n-check/scripts/fill_frontend.py --target en-US
   
   # 补全所有前端语言（会改动所有 locales，务必在 Git 干净时使用）
   python .cursor/skills/i18n-check/scripts/fill_frontend.py
   
   # 补全所有后端语言（JSON，风险相对可控）
   python .cursor/skills/i18n-check/scripts/fill_backend.py
   

4. AI 翻译（自动检测需要翻译的内容，不会直接改 TS/JSON 文件）

   # 翻译特定语言
   python .cursor/skills/i18n-check/scripts/translate_with_ai.py --target en-US
   
   # 翻译所有语言（包括 CJK 语言）
   python .cursor/skills/i18n-check/scripts/translate_with_ai.py --all --cjk
   

5. CJK 语言翻译后检测（翻译完成后检查是否还有未翻译）

   # 导出 CJK 语言未翻译内容到文本文件
   python .cursor/skills/i18n-check/scripts/export_translations.py --target ja-JP --cjk
   
   # 填充后检测 CJK 语言未翻译 key
   python .cursor/skills/i18n-check/scripts/fill_frontend.py --check-cjk
   

完整工作流程（推荐顺序）

# Step 0: 确认 Git 状态
# - 确保 frontend/src/locales 和 internal/services/i18n/locales 内的改动都可回滚
# - 不要在未提交的重要改动上直接批量格式化/补全

# Step 1: 格式化（可选，但推荐先只在后端/英文上尝试）
python .cursor/skills/i18n-check/scripts/format_frontend.py
python .cursor/skills/i18n-check/scripts/format_backend.py

# Step 2: 对比（只读）
python .cursor/skills/i18n-check/scripts/compare_frontend.py
python .cursor/skills/i18n-check/scripts/compare_backend.py

# Step 3: 补全缺失 key（中文占位）
# 先补英文，再按需扩展其他语言
python .cursor/skills/i18n-check/scripts/fill_frontend.py --target en-US
python .cursor/skills/i18n-check/scripts/fill_backend.py

# Step 4: AI 翻译（前端 + 后端）
# 脚本会自动检测需要翻译的内容并生成翻译提示（只读，不改 TS/JSON）
python .cursor/skills/i18n-check/scripts/translate_with_ai.py --all
# 仅处理后端 JSON 时，可显式指定：
# python .cursor/skills/i18n-check/scripts/translate_with_ai.py --type backend --all

# Step 5: 翻译完成后检测 CJK 语言
# 对于 ja-JP, ko-KR, zh-TW，检测是否还有未翻译内容
python .cursor/skills/i18n-check/scripts/fill_frontend.py --check-cjk
python .cursor/skills/i18n-check/scripts/translate_with_ai.py --cjk

# Step 6: 导出未翻译内容到文本，统一翻译后再导入
python .cursor/skills/i18n-check/scripts/export_translations.py --target ja-JP --cjk
# 手动翻译文本文件中的内容
python .cursor/skills/i18n-check/scripts/import_translations.py --file translation_export_ja-JP.txt

脚本说明

脚本位置

所有脚本位于

.cursor/skills/i18n-check/scripts/

format_frontend.py

compare_frontend.py

--cjk

fill_frontend.py

--check-cjk

translate_with_ai.py

--cjk

export_translations.py

--cjk

import_translations.py

format_backend.py

compare_backend.py

fill_backend.py

使用示例

对比 CJK 语言

# 对比特定 CJK 语言与英文
python compare_frontend.py --target ja-JP --cjk

# 对比所有 CJK 语言
python compare_frontend.py --cjk-only

填充 CJK 语言

# 填充时使用 CJK 模式
python fill_frontend.py --cjk

# 检测 CJK 语言未翻译 key
python fill_frontend.py --check-cjk

AI 翻译脚本

# 翻译特定语言
python translate_with_ai.py --type frontend --target en-US

# 翻译 CJK 语言
python translate_with_ai.py --target ja-JP --cjk

# 翻译所有语言（包括 CJK）
python translate_with_ai.py --all --cjk

导出翻译

# 导出 CJK 语言未翻译内容
python export_translations.py --target ja-JP --cjk

翻译检测逻辑

• 非 CJK 语言 (en-US, de-DE, fr-FR 等): 检测含有中文的 key，需要翻译
• CJK 语言 (zh-TW, ja-JP, ko-KR): 检测与非 CJK 语言（如 en-US）相同的 key，需要翻译成对应语言

CJK 语言特殊处理

对于日语 (ja-JP)、韩语 (ko-KR)、繁体中文 (zh-TW)，采用以下检测逻辑：

1. 对比方式: 不以 zh-CN 为基准，而是与英语等非 CJK 语言对比
2. 检测原理: 如果某个 key 在目标语言中的值与英语相同，说明该 key 未翻译
3. 导出格式: 显示 baseline(中文) | reference(英语) | current(当前值)，便于翻译

AI 翻译流程

1. 运行

   translate_with_ai.py

   脚本
2. 脚本会自动：
   • 读取目标语言文件
   • 检测需要翻译的中文内容（或 CJK 未翻译内容）
   • 生成 AI 翻译提示 (prompt)
3. 将生成的提示复制给 AI 进行翻译
4. AI 返回 JSON 格式的翻译结果
5. 使用

   import_translations.py

   导入翻译结果

文件位置

frontend/src/locales/

.ts

zh-CN.ts

en-US.ts

internal/services/i18n/locales/

.json

zh-CN.json

en-US.json

注意事项

• 保持 key 结构: 必须与基准文件完全一致，使用相同的嵌套层级
• 不要删除任何内容: 只能添加缺失的 key，不能删除现有的 key
• 变量占位符: 后端 JSON 使用

  {{.xxx}}

  格式，前端使用

  {xxx}

  格式，必须保留
• 格式化后再对比: 每次对比前先运行格式化脚本，确保格式统一
• CJK 语言处理: 繁体中文(zh-TW)、日语(ja-JP)、韩语(ko-KR)使用英语(en-US)作为基准文件进行对比和填充