企业官网建设流程全解析

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

本篇技术指南以 Azure Data Studio 仓库内的韩国语语言包扩展（i18n/ads-language-pack-ko/vsc-extension-quickstart.md）为蓝本，系统讲解如何搭建、配置并通过 Transifex 持续更新一个Language Packs类型扩展：涵盖package.json清单中localizations贡献点的字段语义、translations目录的翻译文件结构，以及从拉取翻译到发布新版的完整命令行流程。读完本文，你将掌握语言包扩展的标准骨架，并能独立为 Azure Data Studio（及同构的 VS Code 系产品）维护一套韩语或其他语言的本地化扩展。

语言包扩展的定位与目录结构

Azure Data Studio 的界面本地化采用“语言包扩展（Language Pack Extension）”机制：核心产品本身不内嵌所有语言，而是通过独立的扩展为每种语言提供一套翻译字符串。以ads-language-pack-ko为例，其扩展目录包含两类核心资产：

• package.json——扩展的清单文件（manifest），声明扩展名称、描述、版本、发布者，并通过localizations贡献点声明语言标识；
• translations/——存放翻译字符串的目录，内部按“主界面 + 各扩展”拆分为多个.i18n.json文件。

打开仓库中的实际清单文件 i18n/ads-language-pack-ko/package.json 可以看到，它的元信息包括name: ads-language-pack-ko、displayName: Korean Language Pack for Azure Data Studio、publisher: Microsoft、categories: ["Language Packs"]，且engines同时声明了对vscode与azdata（^1.49.0）的兼容要求——这正说明该扩展需要同时服务于 Azure Data Studio 与其底层的 VS Code 运行时。

localizations贡献点：语言包的核心声明

语言包之所以能被主程序识别为“一种可用语言”，依靠的是package.json中contributes.localizations贡献点。该贡献点以数组形式声明一个或多个语言条目，每条包含三个关键字段：

在原文档 vsc-extension-quickstart.md 给出的最小声明基础上，仓库中的真实清单还增加了关键的translations子属性，用于将语言 ID 映射到具体的翻译文件路径：

"contributes": { "localizations": [ { "languageId": "ko", "languageName": "Korean", "localizedLanguageName": "한국어", "translations": [ { "id": "vscode", "path": "./translations/main.i18n.json" }, { "id": "Microsoft.mssql", "path": "./translations/extensions/Microsoft.mssql.i18n.json" } ] } ] }

这里的id是翻译目标模块的标识：vscode对应主程序核心 UI，Microsoft.mssql、Microsoft.arc、Microsoft.notebook等则对应 extensions 目录下的各个业务扩展。完整的translations映射列表（共 40 余项）可在 i18n/ads-language-pack-ko/package.json 的contributes.localizations[0].translations中查看。注意：原文档中的示例使用的是单数localization字段名，而实际仓库清单采用的是复数localizations，二者在结构上一致，均通过languageId关联语言。

translations目录：翻译文件的分层组织

translations/目录是语言包的“内容主体”，其内部结构分为两层：

