企业官网建设流程全解析

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

本篇技术指南以 Azure Data Studio 仓库内的法语语言包（French Language Pack）扩展（位于i18n/ads-language-pack-fr/）为对象，系统讲解语言包扩展的目录结构、localizations贡献点的 JSON 声明方式，以及如何通过 Transifex 与update-localization-extension构建脚本将最新翻译同步回translations目录。读完本文，你将掌握语言包扩展从「清单声明」到「翻译文件落盘」再到「构建脚本自动写回 package.json」的完整工作流，并可直接复用到其他语种的语言包扩展维护中。

Azure Data Studio 支持 Windows、macOS 与 Linux，并提供多语言界面体验。法语语言包正是这一机制的一个典型落地示例：它以独立扩展的形式存在，通过贡献点声明语言 ID，由宿主应用在运行时按当前显示语言加载对应的翻译字符串。本指南将围绕该扩展的vsc-extension-quickstart.md文档展开，并结合仓库中的真实配置与构建脚本，给出可操作的完整说明。

语言包扩展的目录结构与角色划分

法语语言包扩展位于 i18n/ads-language-pack-fr/，其核心组成如下：

• package.json—— 扩展清单文件，定义扩展的名称、描述、版本、引擎要求，以及最关键的语言本地化（localizations）贡献点；
• translations/—— 存放翻译字符串的目录，包含面向核心界面与各内置/微软扩展的.i18n.json文件；
• README.md—— 面向终端用户的用法说明（语言切换、社区贡献、许可与致谢）；
• CHANGELOG.md、languagepack.png、yarn.lock—— 变更记录、扩展图标与依赖锁定文件。

其中，package.json与translations/是语言包扩展的「双支柱」：前者告诉宿主应用「这个扩展提供哪种语言」，后者提供「这种语言的具体翻译内容」。原文档vsc-extension-quickstart.md明确将这两个部分列为语言包扩展的核心组成，下面分别展开。

package.json 与 localizations 贡献点：语言身份声明

原文档给出了语言包扩展最核心的 JSON 结构——localizations贡献点，用于向宿主声明语言 ID：

"contributes": { "localization": [{ "languageId": "fr", "languageName": "French", "localizedLanguageName": "français" }] }

在 Azure Data Studio 仓库中，法语语言包的实际配置位于 i18n/ads-language-pack-fr/package.json，其声明比文档示例更完整，包含了translations文件映射：

{ "name": "ads-language-pack-fr", "displayName": "French Language Pack for Azure Data Studio", "version": "1.49.0", "publisher": "Microsoft", "engines": { "vscode": "*", "azdata": "^1.49.0" }, "icon": "languagepack.png", "categories": ["Language Packs"], "keywords": ["français"], "contributes": { "localizations": [{ "languageId": "fr", "languageName": "French", "localizedLanguageName": "français", "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" }, ... ] }] } }

几个值得注意的细节：

• localization与localizations：原文档示例中的贡献点键名为localization（单数），而仓库实际使用的键名是localizations（复数）。构建脚本 build/npm/update-localization-extension.js 在解析时明确要求contributes.localizations为数组，并逐项校验每个元素必须同时具备languageId、languageName与localizedLanguageName三个属性，否则直接抛错。因此实际开发中应以localizations为准。
• translations数组：每个条目由id（对应源码或扩展模块标识）与path（指向.i18n.json文件）组成。核心界面的翻译统一由vscode条目指向./translations/main.i18n.json，其余条目则覆盖内置扩展（vscode.git、vscode.sql、vscode.markdown-language-features等）以及微软数据类扩展（Microsoft.mssql、Microsoft.arc、Microsoft.machine-learning、Microsoft.sql-database-projects、Microsoft.sql-migration、Microsoft.notebook等），映射关系可完整查阅 package.json 的contributes.localizations段。
• engines.azdata：版本号^1.49.0表明该语言包与 Azure Data Studio 1.49.x 版本线匹配，即此扩展的翻译面向该主版本之上的宿主应用。

