企业官网建设流程全解析

• 数据库客户端
• 桌面应用
• 数据分析

Azure Data Studio 作为面向 Windows、macOS、Linux 的跨平台数据管理与开发工具，其简体中文界面由ads-language-pack-zh-hans语言包扩展提供。本文以该语言包的 CHANGELOG.md 为骨架，结合仓库源码深入剖析语言包的组成结构、工作机理、安装使用方法，以及从 1.29 到 1.49 的版本演进脉络，帮助读者掌握 Azure Data Studio 多语言体系的完整视图。

一、语言包是什么：从 CHANGELOG 看它的定位

ads-language-pack-zh-hans 的 CHANGELOG.md 记录了一条简单却极具信息量的发布线：该语言包以 Azure Data Studio 的主版本为对齐基准，几乎每个主版本都会同步更新一次本地化字符串，个别版本还会发布修正补丁：

这一表格揭示了语言包的两大特性：

1. 版本强绑定：语言包的版本号与 Azure Data Studio 主版本一一对应。查看 package.json 可见其"version": "1.49.0"与"engines"中声明的"azdata": "^1.49.0"恰好匹配，这正是语言包“随产品主版本迭代”的机制保障。
2. 发布节奏稳定：从 1.35 起基本保持每 6～8 周随产品主版本发布一次的节奏，且偶发 Patch 用于修正紧急问题（如 1.40 Patch），说明本地化团队与产品研发周期深度耦合。

需要说明的是，CHANGELOG 的条目顺序并非严格按时间倒序（1.29 的条目排在 1.33 之后），但这不影响其作为版本演进证据的有效性。以仓库当前内容为准，该语言包最新版本对应 Azure Data Studio 1.49。

二、语言包目录结构与内部组成

简体中文语言包在仓库中的路径为i18n/ads-language-pack-zh-hans/，其内部结构如下：

i18n/ads-language-pack-zh-hans/ ├── CHANGELOG.md # 版本发布记录 ├── README.md # 中英双语使用说明与致谢 ├── package.json # 扩展清单（localizations 贡献点） ├── languagepack.png # 语言包图标 ├── vsc-extension-quickstart.md # 开发者快速上手（如何拉取/更新翻译） ├── translations/ │ ├── main.i18n.json # Azure Data Studio 主程序 UI 字符串（约 1.5 万行） │ └── extensions/ # 各扩展的本地化字符串 │ ├── Microsoft.mssql.i18n.json │ ├── Microsoft.arc.i18n.json │ ├── Microsoft.azurecore.i18n.json │ ├── Microsoft.notebook.i18n.json │ ├── Microsoft.sql-database-projects.i18n.json │ ├── ...（共 60+ 个 JSON 文件）

• package.json是扩展的清单文件，核心是contributes.localizations贡献点，声明了语言 ID、语言名称与全部翻译文件的映射；
• translations/存放实际翻译字符串，其中 main.i18n.json 覆盖产品主程序，extensions/子目录则按扩展 ID 逐一组织，如 Microsoft.mssql.i18n.json 负责 SQL Server 连接与查询相关界面。

2.1 package.json 中的 localizations 贡献点

打开 package.json 可以看到语言包如何“宣告自己”：

{ "name": "ads-language-pack-zh-hans", "displayName": "Chinese (Simplified) (简体中文) Language Pack for Azure Data Studio", "version": "1.49.0", "publisher": "Microsoft", "engines": { "vscode": "*", "azdata": "^1.49.0" }, "categories": ["Language Packs"], "keywords": ["中文(简体)"], "contributes": { "localizations": [ { "languageId": "zh-cn", "languageName": "Chinese Simplified", "localizedLanguageName": "中文(简体)", "translations": [ { "id": "vscode", "path": "./translations/main.i18n.json" }, { "id": "vscode.bat", "path": "./translations/extensions/vscode.bat.i18n.json" }, { "id": "Microsoft.mssql", "path": "./translations/extensions/Microsoft.mssql.i18n.json" }, { "id": "Microsoft.arc", "path": "./translations/extensions/Microsoft.arc.i18n.json" }, ... ] } ] } }