• main.i18n.json——主界面翻译。仓库中该文件体量约 1.5 万行（见 i18n/ads-language-pack-ko/translations/main.i18n.json），按vs/...源码模块路径（如vs/base/browser/ui/dialog/dialog）组织键值对，覆盖编辑器、命令面板、对话框等核心 UI 元素；
• extensions/*.i18n.json——按扩展名拆分的翻译文件，命名规则为{发布者}.{扩展名}.i18n.json，例如Microsoft.mssql.i18n.json、vscode.git.i18n.json、Microsoft.sql-database-projects.i18n.json等，与 extensions 目录下的扩展一一对应。

每个.i18n.json的顶层结构统一为version+contents两个键，contents内以源码模块路径为一级键、以源码中的英文 key 为二级键、以本地化字符串为值。以 i18n/ads-language-pack-ko/translations/extensions/Microsoft.mssql.i18n.json 为例：

{ "version": "1.0.0", "contents": { "dist/localizedConstants": { "mssql.tokenRefreshFailed": "{0} AAD 토큰 새로 고침에 실패했습니다. {0}을(를) 활성화하려면 다시 연결하세요." } } }

这种“按扩展分文件”的组织方式让每个扩展的维护者可以独立追踪翻译进度，也让语言包扩展的体积与主程序解耦——Azure Data Studio 只需按需加载对应扩展的翻译文件即可。

从 Transifex 同步翻译：标准更新流程

原文档 vsc-extension-quickstart.md 的核心章节给出了从 Transifex 拉取最新翻译并回填到扩展目录的完整流程，这是语言包维护者最常执行的操作。以下按步骤展开并补充实操细节。

第一步：准备 VS Code 主仓库

翻译同步脚本运行在 VS Code（Azure Data Studio 的上游框架）主仓库中，因此需要先检出其master分支并完成依赖初始化：

git clone https://github.com/Microsoft/vscode cd vscode yarn

最佳实践是把 VS Code 仓库与语言包扩展放在同一父目录下（即二者是兄弟目录），这样更新脚本可以按约定路径直接找到扩展目录，无需额外传参。

第二步：获取并配置 Transifex API Token

翻译字符串托管在 Transifex 平台（微软本地化社区流程），同步脚本需要调用其 API 下载翻译，因此必须先获取凭证：

1. 登录 Transifex，在用户设置中的 API 页面生成个人 API Token；
2. 将 Token 写入环境变量：

export TRANSIFEX_API_TOKEN=<your_transifex_api_token>

第三步：执行更新脚本

回到 VS Code 仓库目录后，执行update-localization-extension脚本。脚本的调用方式取决于扩展目录的位置：

# 方式一：语言包扩展与 VS Code 仓库位于同一父目录下（推荐） npm run update-localization-extension ko # 方式二：扩展位于其他路径，显式传入扩展目录路径 npm run update-localization-extension {path_to_lang_pack_ext}

仓库清单文件 i18n/ads-language-pack-ko/package.json 的scripts节也固化了一条等价脚本："update": "cd ../vscode && npm run update-localization-extension ko"，前提同样是 VS Code 仓库与语言包扩展互为兄弟目录。

第四步：校验更新结果

脚本运行成功后会产生两类效果，需要逐一核对：

• 下载翻译文件到translations/目录：main.i18n.json与extensions/下各.i18n.json的内容应随之更新（文件头部标注Do not edit this file. It is machine generated.，即该文件由机器生成，不应手工编辑）；
• 回填translations属性：脚本会同步更新package.json中localizations[0].translations数组，将新加入翻译的扩展自动追加为新的{ id, path }条目，确保清单与实际文件保持一致。

语言包在 Azure Data Studio 中的启用方式

翻译同步完成、扩展打包发布后，用户侧的使用方式很简单。语言包自带的 i18n/ads-language-pack-ko/README.md 说明了如何切换界面语言：

1. 按Ctrl+Shift+P打开命令面板；
2. 输入display过滤出Configure Display Language（显示语言配置）命令并执行；
3. 面板会列出所有已安装语言对应的 locale（当前语言高亮显示），选择ko（한국어）即可将 UI 切换为韩语。

该命令本质上是在覆盖默认 UI 语言，因此即使系统 locale 不是韩语，也能按需切换。

维护节奏与版本管理

从语言包的 i18n/ads-language-pack-ko/CHANGELOG.md 可以看出其发布节奏与 Azure Data Studio 主版本严格对齐：每个 Azure Data Studio 版本（1.33～1.49）发布时，语言包都会同步跟进一个新版本（如Release for Azure Data Studio 1.49，版本号为 1.49.0）。这意味着语言包维护者应把“更新翻译 → 校验translations映射 → 提升版本号 → 发布”固化为与主版本绑定的例行流程，且所有步骤都应围绕localizations贡献点与translations/目录的一致性展开。

小结

语言包扩展的本质并不复杂：通过package.json的localizations贡献点向主程序声明“我提供ko（한국어）这套语言”，再以translations/目录按模块分层承载翻译字符串，最后借 Transifex 的update-localization-extension脚本实现翻译的持续同步。掌握了这一套骨架与流程，你就可以照葫芦画瓢，为 Azure Data Studio 乃至任何 VS Code 系产品维护任意语言的语言包，并保证每个主版本发布时本地化内容都同步就位。

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