# Translation Check

> Validates Chinese-English translations for miot-plugin-sdk plugin projects — key parity between zh.js/en.js, hardcoded UI strings, translation quality, and bilingual entry completion. Use when adding or reviewing UI copy, strings files, i18n, 翻译校验, 文案, 翻译, or PluginStrings/i18nStrings.

- Skill: `zebr57/translation-check` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add zebr57/translation-check`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zebr57/translation-check/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zebr57 (https://skillmd.com/u/zebr57)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zebr57/translation-check

---


# 翻译校验

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

## 项目约定

| 项 | 约定 |
|---|---|
| 文案目录 | `Main/strings/zh.js`、`Main/strings/en.js` |
| 入口 | `Main/strings/index.js` → 导出 `PluginStrings` |
| 引用方式 | `import i18nStrings from "../../strings"`，使用 `i18nStrings["键名"]` |
| 键名 | 以**中文**为主；允许英文 alias（如 `cancel`、`confirm`），zh/en 两文件 key 完全一致 |
| zh 值 | 中文 key：与 key 相同；英文 alias key：写对应简体中文 |
| en 值 | 对应英文翻译 |
| 函数键 | 如 `xSec: (x) => \`${x}秒\``，zh/en 均需存在且签名一致 |

## 修复规范（必须遵守）

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. 键名一致性

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

```bash
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 均存在：

```bash
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/` 内定义
- 资源路径、样式名、变量名、协议字段名
- 上述**忽略范围**内的文件

**扫描命令示例**：

```bash
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. 翻译质量审查

| 检查项 | 说明 |
|--------|------|
| 语义准确 | 英文含义与中文一致，无漏译/错译 |
| 产品语气 | 简洁，符合窗帘/智能家居 UI 习惯 |
| 术语统一 | 与现有 `en.js` 专有名词一致（Settings、Mesh Gateway、Countdown 等） |
| 英文大小写 | 仅首词首字母大写，如 `Saved successfully`、`Socket switch`、`No gateway` |
| UI 长度 | 英文不过长导致布局溢出；按钮/标签宜简短 |
| 标点 | 省略号统一 `...`；中英文各自规范 |
| 占位符 | 函数键中 `${x}` 等占位符两侧语言结构对应 |
| 陈旧文案 | 复制粘贴错误（如其他品类设备描述） |

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

### 4. 新增 / 修复文案

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

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

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

**Step B — 组件引用**：

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

英文 alias 双语示例：

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

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

函数键成对添加：

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

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

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

## 报告格式

```markdown
# 翻译校验报告

## 摘要
- 键名：通过 / 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](reference.md)