关键字段逐一说明：

这份清单里出现了 60 多个id，既有vscode.*前缀的内置功能（bat、git、json、markdown、python、r、sql、主题等），也有Microsoft.*前缀的 Azure Data Studio 专属扩展（admin-tool-ext-win、agent、arc、azcli、azurecore、azuremonitor、cms、dacpac、data-workspace、datavirtualization、import、kusto、machine-learning、mssql、notebook、profiler、query-history、query-store、resource-deployment、schema-compare、server-report、sql-assessment、sql-database-projects、sql-migration、sql-bindings-vscode 等），几乎覆盖了产品全部功能面。

2.2 翻译文件的数据结构

每个*.i18n.json都遵循同一套结构（文件头部明确标注 “Do not edit this file. It is machine generated.”，即机器生成、禁止手改）：

{ "": ["版权声明...", "Do not edit this file. It is machine generated."], "version": "1.0.0", "contents": { "vs/base/browser/ui/dialog/dialog": { "dialogClose": "关闭对话框", "ok": "确定", "error": "错误" }, "dist/features": { "mssql.missingLinkedAzureAccount": "Azure Data Studio 需要连接 Azure Key Vault 才能访问 Always Encrypted 的列主密钥..." } } }

其中contents的外层键是源码模块路径（如vs/base/browser/ui/dialog/dialog、dist/localizedConstants），内层键是源码中的英文字符串键，值即翻译文本。运行时，NLS 加载器会按模块路径+字符串键精确替换界面文案。这也解释了为何文件体积庞大——main.i18n.json 全文件约 1.5 万余行，覆盖了 Azure Data Studio 主程序几乎每一个可交互界面元素。

三、工作原理：语言包如何被加载与生效

语言包不是一个普通的功能扩展，而是一种特殊的“本地化扩展”。理解它的工作方式需要分两层：注册层与加载层。

3.1 注册层：语言包如何被发现

Azure Data Studio 的扩展管理服务会扫描所有已安装扩展的 manifest，凡是contributes.localizations非空的扩展都会被识别为语言包提供者。对应源码在 src/vs/platform/languagePacks/node/languagePacks.ts：

• createLanguagePacksFromExtension（第 142～168 行）遍历扩展的localizations贡献点，按languageId聚合语言包，并把每条translations[].path拼接为翻译文件的绝对路径存入languagePack.translations[id]；
• updateHash（第 170～178 行）基于扩展 ID 与版本计算 MD5，用于判断语言包是否需要更新；
• 聚合结果缓存到用户数据目录下的languagepacks.json（见LanguagePacksCache构造函数，第 113 行），getInstalledLanguages（第 64～77 行）据此返回所有已安装语言列表，并额外固定追加一项en（English）。

从源码结构可以推断：只要把一个符合规范的语言包扩展放入扩展目录（或通过扩展商店安装），languagepacks.json就会在扩展安装/卸载时自动重建（对应postInstallExtension/postUninstallExtension钩子），语言选项随即出现在“配置显示语言”列表中。

3.2 加载层：翻译字符串如何替换界面文案

界面文案的替换依赖 NLS（National Language Support）加载器。核心逻辑位于 src/vs/nls.ts 的load函数（第 170 行起）：

• 从 AMD 配置中读取availableLanguages，确定当前模块应使用哪种语言；
• 若useDefaultLanguage为假，则加载带语言后缀的 bundle（如.nls.zh-cn）；
• 若配置了translationServiceUrl，则直接向翻译服务按语言拉取消息，失败时回退到泛化语言（如de-CH失败回退de，见第 214～219 行注释）再失败则回退英文默认字符串，保证界面永不因缺翻译而空白。

