VSCode插件开发与中文显示适配指南-VSCode-PHP中文网

插件界面仍是英文，关键在于package.json的contributes.configuration未配置locale——插件需在properties中为title和description显式声明zh-cn键值对，仅靠package.nls.json无法覆盖配置项文案。

vscode插件开发与中文显示适配指南

为什么插件界面仍是英文？关键在 `package.json` 的 `contributes.configuration` 里没配 `locale`

插件作者常误以为装了中文语言包，插件 UI 就自动汉化——其实 VS Code 不会主动翻译插件自己的配置项、设置描述、命令提示等。这些内容必须由插件显式声明多语言支持。

常见错误现象：插件已安装，settings.json 里能看到配置项名（如 "myPlugin.enable": true），但设置面板中显示的标题、说明文字仍是英文。

必须在插件根目录的 package.json 中，于 contributes.configuration 下每个 properties 字段内，为 title 和 description 单独提供 zh-cn 键值对，例如：

{
  "myPlugin.enable": {
    "type": "boolean",
    "default": true,
    "title": {
      "zh-cn": "启用插件功能",
      "en": "Enable plugin functionality"
    },
    "description": {
      "zh-cn": "开启后将自动注入代码片段",
      "en": "Automatically injects code snippets when enabled"
    }
  }
}

仅靠 package.nls.json 或 package.nls.zh-cn.json 文件无法覆盖配置项文案；VS Code 读取配置描述时只认 package.json 内联结构
若使用 vscode-nls 库做运行时翻译，它只适用于插件代码中调用 vscode.l10n.t() 的字符串，不作用于 contributes 静态定义

`vscode.l10n.t()` 在插件 UI 中怎么用才不出乱码？

调用 vscode.l10n.t() 是动态文本本地化的标准方式，但容易因编码或路径问题导致中文显示为方块或问号。

使用场景：命令提示、状态栏消息、QuickPick 选项、Webview 中的提示文案等需运行时决定的文字。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

确保插件项目根目录下存在 package.nls.json（主语言映射）和 package.nls.zh-cn.json（简体中文翻译），且两个文件都保存为 UTF-8 无 BOM 编码
package.nls.zh-cn.json 中的 key 必须与 package.nls.json 完全一致，value 为对应中文翻译，例如：
```
{"helloWorld": "你好世界"}
```
在 TypeScript 代码中调用时，必须传入 key 字符串字面量（不能拼接、不能变量），否则编译期无法提取：vscode.l10n.t("helloWorld") ✅，vscode.l10n.t(key) ❌
如果 Webview 中使用 vscode.postMessage 传递带中文的文案，务必确认接收端未做二次 URL decode 或字符截断

插件发布后用户看到的是英文？检查 `package.json` 的 `engines.vscode` 和语言包兼容性

VS Code 自 1.85 版起强制要求插件声明最低兼容版本，且 l10n 支持依赖编辑器底层能力。老版本用户即使装了中文语言包，也可能无法加载插件的 nls 文件。

参数差异直接影响是否触发翻译逻辑：

"engines": {"vscode": "^1.85.0"} 是当前安全下限；低于此版本，vscode.l10n.t() 调用会静默回退到英文 key，不报错也不提示
插件打包时若用 vsce package，默认不包含 .nls.*.json 文件——必须在 vsce 命令后加 --no-dependencies 并确认 package.nls.*.json 已列入 files 字段
用户端若使用企业版 VS Code（如启用了 extensions.autoCheckUpdates 关闭策略），可能跳过语言包更新，导致 zh-cn 翻译资源未同步拉取

调试插件中文显示问题时，别忽略 `Developer: Toggle Developer Tools` 里的 console 报错

很多插件作者卡在“明明写了中文，却没生效”，实际是底层加载失败但没暴露错误。

性能 / 兼容性影响：nls 文件加载失败不会阻塞插件启动，但会降级为英文 fallback，用户无感知，开发者也难定位。

打开开发者工具（Ctrl+Shift+P → Developer: Toggle Developer Tools），切换到 Console 标签页，筛选关键词 nls 或 locale
典型错误：Failed to load nls file for zh-cn: Error: Cannot find module './package.nls.zh-cn.json' —— 表明打包遗漏或路径写错
另一个线索：在 Sources 面板中展开 webpack://，搜索 package.nls，看是否真有对应语言文件被注入
临时验证法：在插件激活函数中加一行 console.log(vscode.env.language)，确认当前编辑器 locale 确实是 zh-cn（不是 zh 或 zh-CN）

插件汉化不是“写完中文再打包”就完事，而是从 package.json 结构、nls 文件编码、引擎版本约束到用户端 locale 状态，每层都可能断裂。最常被忽略的是：插件开发时本地 locale 是 zh-cn，但 CI 构建环境默认 en-us，导致 nls 提取脚本失效，最终发布包里缺中文映射。