用途:编辑 Salesforce DX VS Code 扩展的国际化消息文件及其消费代码,范围限于 packages/*/src/messages/i18n.ts 与使用 nls.localize 的代码,不涉及 package.json/package.nls.json 中的 nls 字符串(如命令标题)。
占位符语义:nls.localize(key, ...args) 通过 node:util.format 替换(见 packages/salesforcedx-vscode-i18n/src/i18n/message.ts:50)。%s 为字符串,%d 为数字原样输出(3.7→3.7),%i 截断浮点(3.7→3),%f 为浮点,%j 为 JSON,%o/%O 为对象检查输出,%c 为 CSS 指令无输出,%% 仅在存在参数时输出 %(message.ts:37 有 args.length > 0 守卫,裸字符串跳过 format 并保留 %%),%n 不受支持,会原样渲染。默认计数用 %d,字符串用 %s。
参数计数陷阱:message.ts:39 用 /%[sdifj%]/g 统计占位符(%% 除外,L40),不匹配时记录日志并裁剪多余参数(L41-48),缺失参数不会补齐,末尾未匹配标记会原样渲染。%o、%O、%c 运行时替换但不在此正则内,会绕过参数计数校验,应避免依赖,优先用 %s/%d/%j。%n 既不计入也不是真实标记,会导致预期计数偏差并原样打印。
复用优先:新增前先在 package.nls.json 中 grep 是否已有等价字符串,复用而非重复。
各界面风格:命令标题(package.nls.json _text)用 Title Case 并带 SFDX: 前缀,无标点;QuickPick/InputBox 占位符用句子式,无标点;确认提示用句子式,以 ./? 结尾;通知(showMessage)用句子式,以 . 结尾;按钮/操作标签用 Title Case,无标点;树/状态栏标签与提示用 Title Case,无标点;日志/通道行、校验错误用句子式,以 . 结尾。
不要加严重级别前缀:新字符串不要以 Error:/Warning: 开头,show*Message API 会提供严重级别;i18n.ts:92 的 Warning: 是遗留反模式,不要复制也不要修改(超出范围)。
交叉引用:vscode-window-messages 覆盖通知/按钮 API(哪个 show*Message、返回值、Effect、模态),本技能只负责消息文本,不要在此重复 API 指导。