当前生效语言由 src/vs/base/common/platform.ts 解析：桌面端读取VSCODE_NLS_CONFIG环境变量（第 116～128 行），其availableLanguages['*']决定_language；Web 端则通过nls.getConfiguredDefaultLocale获取（第 93～102 行），默认语言常量LANGUAGE_DEFAULT = 'en'（第 7 行）——这意味着未安装任何语言包时，界面始终回退为英文，中文界面必须依赖语言包显式安装并选中。

3.3 语言设置如何持久化

当用户通过命令面板选中“中文(简体)”后，桌面端 src/vs/workbench/services/localization/electron-sandbox/localeService.ts 的NativeLocaleService.setLocale（第 88 行起）会执行一套完整流程：

1. validateLocaleFile（第 54 行）先校验运行时设置文件argvResource（即argv.json）的 JSON 合法性，若文件损坏则弹出错误通知并提供“打开运行时设置”修复入口；
2. writeLocaleValue（第 80 行）通过jsonEditingService.write向argv.json写入{ "locale": "zh-cn" }；
3. 若语言包尚未安装，会先判断发布者是否为ms-ceintl（第 101 行），是则后台静默安装，否则在扩展视图里搜索该语言包引导用户手动安装；
4. showRestartDialog（第 142 行）弹出确认框，用户确认后调用hostService.restart()重启应用使新语言生效。

命令行层面，--locale参数也可以直接指定语言（见 src/vs/platform/environment/node/argv.ts 的'locale': { type: 'string', ... }定义，帮助文本为 “The locale to use (e.g. en-US or zh-TW)”），它与argv.json中locale字段属于同一设置通道。

四、安装与切换语言：完整操作指南

4.1 安装简体中文语言包

三种途径均可：

1. 扩展商店安装（推荐）：打开 Azure Data Studio 的“扩展”视图，搜索Chinese (Simplified)或zh-hans，找到微软发布的简体中文语言包后点击安装；
2. 离线 VSIX 安装：通过命令行--install-extension安装 VSIX 包（该参数的语义定义同样位于 argv.ts，支持publisher.name或本地.vsix路径）；
3. 仓库内置：本仓库已将语言包源码随产品一起维护在i18n/ads-language-pack-zh-hans/，开发者可从源码构建。

4.2 切换显示语言

按照 README.md 的官方说明，操作路径为：

1. 按Ctrl+Shift+P打开命令面板；
2. 输入display过滤命令，选择并回车执行“配置显示语言”（Configure Display Language）；
3. 弹出已安装语言列表，当前语言处于高亮状态，选择中文(简体)；
4. 按提示确认重启 Azure Data Studio，界面即切换为简体中文。

这条命令在源码中的实现位于 src/vs/workbench/contrib/localization/common/localizationsActions.ts：ConfigureDisplayLanguageAction（第 16 行）的命令 ID 为workbench.action.configureLocale，执行时会通过languagePackService.getInstalledLanguages()获取已安装语言、getAvailableLanguages()获取可安装语言，并以分隔线分组展示“已安装 / 可安装”两段列表（第 41～64 行），选中后调用localeService.setLocale完成切换。同一文件还提供了ClearDisplayLanguageAction（workbench.action.clearLocalePreference，第 96 行），用于清除语言偏好、恢复到默认英文界面。

4.3 撤销语言设置

如果希望回到默认英文界面，可在命令面板执行“清除显示语言偏好”（Clear Display Language Preference）。源码中对应clearLocalePreference（第 131 行）：它会向argv.json写入locale: undefined，并在当前非默认语言时提示重启（localeService.ts）。

五、字符串覆盖范围：从主程序到每个扩展

语言包的价值体现在覆盖广度。以仓库中翻译文件清单为准，translations/extensions/目录下 60 余个翻译文件大致可归为四类：

1. 编辑器基础设施（vscode.*前缀）：bat、docker、git、git-base、github、github-authentication、ipynb、javascript、json、json-language-features、markdown、markdown-language-features、markdown-math、media-preview、merge-conflict、microsoft-authentication、powershell、python、r、search-result、simple-browser、sql、theme-*（abyss、defaults、kimbie-dark、monokai、monokai-dimmed、quietlight、red、solarized-dark、solarized-light、tomorrow-night-blue、seti）、xml、yaml、builtin-notebook-renderers、configuration-editing。

