企业官网建设流程全解析

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

本文以 Azure Data Studio 仓库中 i18n/ads-language-pack-es/vsc-extension-quickstart.md 为核心骨架，结合语言包真实清单文件与编辑器侧本地化基础设施源码，系统讲解 Azure Data Studio 语言包扩展的目录结构、localizations贡献点协议、翻译文件格式，以及如何通过 VS Code 仓库的update-localization-extension脚本从 Transifex 拉取并同步翻译串。读完本文，你将能够理解语言包扩展的完整生命周期，并掌握“新增语言 → 声明贡献点 → 同步翻译 → 安装切换”的端到端工作流。

Azure Data Studio 支持 Windows、macOS 与 Linux，其多语言 UI 能力正是通过“语言包扩展（Language Pack Extension）”机制实现的。仓库的 i18n 目录下存放了 10 个官方语言包（德语、西班牙语、法语、意大利语、日语、韩语、葡萄牙语、俄语、简体中文、繁体中文），其中 ads-language-pack-es 即为西班牙语（es）语言包。本文以该扩展的快速上手文档为主线，逐层拆解其实现原理与维护流程。

一、语言包扩展的目录结构与核心角色

一个语言包扩展的顶层结构非常精简，以西班牙语包为例：

i18n/ads-language-pack-es/ ├── CHANGELOG.md # 按 Azure Data Studio 版本发布的翻译更新记录 ├── README.md # 双语使用说明（es / en）与贡献者名单 ├── languagepack.png # 扩展图标 ├── package.json # 扩展清单，声明 localizations 贡献点 ├── translations/ # 存放全部翻译字符串文件 │ ├── main.i18n.json │ └── extensions/ └── yarn.lock

整个扩展只有两个“灵魂”：

1. package.json—— 扩展清单（manifest），除定义名称、描述、版本外，还通过contributes.localizations贡献点声明“本扩展为哪种语言提供翻译”；
2. translations/—— 存放翻译字符串的目录，由机器生成，不应手工编辑（其生成的main.i18n.json文件头部即注明Do not edit this file. It is machine generated.）。

package.json中与本扩展身份直接相关的字段如下（摘自 i18n/ads-language-pack-es/package.json）：

{ "name": "ads-language-pack-es", "displayName": "Spanish Language Pack for Azure Data Studio", "description": "Language pack extension for Spanish", "version": "1.49.0", "publisher": "Microsoft", "engines": { "vscode": "*", "azdata": "^1.49.0" }, "icon": "languagepack.png", "categories": ["Language Packs"], "keywords": ["español"] }

其中engines.azdata: "^1.49.0"明确了该语言包对应的 Azure Data Studio 主版本约束，与 CHANGELOG.md 中“May 13, 2024 - Release for Azure Data Studio 1.49”的记录相互印证——语言包版本与 ADS 主版本一一对应、按版本节奏发布。

二、localizations 贡献点：语言包的核心协议

快速上手文档开门见山地指出，package.json通过localizations贡献点定义语言 id。西班牙语包的声明如下（摘自 package.json）：

"contributes": { "localization": [{ "languageId": "es", "languageName": "Spanish", "localizedLanguageName": "español" }] }

注意：仓库中语言包实际使用的贡献点键名是复数形式localizations（见 package.json），快速上手文档中的单数写法是早期模板遗留，二者所指协议相同。

字段语义与校验规则（源码级）

编辑器侧对该扩展点的解析与校验实现在 src/vs/workbench/contrib/localization/common/localization.contribution.ts，通过ExtensionsRegistry.registerExtensionPoint({ extensionPoint: 'localizations', ... })注册。各字段含义如下：

其中translations数组的每个元素包含两个必填字段：

• id：被翻译对象（VS Code 核心或某个扩展）的标识。VS Code 核心固定为vscode，扩展则必须是publisherId.extensionName格式，校验正则（见 localization.contribution.ts）为^((vscode)|([a-z0-9A-Z][a-z0-9A-Z-]*)\.([a-z0-9A-Z][a-z0-9A-Z-]*))$；
• path：指向翻译文件的相对路径（如./translations/main.i18n.json）。

这一协议的作用是：当用户切换显示语言时，编辑器会汇总所有已安装语言包中languageId匹配的扩展点声明，按其translations列表加载对应path下的翻译文件。因此，翻译覆盖面完全由translations数组决定——它既可以只翻译核心 UI，也可以为仓库内的每一个 Microsoft 扩展单独提供翻译。

西班牙语包的翻译覆盖面

在 i18n/ads-language-pack-es/package.json 中，translations数组共列出了 59 个条目，可分为三类：