在宿主应用侧，语言包的加载与解析逻辑位于 src/vs/platform/languagePacks/，分为common、browser、node三层实现（common/languagePacks.ts定义接口与数据结构，node/languagePacks.ts与browser/languagePacks.ts分别实现桌面与浏览器环境下的语言包发现和翻译文件读取）。从源码结构看，宿主会根据当前显示语言（locale）匹配已安装语言包贡献点中的languageId，再按translations数组逐模块加载对应翻译。

translations 目录：翻译字符串的存放形态

translations/目录是语言包扩展的第二个核心部分，其真实结构为：

translations/ ├── main.i18n.json # 核心界面翻译（vs/base、vs/workbench 等模块） └── extensions/ ├── Microsoft.admin-tool-ext-win.i18n.json ├── Microsoft.agent.i18n.json ├── Microsoft.arc.i18n.json ├── Microsoft.asde-deployment.i18n.json ├── Microsoft.azcli.i18n.json ├── Microsoft.azurecore.i18n.json ├── Microsoft.azuremonitor.i18n.json ├── Microsoft.cms.i18n.json ├── Microsoft.dacpac.i18n.json ├── Microsoft.data-workspace.i18n.json ├── Microsoft.datavirtualization.i18n.json ├── Microsoft.import.i18n.json ├── Microsoft.kusto.i18n.json ├── Microsoft.machine-learning.i18n.json ├── Microsoft.mssql.i18n.json ├── Microsoft.notebook.i18n.json ├── Microsoft.profiler.i18n.json ├── Microsoft.query-history.i18n.json ├── ...（其余扩展翻译文件） └── main.i18n.json 之外的内置扩展翻译

以 translations/main.i18n.json 为例，其内部结构分为两层：顶层是version（1.0.0）与contents，contents下以源码模块路径（如vs/base/browser/ui/button/button）为键，模块下再以原始英文字符串键名映射法语译文：

{ "version": "1.0.0", "contents": { "vs/base/browser/ui/button/button": { "button dropdown more actions": "Plus d'actions..." }, "vs/base/browser/ui/dialog/dialog": { "dialogClose": "Fermer la boîte de dialogue", "dialogErrorMessage": "Erreur", "dialogInfoMessage": "Infos", "ok": "OK" }, "vs/base/browser/ui/findinput/findInputToggles": { "caseDescription": "Respecter la casse", "regexDescription": "Utiliser une expression régulière", "wordsDescription": "Mot entier" } } }

文件头部同时包含版权声明与「本文件由机器生成，请勿手动编辑」的提示（Do not edit this file. It is machine generated.），这一点与原文档介绍的「通过脚本从 Transifex 拉取最新字符串」的流程相呼应——翻译文件应当由自动化工具生成，而非手工维护。

在 Azure Data Studio 中切换法语界面

语言包安装后，终端用户可通过「Configure Display Language（配置显示语言）」命令切换界面语言，具体操作在 i18n/ads-language-pack-fr/README.md 中有明确说明：

1. 按下Ctrl+Shift+P打开命令面板（Command Palette）；
2. 输入display过滤并定位Configure Display Language命令；
3. 按Enter后，宿主会按区域设置列出已安装的语言列表，当前语言处于高亮状态；
4. 选择fr（或列表中的法语条目）即可将界面语言切换为法语。

切换后，Azure Data Studio 将依据localizations贡献点中的映射加载 translations/main.i18n.json 及各扩展翻译文件，完成界面文案的本地化渲染。

从 Transifex 同步最新翻译：完整操作流程

原文档给出了语言包维护者同步翻译的核心流程，其目标是从微软翻译平台 Transifex 拉取最新翻译字符串，填充translations/目录，并同步更新package.json中的translations属性。以下按文档步骤并结合仓库脚本逐一展开。

前置准备：克隆并初始化 VS Code 仓库

由于语言包翻译的源工程基于 VS Code 仓库，原文档建议：

1. 检出 VS Code 仓库的master分支；
2. 推荐将 VS Code 仓库与语言包扩展放在同一父目录下（即两者相邻，便于脚本通过相对路径找到语言包）；
3. 进入vscode目录并运行yarn初始化依赖。

配置 Transifex API 令牌

