Translation Check

翻译校验

miot-plugin-sdk 插件项目所有功能文案必须中英文双语。校验覆盖键名一致性、硬编码、翻译质量、新增补全。

项目约定

修复规范（必须遵守）

1. 双语同步：在 zh.js 与 en.js 同时添加相同 key，禁止只改一侧。
2. 英文风格：简洁、符合当前产品类型/智能家居产品语气；专有名词（Mesh、Mi Home、Bluetooth 等）与现有 en.js 保持一致。
3. 硬编码替换：替换为 i18nStrings["key"] 或 i18nStrings.alias；无对应 key 则双语同步新增。
4. 英文大小写：仅首个单词首字母大写（Sentence case），其余单词小写；专有名词（Mesh、Mi Home、Bluetooth、ACT 等）保持规范写法。
5. 修复后验证：每次修改后重新运行脚本确认通过，未通过则继续修复直至 PASS。

校验流程

复制并跟踪进度：

校验进度：
- [ ] 1. 键名一致性（脚本）
- [ ] 2. 硬编码文案扫描
- [ ] 3. 翻译质量审查
- [ ] 4. 修复并双语同步
- [ ] 5. 重新运行脚本确认 PASS

1. 键名一致性

在项目根目录执行（路径按实际项目调整）：

node ~/.cursor/skills/translation-check/scripts/check-keys.js Main/strings/zh.js Main/strings/en.js

脚本输出：

• MISSING_IN_EN — zh 有、en 缺
• MISSING_IN_ZH — en 有、zh 缺
• DUPLICATE_KEYS — 同文件内重复 key（后者覆盖前者，易出 bug）

通过标准：两侧 key 集合完全相同，无重复 key。

可选：验证代码引用 key 均存在：

grep -rohE 'i18nStrings(\[["'"'"'][^"'"'"']+["'"'"']\]|\.\w+)' Main --include='*.js' \
  | grep -vE '/example/|/TemplatePage/|/DebugPage/|Demo' \
  | sed 's/i18nStrings\[//;s/i18nStrings\.//;s/\]//;s/["'"'"']//g' | sort -u
# 逐条对照 zh.js / en.js，不得有 MISSING（忽略范围内文件除外）

2. 硬编码文案扫描

在 Main/views/、Main/components/ 中查找未走 i18n 的 UI 文案。

忽略范围（不扫描、不修复、不报告）：

• Demo 示例：**/example/**、**/Demo*.js
• 模版页面：**/TemplatePage/**
• 调试页面：**/DebugPage/**

应检测（用户可见）：

• JSX 属性：title=、label=、placeholder=、message= 等含中文或英文 UI 词
• <Text> 子节点中的字面量文案
• Alert、Toast、Dialog 等弹窗文案
• defaultProps 中的默认展示文案

应排除：

• console.log / 调试日志
• 注释
• Main/strings/ 内定义
• 资源路径、样式名、变量名、协议字段名
• 上述忽略范围内的文件

扫描命令示例：

grep -rn '[\u4e00-\u9fff]' Main/views Main/components --include='*.js' \
  | grep -vE '/example/|/TemplatePage/|/DebugPage/|Demo'

grep -rnE 'title=\{"|label: "|text: "' Main/views Main/components --include='*.js' \
  | grep -vE '/example/|/TemplatePage/|/DebugPage/|Demo'

修复顺序：

1. 硬编码 → i18nStrings["key"] 或 i18nStrings.alias
2. 无对应 key → 双语同步新增（zh/en 同时添加）
3. 英文 alias（cancel、confirm、loading 等）允许使用；zh 值为中文、en 值为英文

3. 翻译质量审查

严重问题标记：

• 🔴 Critical：缺 key、硬编码 UI 文案、语义错误、大小写违规
• 🟡 Suggestion：术语不一致、英文生硬
• 🟢 Nice to have：更自然的英文表达

4. 新增 / 修复文案

Step A — 双语同步添加（无对应 key 时）：

// zh.js
电机速度: "电机速度",

// en.js
电机速度: "Motor speed",

Step B — 组件引用：

i18nStrings["电机速度"]   // 中文 key
i18nStrings.cancel        // 英文 alias（可选）

英文 alias 双语示例：

// zh.js
cancel: "取消",
confirm: "确认",

// en.js
cancel: "Cancel",
confirm: "Confirm",

函数键成对添加：

// zh.js
xMin: (x) => `${x}分钟`,
// en.js
xMin: (x) => `${x} min`,

Step C — 验证（必须执行）：

node ~/.cursor/skills/translation-check/scripts/check-keys.js Main/strings/zh.js Main/strings/en.js
# 期望：Status: PASS

报告格式

# 翻译校验报告

## 摘要
- 键名：通过 / N 处不一致
- 硬编码：N 处待迁移
- 翻译：N 处建议修改
- 脚本：PASS / FAIL

## 键名问题
| Key | 问题 | 文件 |

## 硬编码文案
| 文件:行 | 原文 | key |

## 翻译建议
| Key | 当前 en | 建议 en | 原因 |

自动修复原则

• 缺 en 条目 → 补英文翻译（勿留空），遵守大小写与术语规范
• 缺 zh 条目 → 补中文（key 与 value 相同）
• 硬编码 → i18nStrings["key"] 或 i18nStrings.alias；无对应 key 则双语同步新增
• 重复 key → 合并为一条，删除重复定义
• 英文 alias（cancel、confirm 等）→ 允许；缺条目时 zh/en 同步补全，勿只改一侧
• 修复完成 → 必须重跑 check-keys.js 至 PASS
• 忽略 example/、TemplatePage/、DebugPage/、Demo*.js，不扫描不修复
• 不修改与本次文案无关的代码

附加资源

• miot-plugin-sdk 插件 i18n 细节见 reference.md