1. 核心 UI 与内置模块：vscode（指向./translations/main.i18n.json）、vscode.bat、vscode.git、vscode.sql、vscode.markdown-language-features、vscode.python、vscode.yaml等；
2. ADS 官方功能扩展：Microsoft.mssql、Microsoft.notebook、Microsoft.arc、Microsoft.azurecore、Microsoft.machine-learning、Microsoft.sql-database-projects、Microsoft.schema-compare、Microsoft.sql-migration、Microsoft.import、Microsoft.dacpac、Microsoft.profiler、Microsoft.query-history、Microsoft.agent、Microsoft.kusto、Microsoft.azuremonitor等；
3. 少数非 Microsoft 前缀的扩展：如ms-mssql.sql-bindings-vscode。

可以看到，translations条目与仓库 extensions 目录下的扩展基本一一对应（如 extensions/mssql、extensions/notebook），这保证了西班牙语用户在安装了这些官方扩展后，扩展内文案同样被本地化。

三、translations 目录：翻译文件的实际格式

快速上手文档将translations定义为“the folder containing the translation strings”。以核心翻译文件 translations/main.i18n.json 为例，其顶层结构为：

{ "": [ "--------------------------------------------------------------------------------------------", "Copyright (c) Microsoft Corporation. All rights reserved.", "Licensed under the MIT License. See License.txt in the project root for license information.", "--------------------------------------------------------------------------------------------", "Do not edit this file. It is machine generated." ], "version": "1.0.0", "contents": { "vs/base/browser/ui/dialog/dialog": { "dialogClose": "Cerrar cuadro de diálogo", "dialogErrorMessage": "Error", "dialogInfoMessage": "Información", "dialogPendingMessage": "En curso", "dialogWarningMessage": "Advertencia", "ok": "Aceptar" }, "vs/base/browser/ui/dropdown/dropdownActionViewItem": { "moreActions": "Más Acciones..." } } }

要点：

• contents键按源码模块路径（module id）组织，如vs/base/browser/ui/dialog/dialog、vs/base/browser/ui/button/button，其键名对应源码中localize()调用的 key，值即西班牙语译文；
• 文件头部的""数组是版权与机器生成声明，正文由工具生成，编辑会被覆盖；
• 该文件达 1.5 万余行，覆盖整个核心 UI 的字符串；translations/extensions/下则按扩展 id 存放各扩展的独立翻译文件（如Microsoft.mssql.i18n.json、vscode.sql.i18n.json）。

由此可以理解快速上手文档中“download translation files to the foldertranslations, as well as populate atranslationsproperty”这句话的完整含义：同步脚本既写入了翻译内容文件，又反向更新了package.json中localizations[].translations清单，使声明与实际文件始终保持一致。

四、翻译同步工作流：从 Transifex 拉取最新字符串

这是快速上手文档的核心实操章节，原文给出的完整流程如下（以下命令必须逐字执行）：

前置准备

1. 检出 VS Code 仓库的master分支（即 Microsoft/vscode 主分支）；
   • 推荐将 VS Code 仓库放在语言包扩展的同级目录（二者拥有相同的父目录），这样后续命令可以少传一个参数；
   • cd vscode后运行yarn初始化 VS Code 仓库（安装依赖）。
2. 获取 Transifex API Token：登录 Transifex 后到https://www.transifex.com/user/settings/api生成；
3. 将 Token 写入环境变量：

export TRANSIFEX_API_TOKEN=<你的Token>

执行同步

进入 VS Code 仓库目录后，按语言包扩展的位置分两种情况：

# 情况 A：语言包扩展与 VS Code 仓库同级（推荐布局） cd vscode npm run update-localization-extension es # 情况 B：语言包扩展在其他位置 cd vscode npm run update-localization-extension {path_to_lang_pack_ext}

其中es即西班牙语的 Transifex 语言代码；其他语言包换用对应代码即可（如zh-hans、ja、de等）。命令执行后会自动完成两件事：

• 将最新翻译文件下载到translations目录；
• 同时更新package.json中localizations贡献点内的translations属性（即上节所述的条目清单）。

与仓库现状的印证

在 i18n/ads-language-pack-es/package.json 的scripts中，官方为这个流程封装了快捷命令：

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

即：在语言包扩展目录下直接运行npm run update，即可自动cd到同级vscode目录并执行update-localization-extension es——前提正是“VS Code 仓库与语言包扩展同级”的推荐布局。这条脚本与快速上手文档描述的步骤完全对应，是文档流程在真实仓库中的落地实现。

说明：该流程依赖外部 VS Code 仓库与 Transifex 平台，属于语言包维护者的发布期操作；作为读者，理解其“脚本下载翻译 + 更新贡献点清单”的机制即可，日常使用语言包并不需要执行这些命令。

五、安装后的使用：Configure Display Language 切换界面语言

语言包安装到 Azure Data Studio 后，用户即可切换显示语言。此处的使用入口是Configure Display Language命令，快速上手文档（及双语 README.md）给出的操作路径为：

