fix-nls-gaps
排查并修复「用户可见文本没走 localize / 中文硬编码漏本地化 / 中文 defaultMessage 泄漏到英文界面」。当用户说某文案没本地化、找未本地化的文本、本地化查漏补缺、英文界面冒出中文(或中文界面冒出英文)时使用。覆盖三种遗漏形态的扫描、修复写法约定、zh-CN.ts 补译与验证链。
SKILL.md.claude/skills/fix-nls-gaps/SKILL.md
GitHub修复本地化遗漏(裸文本 / 中文 defaultMessage / zh-CN 缺 key)
本仓库走 localize(key, defaultMessage, vars?)(packages/platform/src/nls/nls.ts),中文集中在 apps/editor/src/shared/i18n/messages/zh-CN.ts;en-US.ts 只是不完整的历史子集,英文由 defaultMessage 兜底。
核心机制:兜底链决定一切
translated = state.messages[key] ?? state.fallbackMessages[key] // zh-CN.ts ?? en-US.ts
template = translated ?? defaultMessage
由此推出三条铁律:
- defaultMessage 必须写英文。zh-CN 缺 key 时会落到 en-US.ts(多半也没有)→ 落到 defaultMessage——default 写中文 = 中文泄漏到英文界面。反之英文 default 是安全兜底。
- e2e 断言的是 defaultMessage 原文。两套 e2e fixture 都 pin
workbench.language=en-US,zh-CN.ts 在 e2e 里不生效。改了 defaultMessage / 把裸中文改成 localize,必须同步 grep e2e spec 里的旧文案断言。 - 「已 localize 但 zh-CN.ts 缺 key」是隐性遗漏:zh-CN 用户此时看到 defaultMessage(英文)。发现中文界面出英文,先查 key 是否在 zh-CN.ts。
三种遗漏形态与修法
| 形态 | 识别 | 修法 |
|---|---|---|
| ① 裸文本(没走 localize) | grep 出中文/英文字面量直接渲染或抛错 | 就地 localize('域.key', 'English default', { vars }),中文入 zh-CN.ts |
| ② 中文 defaultMessage | localize('...', '中文') |
default 换英文,中文入 zh-CN.ts(同 key) |
| ③ zh-CN.ts 缺 key | 代码已有 localize 但 zh-CN 界面显示英文 | 只补 zh-CN.ts,default 不动 |
第 1 步:扫描
# 裸中文(形态①):排除注释/测试/消息表/localize 行
grep -rn -P '[\x{4e00}-\x{9fff}]' apps/editor/src packages/workbench-ui/src packages/platform/src \
--include='*.ts' --include='*.tsx' \
| grep -v '\.test\.' | grep -v '__tests__' | grep -vP '//|/\*|\* |messages/(zh-CN|en-US)' \
| grep -vP "localize2?\("
# 中文 defaultMessage(形态②,同行)
grep -rn -P "localize2?\('[^']+', '[^']*[\x{4e00}-\x{9fff}]" \
apps/editor/src packages/workbench-ui/src packages/platform/src --include='*.ts' --include='*.tsx' \
| grep -v '\.test\.'
# 形态②跨行变体(key 与 default 分行):-A2 后滤中文
grep -rn -P "localize2?\(" apps/editor/src packages/workbench-ui/src packages/platform/src \
--include='*.ts' --include='*.tsx' -A2 | grep -P "'[^']*[\x{4e00}-\x{9fff}]" | grep -v '\.test\.'
# 形态③:某 key 是否已在 zh-CN.ts
grep -n "'<key>'" apps/editor/src/shared/i18n/messages/zh-CN.ts
第 2 步:排除项(这些刻意保留中文/不 localize)
- 发给 agent/模型的文本:协议恢复语(如
CONTINUE_PROMPT_TEXT = '继续')、few-shot prompt 示例。 - 中文搜索关键词表(如 contextSuggestions 的中文别名、COMMIT_MATCH_KEYWORDS)——是匹配数据不是 UI 文案。
- placeholder 值示例(
sk-…、gpt-5.1-codex、**/*.ts)、协议标识符、语言专名、Output channel 名。 - 日志 / console / logger 文本、开发者向面板(Startup Performance 里程碑)。
- 注释(含 JSX
{/* */},注意跨行注释会被 grep 误报)。 - 测试 fixture 自造串(测试里 new Error('中文') 模拟错误、自造 markdown)——除非断言的就是生产文案。
- e2e spec 里的中文多为测试数据(文档内容、文件名),不受影响;只有断言 UI 文案的才要改。
边界判定拿不准的:issue 报告模板这类「贴到外部(GitHub)的文本」用英文(国际化惯例);CLI --help 输出统一英文(ConfigItem.description 只被 cliHelp 消费)。
第 3 步:修复写法约定
- key 命名:Action2 title →
action.<domain>.<camelName>(用localize2,命令面板匹配用 original);其余按<domain>.<thing>[.desc],沿用既有分节前缀(search.*/dialog.*/common.*…)。 - 变量插值:模板字符串拼接改
{var}具名占位 + 对象参——语序随语言变,绝不拼接。'文件不存在: ' + path→localize('markdown.linkFileNotFound', 'File does not exist: {path}', { path })。 - 复用已有 key:'取消' →
common.cancel等,先 grep zh-CN.ts 查重。 - 同文案多处共用 key:如三个编辑器的加载态共用
editor.loading;两个预览 input 共用editor.previewTitle。 - 模块求值时序:renderer 模块级 localize 安全;main 侧顶层常量不行(NLS 装配晚于模块求值)——顶层表改函数内解析(先例:
VENDOR_DESCRIPTORS用 labelKey + 函数内 resolve;MarkdownPreviewHelp的 SHORTCUTS 常量改shortcuts()函数)。 - Monaco 命令 label:先查
__MONACO_NLS__表(按英文源文本为键)是否覆盖,未覆盖的走 labelKey + localize。
第 4 步:zh-CN.ts 补译
- 按现有
// --- <域> ---分节插入,新域新建分节;统一在最后一轮一次写入,避免多轮往返。 - 翻译与 defaultMessage 语义对齐;变量名保持一致(
{count}/{name}…)。
第 5 步:验证链(顺序执行,每步过了再下一步)
pnpm exec prettier --write <改动的文件…> # PostToolUse hook 可能留行宽 lint 错误
pnpm --filter @universe-editor/platform build # 仅当改了 platform(apps 看 dist/)
pnpm check # lint + typecheck + 相关测试
pnpm --filter @universe-editor/editor test:unit # 全量单测——断言漂移在这暴露
pnpm --filter @universe-editor/editor build # e2e 跑 out/ 产物
pnpm e2e:smoke # @p0 冒烟
断言漂移处理(必然遇到,分两类):
- 单测断言旧文案:测试环境 localize 返回 defaultMessage,断言写英文 default 原文(不再写中文)。逐文件 grep 旧文案改断言。
- e2e 断言旧文案:e2e pin en-US → 断言的同样是 defaultMessage 原文。改完全局扫一遍:
逐个判定是 UI 文案断言(要改)还是测试数据(保留)。grep -rn -P '[\x{4e00}-\x{9fff}]' apps/editor/e2e/specs/ | grep -vE '//|/\*|\* ' | grep -vP 'describe\(|test\('
收尾全量复扫:三种形态各跑一遍第 1 步的命令,确认清零(排除项除外)。
易踩坑速记
- 单行 grep 漏跨行 localize:key 与 defaultMessage 分行的调用要
-A2扫,别只看单行。 - 改了 platform 要 rebuild:apps 看
dist/,否则 typecheck/单测拿旧产物。 - PostToolUse prettier hook 会重排 JSX:可能制造行宽 lint 错误,验证前先手动
prettier --write。 - cliHelp 的 description 别 localize:
--help在 NLS 装配前就可能输出,且 CLI 惯例英文;ConfigItem.description仅 cliHelp 消费。 - 别动 en-US.ts:它只是兜底子集,新增 key 不需要补(defaultMessage 即英文)。
- 单测里断言 localize 结果 = 断言 defaultMessage;若想验证 zh-CN 翻译,没有现成机制——不要为翻译写测试,只保证 key 存在于 zh-CN.ts。
关键参考路径
packages/platform/src/nls/nls.ts—— localize/localize2 与兜底链实现apps/editor/src/shared/i18n/messages/zh-CN.ts—— 中文消息表(分节结构)apps/editor/src/shared/i18n/availableLocales.ts—— locale 装配(configureEditorNls)apps/editor/src/renderer/workbench/editor/monaco/monacoActionsBridge.ts—— Monaco 命令 label 的 NLS 查表兜底packages/platform/src/configuration/sources/cliHelp.ts——--help文本生成(英文惯例的例外域)docs/development/monaco-embedding.md「0.55 升级踩坑」 —— monaco 内置 UI(查找框/右键/peek)的中文不走本表:0.55 起其 NLS 是索引制(prebuiltlocalize(786,"EN")查_VSCODE_NLS_MESSAGES[index]),走「英文桥接」patchlookupMessage——apps/editor/src/renderer/workbench/editor/monaco/monacoNlsPatch.ts+ 构建脚本apps/editor/scripts/build-monaco-nls.mjs,产物apps/editor/src/renderer/vendor/monaco-nls/zh-cn.messages.json
其它
- 后续用本 skill,发现新经验,需同步更新本文件