1. 登录 Transifex，在用户设置中获取 API Token；
2. 将 Token 写入环境变量：

export TRANSIFEX_API_TOKEN=<你的令牌>

该环境变量在后续npm run update-localization-extension执行时被读取，用于向 Transifex 服务端发起认证请求。

执行更新脚本

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

• 若语言包扩展与 VS Code 仓库相邻（同一父目录），直接指定语言代码：

npm run update-localization-extension fr

• 否则，显式传入语言包扩展所在路径：

npm run update-localization-extension {path_to_lang_pack_ext}

该 npm 脚本在 Azure Data Studio 仓库根 package.json 中也有对应声明（"update-localization-extension": "node build/npm/update-localization-extension.js"），其底层实现即 build/npm/update-localization-extension.js。

脚本执行背后的工作原理

从 build/npm/update-localization-extension.js 的源码可以看到完整的数据流：

1. 参数解析与校验：脚本通过minimist解析命令行参数，idOrPath为语言代码或语言包目录路径；若为纯语言代码（匹配^\w{2,3}(-\w+)?$），会将其映射到vscode-loc仓库中对应语言包目录。若传入的目录不存在，或package.json中缺少localizations贡献点，脚本会分别抛出明确错误（如No directory found at ...、The extension must define a "localizations" contribution）。
2. 语言 ID 归一化：对zh-cn、zh-tw、pt-br分别归一化为zh-Hans、zh-Hant、pt-BR，确保与 BCP 47 标准写法一致。
3. 清理旧翻译：若translations/目录已存在且包含main.i18n.json，脚本会先清空该目录，保证每次同步都是全新落盘，避免陈旧字符串残留。
4. 拉取并转换：通过gulp.src匹配 Transifex 导出目录下的**/{languageId}/*.xlf文件，以及外部扩展的*-new.xlf文件，交给i18n.prepareI18nPackFiles管道转换为.i18n.json包文件，再经vfs.dest写入translations/目录。
5. 回写 package.json：转换完成后，脚本收集所有产出文件的id与文件名，重组localization.translations数组（形如{ id: tp.id, path: "./translations/${tp.resourceName}" }），并以制表符缩进重新写回语言包的 package.json。这正是原文档所述「同时填充localizations贡献点中的translations属性」的实现落点。

此外，i18n/ads-language-pack-fr/package.json 的scripts段还预置了快捷命令：

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

即当 VS Code 仓库与语言包相邻时，在语言包目录内直接运行yarn update即可完成一次翻译同步，无需手动拼接路径。

维护注意事项与约束

综合原文档、构建脚本与仓库现状，语言包维护者应注意以下几点：

• 不要手工编辑translations/下的.i18n.json文件：文件头明确标注机器生成，且脚本每次更新会先清空目录再重新落盘，手工改动会被覆盖；翻译的增删改应统一走 Transifex 平台。
• localizations数组元素必填字段：languageId、languageName、localizedLanguageName三者缺一不可，脚本校验不通过会直接中止执行（见 build/npm/update-localization-extension.js）。
• 保持engines.azdata与目标版本一致：语言包面向特定 Azure Data Studio 版本线，升级宿主版本时需同步评估是否需要更新语言包版本与翻译覆盖范围。
• 翻译覆盖范围：从 package.json 可见，法语包同时覆盖核心界面与大量微软扩展（如Microsoft.mssql、Microsoft.machine-learning、Microsoft.arc、Microsoft.sql-database-projects、Microsoft.sql-migration等），新增扩展或新增界面文案后，应通过更新流程及时补充对应翻译。

结语

法语语言包是 Azure Data Studio 多语言机制的一个完整缩影：package.json的localizations贡献点声明语言身份与文件映射，translations/目录承载按模块组织的翻译内容，update-localization-extension脚本则把 Transifex 上的社区翻译自动转换为本地包文件并写回清单。理解这一「声明—存放—同步」闭环，即可举一反三地维护其余语种语言包（仓库内另有ads-language-pack-de、ads-language-pack-ja、ads-language-pack-zh-hans等十余个同构扩展），并为 Azure Data Studio 的本地化生态贡献一份力量。

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