VS Code 源码分析 – 多语言实现

主要包含了 keys 、  messages 、  bundles 三个对象，其中 keys 里是每个源码文件中语言文案的 key 名，messages 则是每个源码文件中语言文案的默认值，bundles 比较奇怪，我们一会再说。这里很明显可以看出 keys 里的键名对应到了 messages 里的文案，我们把它们合并成一个对象

{
    ”vs/code/electron-browser/processExplorer/processExplorerMain“：{
        "cpu": "CPU %",
        "memory": "Memory (MB)",
        //...
    }
}

如果好奇点开上文中 vscode-loc 插件并且看了语言包文件的话会发现这就是[语言包文件 (https://github.com/microsoft/vscode-loc/blob/master/i18n/vscode-language-pack-zh-hans/translations/main.i18n.json#L1486) 的结构。

{
    "vs/code/electron-browser/processExplorer/processExplorerMain": {
        "cpu": "CPU %",
        "memory": "内存 (MB)"// ...
    }
}

到这里似乎有了一点头绪，语言包文件的文案内容对应到了 VS Code 源码的具体文件，根据文件相对路径分为一个一个的 namespace ，在编译时分析了所有包含多语言调用的文件并生成了这个 nls.metadata.json 文件。

bundles 里记录的实际为不同模块的入口，它定义在 gulpfile.vscode.js (https://github.com/microsoft/vscode/blob/master/build/gulpfile.vscode.js#L49) 。在打包时会以这些文件为入口，逐个解析 AST ，根据 import 节点的引用一层一层寻找代码中包含  import * as nls from 'vs/nls' 以及  nls.localize 调用的文件并记录下来。之后根据这些文件再逐个解析 AST 记录所有  nls.localize 调用的 key 值以及默认值 message 分别记录到前文中的 keys 以及 messages 中。

vs/nls

我们再来看一下 vs/nls 模块是什么，源码在这里 (https://github.com/microsoft/vscode/blob/master/src/vs/nls.js) ，这个看起来像编译后代码的实际源码在 vscode-loader (https://github.com/microsoft/vscode-loader/blob/master/src/nls.ts) 项目中。简单看一下代码会发现它是一个 vscode-loader 的插件，vscode-loader 是 VS Code 实现的一个 AMD 规范的异步模块加载器，由于篇幅限制这里不详细叙述它的具体原理。我们只需要了解的是当  import * as nls from 'vs/nls' 时实际加载了一个 nlsPlugin 对象，而  nls.localize 是它的一个属性，粗看它的实现似乎只是负责格式化一下文案及参数原样返回。

上文我们说 VS Code 的多语言对应到源码具体文件，实际上这个说法还不够准确，多语言精确对应到源码中调用 nls.localize 的具体顺序，考虑这段代码

// vs/path/to/code.ts import * as nls from'vs/nls';


const value = nls.localize('key1', 'Message1');
const value2 = nls.localize('key2', 'Message2');


在生成的 nls.matada.json 中应该是

{
    "keys": {
        "vs/path/to/code": [
            "key1",
            "key2"
        ]
    },
    "messages": {
        "vs/path/to/code": [
            "Message1",
            "Message2"
        ]
    }
}

nls.localize 的用法是  nls.localize(key, defaultMesage, [...args]) ，参数中没有任何代码路径的信息，nls 模块如何知道调用的是具体哪个文件的 key 呢？

以前文中的 vs/code/electron-browser/processExplorer/processExplorerMain 为例，再运行  gulp vscode-linux-x64 --old-space-max-size=10240 来看一下源码 完整编译 后变成了什么。

// vs/code/electron-browser/processExplorer/processExplorerMain 编译后 var __m = ["exports","require",/*"..."*/"vs/nls!vs/code/electron-browser/processExplorer/processExplorerMain"];


// ...const tableHead = document.createElement('thead');
tableHead.innerHTML = `

`;


对比[源代码 (https://github.com/microsoft/vscode/blob/master/src/vs/code/electron-browser/processExplorer/processExplorerMain.ts#L245) 会发现两处不一样的地方，首先  __m 记录了代码中所有引用的模块名，其中  vs/nls 后面多了一个  ! 以及当前文件相对路径。其次代码中的  nls.localize(key, message) 变成了  nls_1.localize(index, args) ，没有了 key 也没有 defaultMessage。前文中所说的 多语言精确对应到源码中调用  nls.localize  的具体顺序 ，这里看就很清楚了，这段编译后的代码中 localize 的参数 0、1、2、即表示调用的顺序，那么理论上在 localize 内部执行时应该从类似 nls.metadata.json 中 messages.vs/code/electron-browser/processExplorer/processExplorerMain 数组中获取字符串。

// 伪代码 const languageBundles = <a href="https://zhaoda.net/webpack-handbook/amd.html">

"CPU %",
"内存 (MB)",
"PID",
"名称",
"结束进程",
"强制结束进程",
"复制",
"全部复制",
"调试"
];
function localize(index, args) {
// ...return format(languageBundles[index], args);
}


那么 vs/nls 是如何得到 messages.vs/code/electron-browser/processExplorer/processExplorerMain 的呢？先来快速复习一下 [AMD 模块规范 (https://zhaoda.net/webpack-handbook/amd.html)

再来看看编译后的代码如何定义模块的

// __M 是一个根据给定的参数从 __m 中获取模块列表的函数
define(__m[34/*vs/code/electron-browser/processExplorer/processExplorerMain*/], __M([1/*...*/,36/*vs/nls!vs/code/electron-browser/processExplorer/processExplorerMain*/]), function (require, exports, electron_1, strings_1, os_1, product_1, nls_1, browser, platform, contextmenu_1, dom_1, lifecycle_1, diagnostics_1) {

与我们熟知的 AMD 规范不同的是，这里的依赖列表中 vs.nls 后面多了  !vs/code/electron-browser/processExplorer/processExplorerMain ，我们知道 vscode-loader 是 VS Code 自己实现的一个模块加载器，简单来看一下 define 的调用链

• define

• ModuleManager.defineModule (https://github.com/microsoft/vscode-loader/blob/master/src/core/moduleManager.ts#L502:10) 调用 ModuleManager.defineModule 定义模块

• ModuleManager._normalizeDependency (https://github.com/microsoft/vscode-loader/blob/master/src/core/moduleManager.ts#L536) 标准化依赖

• ModuleManager._normalizeDependencies (https://github.com/microsoft/vscode-loader/blob/master/src/core/moduleManager.ts#L549) 标准化依赖数组

• [DefineFuc (https://github.com/microsoft/vscode-loader/blob/master/src/core/main.ts#L19) 包装前的 Define 方法

let bangIndex = dependency.indexOf('!');

if (bangIndex >= 0) {
    let strPluginId = moduleIdResolver.resolveModule(dependency.substr(0, bangIndex));
    let pluginParam = moduleIdResolver.resolveModule(dependency.substr(bangIndex + 1));
    let dependencyId = this._moduleIdProvider.getModuleId(strPluginId + '!' + pluginParam);
    let pluginId = this._moduleIdProvider.getModuleId(strPluginId);
    returnnew PluginDependency(dependencyId, pluginId, pluginParam);
}

记得前文中说 vs/nls 实际是 vscode-loader 的一个插件吗，这里就是负责处理前文中 vs/nls!path/to/module 的地方，它将 ! 后面的字符作为 nlsPlugin 的参数，这里的 plugin 会作为一个特殊的依赖项(PluginDependency)，当完成标准化模块关系后，defineModule 里会调用 this._resolve 解析模块。我们直接看 _resolve 中对 PluginDependency 的处理 (https://github.com/microsoft/vscode-loader/blob/master/src/core/moduleManager.ts#L896:L913) 。

重点来看 _loadPluginDependency 的实现，第一个参数即是一个 vs/nls 插件实例，并将模块依赖的资源加载行为委托给了插件。

private _loadPluginDependency(plugin: ILoaderPlugin, pluginDependency: PluginDependency): void {
    if (this._modules2[pluginDependency.id] || this._knownModules2[pluginDependency.id]) {
        // known module return;
    }
    this._knownModules2[pluginDependency.id] = true;

    // Delegate the loading of the resource to the pluginlet load: IPluginLoadCallback = ((value: any) => {
        this.defineModule(this._moduleIdProvider.getStrModuleId(pluginDependency.id), [], value, null, null);
    });
    load.error = (err: any) => {
        this._config.onError(this._createLoadError(pluginDependency.id, err));
    };

    // 调用插件 load 方法加载依赖
    plugin.load(pluginDependency.pluginParam, this._createRequire(ModuleIdResolver.ROOT), load, this._config.getOptionsLiteral());
}

而在 vs/nls 插件的 [load 方法 (https://github.com/microsoft/vscode-loader/blob/master/src/nls.ts#L142:L177) 中，首先会判断 name 是否存在，若不存在则加载一个默认的  localize 方法，若存在则读取插件的配置，调用由插件配置传入的 loadBundle (https://github.com/microsoft/vscode/blob/master/src/bootstrap.js#L203:L227) (参数为对应的文件名及语言) 函数获取可用的语言包。插件配置在 VS Code 启动时获取到语言信息完成语言包初始化后传入(开头的 nlsConfigurationPromise)。当语言包加载完成，再调用 _loadPluginDependency 中传入的 load 方法将其定义为一个模块依赖，同时传入一个 scopedLoadlize (https://github.com/microsoft/vscode-loader/blob/master/src/nls.ts#L113:L118) 作为 localize 的实现，这就是运行时真正的 localize 方法。

以上就是 VS Code 中多语言的实现方式，我们会发现整个方案非常依赖一个自定义的模块加载器以及代码编译时的行为，但作为可以独立开发并运行的插件进程不可能为了实现多语言强行用 vscode-loader 作为模块加载方案。那么插件又是如何正确的读取语言包显示对应文案的呢？

NO.3

插件

插件中同样会读取 VSCODE_NLS _ CONFIG 环境变量，不同的是插件中没有 vs/nls 模块，而是由一个 vscode-nls (https://github.com/microsoft/vscode-nls) 替代，这是 VS Code 为插件独立开发的一个多语言模块，这里的实现相对简单一些。首先在插件运行前就会自动执行  initializeSettings (https://github.com/microsoft/vscode-nls/blob/master/src/main.ts#L146) 函数，简而言之这里会读取 VSCODE_NLS _ CONFIG 环境变量并将配置记录下来，在插件中使用 vscode-nls 模块前需要调用 nls.loadMessageBundle 方法，查看 loadMessageBundle 方法会发现它需要一个  file 文件名作为参数，实际上插件代码中并没有传入这个参数。那么很显然插件编译时代码也经过了修改，具体来说编译时会将  nls.loadMessageBundle() 修改为  nls.loadMessageBundle(__filename) ，再同样将  nls.localize(key, message) 修改为  nls.localize(index, args) ，具体的逻辑可以查看 vscode-nls-dev (https://github.com/microsoft/vscode-nls-dev) 模块，这是 VS Code 为插件编译开发的一个模块，编译时也会分析插件 AST 生成 nls.metatdata.json 以及 nls.header.json 文件来记录插件默认的文案以及相关的多语言信息。

NO.4

最后

VS Code 的多语言实现涉及到了依赖分析， AST 操作，模块加载器等许多技术细节，针对这部分工作原理我阅读了两三遍源代码，而且由于其实现的特殊性，如果不完整编译(执行 VS Code 打包编译任务，单纯使用 tsc 编译不会修改 nls 调用行为)并且阅读编译后代码的话可能会一直绕进坑里。希望这篇文章能给希望了解 VS Code 源码细节的同学带来帮助。

推荐阅读