🌐 新增翻译完整性机械检查 (check:i18n)

[cyfung1031]

Checklist / 检查清单

• Fixes mentioned issues / 修复已提及的问题
• Code reviewed by human / 代码通过人工检查
• Changes tested / 已完成测试

背景

#1587（pt-BR 翻译）合并后，评审中发现该 PR 遗漏了 messages.json（chrome.i18n 商店信息）与 Monaco 编辑器语言（editorLangs），当时没有机制能自动拦截这类遗漏（"we don't have a solid mechanism to prevent this"）。本 PR 为此补上一个机械检查脚本，并在本地提交与 CI 两处强制执行。

本次改动

新增 scripts/check-i18n.mjs，并通过新增的 pnpm run check:i18n 接入 pnpm lint / pnpm lint:ci。针对 src/locales/ 下的每个 locale，以 en-US 为基准做以下校验：

1. src/locales/<locale>/*.json：每个命名空间文件的 key 是否与 en-US 一一对应，缺失或多余都会报错。
2. src/locales/<locale>/index.ts：是否导出了 en-US 拥有的全部命名空间。
3. src/assets/_locales/<chrome-locale>/messages.json：与 en/messages.json 的 key 是否一致（即 Brazilian Portuguese/pt-BR Translation #1587 遗漏的部分）。chrome 目录名通过实际扫描 _locales/ 目录解析（如 ko-KR → ko、zh-CN → zh_CN），而非写死的映射表，避免映射表本身过期失效。
4. docs/references/terminology-<locale>.md：每个 locale 必须有对应术语规范文件，缺失即报错。
5. src/pkg/utils/monaco-editor/langs.ts（或未来拆分后的 langs/<locale>.ts + langs/index.ts）：editorLangs（悬浮提示、脚本头字段提示，即 Brazilian Portuguese/pt-BR Translation #1587 遗漏的另一部分）用 TypeScript 编译器 API 解析。它是手写的 const 对象而非 JSON，部分属性引用了同文件内其他顶层常量（如 grantValuePrompts: grantValuePromptsEnUS）或跨文件 import 绑定（拆分后每个 locale 一个文件，index.ts 里 "pt-BR": ptBR 指向 ./pt-BR.ts 的 export default），解析时都会展开后再与 en-US 比对 key。

同时：

• 在 docs/translation.md 新增"机械检查：遗漏翻译"一节并更新翻译检查清单。
• 在 .husky/pre-commit 中新增一段：只要暂存区包含 src/locales/**/*.json 或 src/assets/_locales/**/*.json，本地提交前就会先跑一遍 pnpm run check:i18n，不通过直接拒绝提交——不用等推送后才在 CI 里看到红叉。范围刻意收窄为 json 文件本身（不含 terminology-*.md、langs.ts/langs/），这样改动检查脚本本身或调整 terminology/langs 这类周边文件时不会被连带拦下；这些周边文件的完整性仍由 CI 侧的 lint:ci（覆盖全部 5 类检查）兜底。

已知限制

• 对于第 3、5 项，如果某个 locale 尚未创建对应目录/条目（当前如 pt-BR 的 _locales 目录、pt-BR/tr-TR 的 editorLangs 条目），本次检查仅给出提示（warning），不会导致失败——这两处目前是可选/尽力而为的内容（参见 docs/translation.md），与项目现状一致。但只要该 locale 已经创建了对应条目，其 key 就必须与 en-US 保持一致，否则报错。这个折衷是为了不让本 PR 自身因为与本次改动无关的历史遗留缺口（tr-TR/pt-BR 的 editorLangs）而在合并后立即变红。
• 该脚本无法判断翻译措辞是否准确、是否符合术语规范——那部分仍需人工审阅并遵循 docs/translation.md 与对应的 terminology-<locale>.md。
• 本 PR 无法做到"检查不通过就不允许合并"：pnpm run check:i18n 已经接入 pnpm lint:ci（.github/workflows/test.yml 的 Lint job），失败时 PR 上会有红叉，本地 pre-commit 也会提前拦截；但真正能拦住合并按钮的，是仓库管理员在 main 分支的 branch protection 里把 Lint 设为 required status check——这一步需要 scriptscat/scriptcat 的仓库管理员在 GitHub 仓库设置里配置，贡献者/本 PR 都无法代为完成，只能建议。

建议审查重点

• src/pkg/utils/monaco-editor/langs.ts 的 TypeScript AST 解析逻辑（parseModule/flattenNode）：是否正确处理了对象嵌套、同文件顶层常量引用、跨文件 import 绑定与 shorthand 属性（grantValuePrompts,）。
• src/assets/_locales 目录名解析逻辑（findChromeDirName）：是否能正确覆盖未来新增的 locale，而不需要手动维护映射表。
• 第 3、5 项"缺失整个目录/条目仅警告，但已存在则必须对齐"的严格程度是否符合预期。
• .husky/pre-commit 只在 json 文件改动时触发是否合适：好处是不会拦住本 PR 自身、或调整 terminology/langs 文件时的提交；代价是本地提交阶段不会拦截"新增 locale 但漏配 terminology 文件/langs 条目"这类问题，这类问题仍要等 CI 才会报出来。

验证

• pnpm run check:i18n：在当前 main 上通过，仅有两条提示性 warning（pt-BR 尚无 _locales 目录、pt-BR/tr-TR 尚无 editorLangs 条目），均为历史遗留、非阻塞。
• pnpm run lint:ci：全部通过（prettier、tsc、check:i18n、eslint）。
• 用 scriptscat/scriptcat 官方仓库的三个真实 PR 做了验证：
  • Brazilian Portuguese/pt-BR Translation #1587（pt-BR）：通过，警告同上。
  • i18n: add Korean (ko-KR) translation #1568（ko-KR）：零问题通过，独立印证了该 PR 自述的"11 个命名空间文件 0 缺失 0 多余"、_locales/ko/messages.json 与 editorLangs["ko-KR"] 均完整。
  • 🌐 Cover chrome.i18n messages.json and Monaco editor langs for pt-BR / tr-TR #1605（pt-BR/tr-TR 补全 + langs.ts 拆分为 langs/<locale>.ts）：零问题通过，已在 #1605 的评论里贴出结果；期间发现脚本最初硬编码单文件路径、对拆分后的目录结构会误报"文件缺失"，已在本 PR 中修复（自动探测 langs/index.ts，支持跨文件 import 解析）。
• 反向验证（人为在 JSON 命名空间、拆分前后的 langs.ts/langs/<locale>.ts 中删除/新增 key，删除 messages.json、删除 terminology-<locale>.md）均能正确以 exit code 1 报出具体缺失/多余的 key 路径，还原后重新通过；pre-commit 钩子在暂存区包含 json 翻译文件的坏改动时也会正确拒绝提交，同时确认了它不会拦截本 PR 自身对 .husky/pre-commit、scripts/check-i18n.mjs 等非 json 文件的提交。

关联

• 参见 Brazilian Portuguese/pt-BR Translation #1587 中的评审讨论。
• 参见 🌐 Cover chrome.i18n messages.json and Monaco editor langs for pt-BR / tr-TR #1605（该 PR 的实际内容被用作本次机械检查的验证对象之一）。

[cyfung1031]

manually tested