企业官网建设流程全解析

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

本篇技术指南以 Azure Data Studio 仓库中官方语言包扩展的快速入门文档（i18n/ads-language-pack-zh-hant/vsc-extension-quickstart.md）为核心骨架，结合仓库内真实的package.json清单、translations翻译数据与 build/npm/update-localization-extension.js 底层脚本，完整讲解语言包（Language Pack）扩展的目录结构、localizations贡献点声明方式，以及如何从 Transifex 拉取并更新翻译的完整流程。读完本文，你将掌握"基于 VS Code 扩展模型的语言包到底由什么组成、翻译数据如何被清单引用、同步脚本背后的执行逻辑"，并能独立完成语言包的搭建、同步与在 Azure Data Studio 中的启用。

语言包扩展的本质：一份清单 + 一个翻译目录

Azure Data Studio 基于 VS Code 扩展体系构建，其多语言支持通过"语言包扩展（Language Pack Extension）"实现。以本仓库的 i18n/ads-language-pack-zh-hant 为例，整个扩展本质上只有两个核心组成部分：

• package.json：扩展的清单文件（manifest），定义扩展的名称、描述，并通过localizations贡献点声明它所支持的语言 ID；
• translations/：存放翻译字符串的目录，每个 JSON 文件对应一组 UI 模块或子扩展的本地化文本。

官方快速入门文档明确给出了localizations贡献点的最小声明结构：

"contributes": { "localization": [{ "languageId": "zh-tw", "languageName": "Chinese Traditional", "localizedLanguageName": "中文(繁體)" }] }

其中：

这三项属性是语言包扩展的"身份证"，缺一不可。

真实清单剖析：ads-language-pack-zh-hant 的 package.json

对照仓库中实际生效的 i18n/ads-language-pack-zh-hant/package.json，可以看到完整清单远不止三行声明，它同时约束了扩展的运行环境与翻译资源映射：

{ "name": "ads-language-pack-zh-hant", "displayName": "Chinese (Traditional) Language Pack for Azure Data Studio", "description": "Language pack extension for Chinese (Traditional)", "version": "1.49.0", "publisher": "Microsoft", "engines": { "vscode": "*", "azdata": "^1.49.0" }, "icon": "languagepack.png", "categories": [ "Language Packs" ], "contributes": { "localizations": [ { "languageId": "zh-tw", "languageName": "Chinese Traditional", "localizedLanguageName": "中文(繁體)", "translations": [ { "id": "vscode", "path": "./translations/main.i18n.json" }, { "id": "vscode.sql", "path": "./translations/extensions/vscode.sql.i18n.json" }, { "id": "Microsoft.mssql", "path": "./translations/extensions/Microsoft.mssql.i18n.json" }, { "id": "Microsoft.arc", "path": "./translations/extensions/Microsoft.arc.i18n.json" } ] } ] }, "scripts": { "update": "cd ../vscode && npm run update-localization-extension zh-hant" } }

值得注意的几点实现细节：

• engines双约束：同时声明"vscode": "*"与"azdata": "^1.49.0"，说明该语言包既遵循 VS Code 的扩展模型，又对 Azure Data Studio 主版本（≥ 1.49.0）有兼容性要求，防止与宿主版本不匹配导致加载失败。
• translations数组即资源索引：localizations贡献点内的每个translations条目将"模块 ID"（如vscode、Microsoft.mssql）映射到相对./translations/目录的具体 JSON 文件。宿主启动时据此按 ID 装载对应模块的本地化字符串。
• 覆盖范围广：仓库中translations数组实际包含 60 余个条目，既覆盖vscode.sql、vscode.git、vscode.notebook等内置模块，也覆盖Microsoft.mssql、Microsoft.arc、Microsoft.azurecore、Microsoft.sql-migration等 Azure Data Studio 专属扩展，确保整个工作台的 UI 体验是完整的繁体中文。

translations 目录：翻译数据的存放与格式

translations/目录由翻译 JSON 文件组成，从仓库目录树可以看到其组织方式：

