VS Code 扩展本地化l10n实战指南以 l10n-sample 为例掌握vscode.l10n全流程【免费下载链接】vscode-extension-samplesSample code illustrating the VS Code extension API.项目地址: https://gitcode.com/gh_mirrors/vs/vscode-extension-samples本指南基于 vscode-extension-samples 仓库中的 l10n-sample 示例系统讲解 VS Code 扩展国际化的完整技术栈从静态清单package.nls.json的翻译、源码内字符串标记vscode.l10n.t到本地化字符串的提取工具vscode/l10n-dev再到子进程中加载翻译vscode/l10n。读完本文你将能够为自己的扩展接入中、日等多语言支持并能用伪本地化Pseudolocalization在不出海翻译团队的情况下自测本地化效果。该示例实现了一个简单的扩展注册Hello与Bye两条命令在英文与日文两种 locale 下展示对应翻译并演示了如何把本地化能力传递到扩展派生的子进程Node CLI中。本地化的四大核心组成部分VS Code 扩展源码级本地化由四个相互配合的部分组成示例中全部有对应实现组件作用示例中的位置package.nls.json翻译扩展package.json中的静态贡献命令标题、菜单名等l10n-sample/package.nls.json、l10n-sample/package.nls.ja.jsonvscode.l10n.t官方 API标记代码中需要翻译的字符串l10n-sample/src/extension.ts、l10n-sample/src/command/sayBye.tsvscode/l10n-dev命令行工具从扩展中提取 l10n 字符串、处理 XLF 文件以npx方式调用见下文vscode/l10n运行时库在扩展的子进程中加载翻译l10n-sample/src/cli.ts其中vscode/l10n-dev与vscode/l10n分别声明在 l10n-sample/package.json 的devDependencies^0.0.18与dependencies^0.0.10中。第一步用package.nls.json翻译静态清单扩展的package.json中所有面向用户展示的静态贡献命令标题、配置项名称、菜单文案等都无法通过源码 API 翻译必须借助package.nls.json这一约定文件。工作原理package.nls.json中的键与package.json中的键一一对应值为对应键的翻译。以示例为例打开 l10n-sample/package.json 可以看到命令标题被%包裹{ contributes: { commands: [ { command: extension.sayHello, title: %extension.sayHello.title% }, { command: extension.sayBye, title: %extension.sayBye.title% } ] } }对应的 l10n-sample/package.nls.json默认语言即英文为{ extension.sayHello.title: Hello, extension.sayBye.title: Bye }而日文翻译 l10n-sample/package.nls.ja.json 为{ extension.sayHello.title: こんにちは, extension.sayBye.title: さようなら }语言文件命名规则package.nls.json默认语言通常是英文不含语言代码后缀。package.nls.LANG.json特定语言的翻译例如package.nls.ja.json对应日文ja为 BCP-47 语言代码。当 VS Code 界面语言为对应 locale 时会自动加载对应语言的package.nls.*.json覆盖默认值找不到对应语言文件时回退到package.nls.json。第二步用vscode.l10n.t翻译源码字符串l10n是官方 VS Code API 中新增的命名空间参见官方 vscode-api 文档中l10n部分用于在扩展代码中标记需要翻译的字符串取代了旧方案中的vscode-nls与vscode-nls-dev包。三种函数签名vscode.l10n.t()支持三种调用形式// 形式一位置参数 function t(message: string, ...args: Arraystring | number): string; // 形式二命名参数 function t(message: string, args: Recordstring, any): string; // 形式三带翻译注释推荐用于有占位符的字符串 function t(options: { message: string; args?: Arraystring | number | Recordstring, any; comment: string | string[] }): string;参数占位符机制位置参数字符串中的{0}、{1}等占位符会按索引被替换为对应实参。例如Hello {0}配合参数CLI会得到Hello CLI。命名参数字符串中的{name}占位符会从args对象中读取name属性填充。例如Hello {done}配合{ done: FINISHED }会得到Hello FINISHED。在 l10n-sample/src/extension.ts 中两种形式都有体现// 最简单的无参数形式 const message vscode.l10n.t(Hello); // 命名参数形式 const messageDone vscode.l10n.t(Hello {done}, { done: FINISHED });翻译注释comment当字符串包含占位符时译者往往不知道{0}代表什么。第三个签名中的comment字段正是用来给译者提供上下文说明的。在 l10n-sample/src/command/sayBye.ts 中可以看到完整示范import { l10n, window } from vscode; export function sayByeCommand() { const message l10n.t(Bye); window.showInformationMessage(message); const message2 l10n.t({ message: Bye {0}, args: [Joey], comment: [{0} is a person\s name] }); window.showInformationMessage(message2); }这里comment数组说明{0}是人名译者便能据此给出符合语境的翻译。翻译文件的加载规则被vscode.l10n.t()标记的字符串会在运行时从bundle.l10n.LANG.json文件中查找对应翻译键为原始英文字符串值为翻译。本仓库提供了一份日文翻译 l10n-sample/l10n/bundle.l10n.ja.json{ Bye: さようなら, Hello: こんにちは, Hello {0}: こんにちは {0}, Hello {done}: こんにちは {done} }注意键必须与源码中的t()调用字符串完全一致包括占位符写法翻译时占位符{0}、{done}需原样保留在目标语言字符串中供运行时替换。扩展清单中的l10n属性必须配置要让上述机制生效必须在扩展清单中声明l10n属性告诉 VS Code 到哪里寻找本地化字符串文件。示例中 l10n-sample/package.json 配置如下{ // example main: ./out/extension.js, // ... l10n: ./l10n }要点l10n的值必须是相对于扩展根目录的相对路径指向存放bundle.l10n.LANG.json文件的目录。运行时 VS Code 会依据该属性加载与当前 locale 匹配的翻译文件因此必须确保把翻译文件放在该目录下的正确位置。路径可以自定义但必须遵守相对扩展根目录这一约束。第三步用vscode/l10n-dev提取与生成翻译文件vscode/l10n-dev是用于从扩展中提取本地化字符串、并处理 XLF 文件的命令行工具。示例中它作为 devDependency 引入实际使用时通常通过npx直接运行。导出bundle.l10n.json从源码目录提取所有可本地化字符串生成bundle.l10n.jsonnpx vscode/l10n-dev export -o ./l10n ./src-o ./l10n指定输出目录。./src指定扫描的源码目录。该命令会生成l10n/bundle.l10n.json其中包含扩展中所有可本地化的字符串自动扫描vscode.l10n.t()调用。之后即可为每种目标语言创建bundle.l10n.LANG.json并填写键值对。伪本地化Pseudolocalization自测如果不懂其他语言又想验证本地化链路是否正常工作可以使用vscode/l10n-dev内置的伪本地化生成器把字符串翻译成加了装饰性标记的伪文本npx vscode/l10n-dev generate-pseudo -o ./l10n/ ./l10n/bundle.l10n.json ./package.nls.json该命令会生成package.nls.qps-ploc.json与bundle.l10n.qps-ploc.json两个文件。随后在 VS Code 中安装 Pseudo Language 语言包qps-ploc是 VS Code 约定的伪本地化语言代码并将 VS Code 界面语言切换为该 locale扩展的字符串便会从对应的qps-ploc文件中读取。通过观察字符串是否被明显改写可以快速确认哪些文案漏掉了翻译标记。进阶生成 XLF 文件对接翻译团队XLFXML Localisation Interchange File Format是常见的翻译交付格式。官方团队通常将bundle.l10n.json与package.nls.json转换为 XLF 文件交给翻译团队npx vscode/l10n-dev generate-xlf -o ./l10n-sample.xlf ./l10n/bundle.l10n.json ./package.nls.json-o ./l10n-sample.xlf输出的 XLF 文件路径。后两个参数为输入bundle.l10n.json源码字符串与package.nls.json静态清单字符串。l10n-dev工具同样支持将翻译完成的 XLF 文件反向转换回bundle.l10n.json与package.nls.json从而把翻译结果落盘到仓库中示例未涉及该反向流程此处不做展开。第四步用vscode/l10n在子进程中加载翻译扩展主进程中的vscode.l10n.t()由 VS Code 宿主负责加载翻译但扩展可能通过child_process或任务派生 Node 子进程如语言服务器、CLI 工具这些子进程无法直接访问vscodeAPI需要借助vscode/l10n库在子进程内自行配置并加载翻译。扩展侧把翻译文件路径传给子进程在 l10n-sample/src/extension.ts 中扩展通过vscode.tasks.executeTask启动一个 shell 任务执行cli.js并把vscode.l10n.uri的文件路径通过环境变量传给子进程await vscode.tasks.executeTask( new vscode.Task( { type: shell }, vscode.TaskScope.Global, message, message, new vscode.ShellExecution(node ${path.join(__dirname, cli.js)}, { env: vscode.l10n.uri ? { EXTENSION_BUNDLE_PATH: vscode.l10n.uri?.fsPath } : undefined })));这里vscode.l10n.uri指向当前 locale 对应的bundle.l10n.LANG.json文件 URI通过EXTENSION_BUNDLE_PATH环境变量注入子进程。子进程侧l10n.config()指定翻译文件在 l10n-sample/src/cli.ts 中子进程读取环境变量并调用vscode/l10n的config()完成初始化import * as l10n from vscode/l10n; if (process.env[EXTENSION_BUNDLE_PATH]) { l10n.config({ fsPath: process.env[EXTENSION_BUNDLE_PATH] }); } const message l10n.t(Hello {0}, CLI); console.log(message \n);要点l10n.config({ fsPath })用于指定翻译 bundle 文件的本地路径该库还支持通过uri传入远程 URI。配置完成后l10n.t()的调用行为与扩展主进程中的vscode.l10n.t()一致有对应语言的翻译则返回翻译文本否则回退到源字符串。这类l10n.t()调用同样会被vscode/l10n-dev的提取工具识别从而保证子进程中的字符串也不会漏出本地化流程之外。端到端工作流总结在package.json中声明l10n: ./l10n并让所有静态贡献的标题使用%key%引用。用package.nls.json 各语言的package.nls.LANG.json提供静态文案翻译。源码中用vscode.l10n.t()标记动态字符串占位符优先使用命名参数并辅以comment说明。运行npx vscode/l10n-dev export -o ./l10n ./src提取字符串生成bundle.l10n.json。为每种语言创建bundle.l10n.LANG.json填写翻译不想翻译时可先用generate-pseudo生成伪本地化文件自测。若扩展派生子进程通过环境变量把vscode.l10n.uri传下去子进程用vscode/l10n的config()加载翻译。对接翻译团队时用generate-xlf生成 XLF 交付翻译完成后反向转换回仓库文件。如需运行本示例可在 l10n-sample 目录执行npm install与npm run compile对应package.json中的vscode:prepublish/compile脚本再按 VS Code 扩展调试F5方式启动扩展开发宿主切换界面语言为日文即可看到两条命令的标题与弹窗文案随 locale 变化。【免费下载链接】vscode-extension-samplesSample code illustrating the VS Code extension API.项目地址: https://gitcode.com/gh_mirrors/vs/vscode-extension-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考