1. 按下Ctrl+Shift+P打开命令面板；
2. 输入display过滤出Configure Display Language命令；
3. 按下Enter，弹出已安装语言（按 locale 分组）的列表，当前语言高亮显示；
4. 选择另一个locale即可切换 UI 语言。

这一交互在源码中的实现位于 src/vs/workbench/contrib/localization/common/localizationsActions.ts：

• 命令 id 为workbench.action.configureLocale，标签即"Configure Display Language"，注册于命令面板菜单（MenuId.CommandPalette）；
• 运行时会调用languagePackService.getInstalledLanguages()获取已安装语言，并异步获取getAvailableLanguages()的可用语言，在 Quick Pick 中以Installed / Available两个分组（separator）呈现——这正是“列表显示已安装语言、当前 locale 高亮”的代码来源；
• 用户确认选择后通过localeService.setLocale(selectedLanguage)完成切换。

同时该文件还注册了ClearDisplayLanguageAction（清空显示语言，回退默认）。这两条命令均由 localization.contribution.ts 中的BaseLocalizationWorkbenchContribution在LifecyclePhase.Eventually阶段注册，桌面端与 Web 端分别通过 electron-sandbox/localization.contribution.ts 和 browser/localization.contribution.ts 挂载。

六、版本节奏与多语言生态

语言包的发布与 Azure Data Studio 版本严格对齐。从 CHANGELOG.md 可见完整发布序列：

May 13, 2024 - Release for Azure Data Studio 1.49 February 23, 2024 - Release for Azure Data Studio 1.48 October 31, 2023 - Release for Azure Data Studio 1.47 September 14, 2023 - Release for Azure Data Studio 1.46 July 10, 2023 - Release for Azure Data Studio 1.45 May 8, 2023 - Release for Azure Data Studio 1.44 March 30, 2023 - Release for Azure Data Studio 1.43 March 6, 2023 - Release for Azure Data Studio 1.42 January 13, 2023 - Release for Azure Data Studio 1.41 November 16, 2022 - Patch for 1.40 release November 9, 2022 - Release for Azure Data Studio 1.40 ...

即每个 ADS 主版本发布后，西班牙语语言包随即发布对应版本，偶尔还会针对个别版本发布补丁（如 1.40 的 Patch）。

西班牙语包并非孤例。仓库 i18n 目录下还并列存放了ads-language-pack-de、ads-language-pack-fr、ads-language-pack-it、ads-language-pack-ja、ads-language-pack-ko、ads-language-pack-pt-BR、ads-language-pack-ru、ads-language-pack-zh-hans、ads-language-pack-zh-hant等语言包，目录结构与ads-language-pack-es完全同构（均为package.json+translations/+CHANGELOG.md）。因此，本文阐述的贡献点协议与同步流程对所有官方语言包通用——只需替换 Transifex 语言代码即可。

七、维护、贡献与许可说明

西班牙语语言包的翻译质量维护遵循“社区驱动”模式（README 中表述为"By the community, for the community"）：

• 翻译字符串托管在Microsoft Localization Platform（微软本地化平台）上，只能在平台上修改，再导出到 vscode-loc 仓库，因此不接收 pull request；
• 翻译改进反馈请在 vscode-loc 仓库提交 Issue；
• 源码与字符串遵循仓库根目录 LICENSE.txt 中的许可条款。

快速上手文档本身即面向“语言包扩展的维护者/贡献者”，而使用侧的用户只需关心第五节的语言切换操作——二者共同构成了语言包从“生产”到“消费”的完整闭环。

总结

通过本文，你可以把 Azure Data Studio 语言包扩展理解为一个“声明 + 数据”的极简结构：package.json用localizations贡献点声明语言身份（languageId/languageName/localizedLanguageName）与翻译文件清单（translations），translations/目录存放按模块路径组织的翻译 JSON；维护期通过TRANSIFEX_API_TOKEN环境变量与npm run update-localization-extension es（或语言包内封装的npm run update）从 Transifex 拉取最新字符串并回写贡献点；运行期则由编辑器的 localization 基础设施注册Configure Display Language命令，让用户在已安装的 locale 之间一键切换。

延伸阅读（仓库内线索）

• 语言包清单声明：i18n/ads-language-pack-es/package.json
• 翻译文件示例：i18n/ads-language-pack-es/translations/main.i18n.json
• 扩展点 schema 与校验：src/vs/workbench/contrib/localization/common/localization.contribution.ts
• 语言切换命令实现：src/vs/workbench/contrib/localization/common/localizationsActions.ts
• 版本发布记录：i18n/ads-language-pack-es/CHANGELOG.md
• 其他官方语言包：i18n 目录下ads-language-pack-*系列

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