• translations/main.i18n.json：主翻译文件，对应宿主核心 UI（约 1.5 万行）；
• translations/extensions/*.i18n.json：按扩展逐一存放，例如Microsoft.mssql.i18n.json、vscode.sql.i18n.json。

打开 translations/main.i18n.json 可以看到其内部格式以"模块路径 → 键值对"嵌套组织：

{ "version": "1.0.0", "contents": { "vs/base/browser/ui/dialog/dialog": { "dialogClose": "關閉對話方塊", "dialogErrorMessage": "錯誤", "ok": "確定" }, "vs/base/browser/ui/findinput/findInputToggles": { "caseDescription": "大小寫須相符", "regexDescription": "使用規則運算式", "wordsDescription": "全字拼寫須相符" } } }

格式要点：

• 文件头部以"": [...]数组形式保留版权声明与"本文件由机器生成、请勿手工编辑"的警示；
• contents的键对应源码中的模块路径（如vs/base/browser/ui/dialog/dialog），值是该模块内原始字符串键到繁体中文翻译的映射；
• 这类文件由同步脚本自动生成，不建议手工修改，否则下次同步会被覆盖。

从 Transifex 同步最新翻译：官方完整流程

官方快速入门文档给出了标准化的翻译同步工作流，其目标是"用 Transifex 上最新的翻译字符串，重新生成并填充translations目录，同时更新package.json中的translations属性"。完整步骤如下：

第一步：准备 VS Code 仓库与依赖

1. 检出 VS Code 仓库的master分支（Azure Data Studio 的语言包同步脚本直接复用 VS Code 的构建基础设施）；
2. 建议将 VS Code 仓库放在语言包扩展的同级目录（即两者拥有共同的父目录），以便后续命令使用相对路径；
3. 进入vscode目录执行yarn，完成仓库依赖初始化。

第二步：配置 Transifex API Token

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

export TRANSIFEX_API_TOKEN="your_transifex_api_token"

同步脚本会在运行时读取该环境变量，用于向 Transifex 拉取翻译文件。

第三步：执行同步命令

进入 VS Code 仓库目录，按语言包扩展的位置选择命令：

# 情况一：语言包扩展与 VS Code 仓库同级放置 npm run update-localization-extension zh-hant # 情况二：语言包扩展位于其他路径 npm run update-localization-extension {path_to_lang_pack_ext}

执行完成后，翻译文件会被下载到translations目录，同时脚本会把新生成的翻译文件路径回填到localizations贡献点的translations属性中，实现"清单与数据自动对齐"。

在本仓库中，i18n/ads-language-pack-zh-hant/package.json 的scripts.update正是上述情况的封装：

"scripts": { "update": "cd ../vscode && npm run update-localization-extension zh-hant" }

即：从语言包目录跳到同级vscode目录，再调用其更新脚本为zh-hant语言生成翻译数据。

底层原理：update-localization-extension 脚本的执行逻辑

仓库根目录 package.json 中注册了对应的 npm 脚本：

"update-localization-extension": "node build/npm/update-localization-extension.js"

深入 build/npm/update-localization-extension.js 源码，可以还原整个同步流程的真实执行顺序：

1. 解析目标参数：脚本通过minimist解析location（翻译源文件位置）与externalExtensionsLocation（外部扩展翻译位置）两个可选参数，并校验路径是否存在（源码第 22-29 行）；
2. 定位语言包目录：如果参数形如zh-hant这类语言短码，脚本会按约定拼接出../vscode-loc/i18n/vscode-language-pack-zh-hant目录；如果传入的是显式路径则直接使用（源码第 30-37 行）；
3. 读取并校验清单：解析语言包package.json，强制校验contributes.localizations数组存在，且每个条目都定义languageId、languageName、localizedLanguageName三属性（源码第 38-51 行）；
4. 语言 ID 规范化：将zh-tw映射为zh-Hant、zh-cn映射为zh-Hans、pt-br映射为pt-BR，用于匹配 Transifex 侧的真实目录命名（源码第 55-65 行）；
5. 清理旧数据：若translations/main.i18n.json已存在，先用rimraf清空整个translations目录，保证每次同步都是全量重建（源码第 67-70 行）；
6. 导入并转换：通过gulp.src通配**/<languageId>/*.xlf（含外部扩展的*-new.xlf），经i18n.prepareI18nPackFiles将 XLF 翻译文件转换为扩展所需的 i18n JSON 包，并写入translations目录（源码第 74-90 行）；
7. 回写清单：转换完成后，把生成的每个翻译文件以{ id, path: "./translations/<资源名>" }形式回填到package.json的translations数组并落盘（源码第 93-97 行）。

这解释了为什么文档说"同步会同时更新translations目录和package.json的translations属性"——清单回写正是由脚本第 97 行的fs.writeFileSync完成的。

在 Azure Data Studio 中启用繁体中文界面

翻译数据就绪后，普通用户无需接触命令行即可切换界面语言。仓库内 i18n/ads-language-pack-zh-hant/README.md 给出了官方操作路径：

1. 在 Azure Data Studio 中安装"Chinese (Traditional) Language Pack"扩展；
2. 按Ctrl+Shift+P打开命令面板（Command Palette）；
3. 输入display过滤命令，选择Configure Display Language（設定顯示語言）；
4. 按Enter后，宿主会列出所有已安装语言（按 locale 标识），当前语言高亮显示；
5. 选择中文(繁體)即可切换 UI 语言，并覆盖默认的系统语言设置。

该命令实际上是在告诉宿主读取各已安装语言包的localizations贡献点，以localizedLanguageName作为菜单中的显示名——这也是package.json中该字段必须使用目标语言自述的原因。

常见问题与注意事项

• 不要在translations里手工改翻译：文件头部明确标注"machine generated"（机器生成），任何手工修改都会在下次同步时被整体重建覆盖；如需修正翻译，应回到 Transifex 平台操作后重新同步。
• engines版本匹配：语言包与 Azure Data Studio 主版本存在对应关系（本仓库为^1.49.0），升级宿主大版本后应及时更新语言包版本，避免兼容性告警。
• 路径参数二选一：同步脚本既接受语言短码（zh-hant），也接受语言包扩展的显式路径；使用短码时请确保语言包位于约定位置（../vscode-loc/i18n/vscode-language-pack-<id>）。
• 环境变量必须就位：TRANSIFEX_API_TOKEN未设置或失效时，同步将无法从 Transifex 拉取翻译，命令会以错误结束。
• 本地化范围取决于清单条目：最终界面中哪些模块显示为繁体中文，完全由package.json中translations数组列出的条目决定；新增或移除某个扩展的本地化，需要同步更新该数组。

小结

一份语言包扩展 = 一份声明localizations贡献点的package.json+ 一组按模块组织的 i18n JSON 翻译文件。通过 Transifex 拉取 XLF 翻译、由 build/npm/update-localization-extension.js 脚本完成格式转换与清单回写，再借助 Azure Data Studio 的"設定顯示語言"命令切换生效——这就是完整闭环。本文涉及的清单文件（i18n/ads-language-pack-zh-hant/package.json）、翻译数据（i18n/ads-language-pack-zh-hant/translations/main.i18n.json）与同步脚本（build/npm/update-localization-extension.js）均可在当前仓库中直接查阅，作为搭建其他语言包扩展时的参照模板。

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