2. 核心数据体验（Microsoft.*前缀）：mssql（SQL Server 连接、查询编辑、Always Encrypted 等）、arc（Azure Arc 数据服务）、azurecore（Azure 账户与订阅）、azuremonitor、notebook（笔记本）、kusto（Azure Data Explorer）、query-history、query-store、profiler、schema-compare、sql-assessment、server-report、dacpac、datavirtualization、data-workspace、sql-database-projects（SQL 数据库项目）、sql-migration（SQL 迁移）。

3. 云端与部署能力：azcli、asde-deployment（Azure SQL Edge/Edge 部署）、resource-deployment（资源部署）、machine-learning、import、cms、agent、admin-tool-ext-win、sql-bindings-vscode。

4. 主程序：main.i18n.json 单独覆盖工作台 UI 基础组件（对话框、按钮、输入框、弹窗、菜单等）。

以 Microsoft.mssql.i18n.json 为例，其翻译内容涉及dist/errorDiagnostics（连接错误诊断，如“启用信任服务器证书”提示）、dist/features（Always Encrypted 的 Azure Key Vault 访问提示）、dist/localizedConstants（令牌刷新、笔记本转换等常量文案）。这些字符串与 extensions/mssql 目录下的源码模块路径一一对应，印证了“翻译键 = 源码模块路径 + 字符串键”的映射关系。

六、社区化翻译流程：如何参与贡献

语言包的另一面是社区本地化协作。README.md 明确说明：

• 翻译字符串在微软社区本地化平台（MLCP）的 “DevTools - Azure Data Studio” 项目中维护；
• 这是“来自社区，奉献社区”的项目，社区成员可参与翻译与改进；
• 杰出贡献者 Joel Yang 在项目向社区开放后翻译了大部分新增字符串（累计 4 万余字）。

对于想要从源码层面同步翻译的开发者，vsc-extension-quickstart.md 给出了技术路径：

1. 将 VS Code 仓库克隆到语言包扩展的相邻目录；
2. 在vscode目录运行yarn初始化依赖；
3. 从 Transifex 获取 API Token 并设置为环境变量TRANSIFEX_API_TOKEN；
4. 运行npm run update-localization-extension zh-hans（语言包在相邻目录时）或npm run update-localization-extension {path_to_lang_pack_ext}（指定路径时）拉取最新翻译。

该脚本会自动下载翻译文件到translations目录，并同步更新localizations贡献点中的translations属性——这也解释了 package.json 中scripts.update为何写为cd ../vscode && npm run update-localization-extension zh-hans（第 291 行）：翻译文件本质上是机器生成的产物。

七、小结

通过把 CHANGELOG 的版本记录、package.json 的贡献点声明、translations 的字符串结构，以及languagePacks.ts、nls.ts、localeService.ts、localizationsActions.ts等核心源码串联起来，可以看到 Azure Data Studio 简体中文语言包是一套声明式注册 + 运行时按需加载 + 配置持久化的完整本地化闭环：

• 注册：contributes.localizations声明语言与翻译映射，扩展服务扫描后写入languagepacks.json；
• 加载：NLS 加载器依据当前 locale 按模块替换字符串，缺译时优雅回退英文；
• 切换：workbench.action.configureLocale命令经ILocaleService.setLocale写argv.json并重启生效；
• 演进：语言包随 Azure Data Studio 主版本迭代（当前为 1.49），并由社区平台持续维护。

对于使用 Azure Data Studio 的中文用户，安装并选中该语言包即可获得与英文版完全一致的完整中文界面；对于希望深度定制或参与本地化的开发者，本仓库的 语言包目录 与上述源码路径提供了从“翻译文件格式”到“加载机制”再到“更新流程”的全链路参考。

• 数据库客户端
• 桌面应用
• 数据分析