Electron-i18n 翻译文档同步机制揭秘：en-US 源内容如何驱动 7 种语言文档结构精确同步

Electron-i18n 翻译文档同步机制揭秘：en-US 源内容如何驱动 7 种语言文档结构精确同步

【免费下载链接】i18n🌍 The home of Electron's translated documentation项目地址: https://gitcode.com/gh_mirrors/i18n/i18n

🌍electron-i18n（Electron 官方文档多语言仓库）是整个 Electron 文档国际化（i18n）的"大本营"：它把 en-US 英文源文档作为唯一内容源头，自动同步到德语、西班牙语、法语、日语、葡语、俄语、中文等 7 种语言目录，让每种语言的文档结构与英文源文档精确对齐。本文带你用 5 分钟看懂它的核心同步机制。

一、先看目录布局：en-US 是"母版"，其他语言是"影子"

整个仓库的内容全部存放在 content/ 目录下，每种语言一个子目录：

content/ ├── en-US/ ← 源语言（唯一内容源头） │ ├── docs/ │ │ ├── api/ # API 参考（130 个文档） │ │ ├── development/ # 开发指南 │ │ └── tutorial/ # 教程 │ └── website/ # 官网文案、博客 ├── de-DE/ ← 与 en-US 结构完全一致的德语目录 ├── es-ES/ ├── fr-FR/ ├── ja-JP/ ├── pt-BR/ ├── ru-RU/ └── zh-CN/

关键设计：只有 en-US 目录会被脚本直接写入，其余 6 个语言目录的 Markdown 文件只由 Crowdin 翻译平台回传更新。因此每种语言目录的文件树永远与英文母版一一对应——文件名、目录层级、文档数量完全一致（例如每种语言都有 63 个 API 结构文档）。

语言清单由 lib/locales.ts 在构建时动态生成：它扫描 content/ 下的所有子目录，自动识别出全部支持的语言，并从 stats.json 读取各语言的翻译进度，无需手工维护清单。

二、同步引擎：collect 脚本如何拉取最新英文文档

同步的总入口是 script/collect.ts，它完成了四件关键事情：

1. 锁定 Electron 最新稳定版标签

脚本先执行npm show electron version获取 npm 上最新的稳定版本号，再通过 GitHub API 查到对应的 Release 标签，并把它写回 package.json 的electronLatestStableTag字段（当前为 v15.1.1）。这个标签是后续图片链接、API 定义文件的"版本锚点"。

2. 从两个上游分支拉取内容

• API 文档：从 Electron 上游仓库的稳定版标签（如 v15.1.1）拉取api/目录，保证 API 文档与已发布版本严格一致；
• 教程与开发文档：从对应的major-x-y分支拉取，反映最新开发中的内容；
• API 定义：下载 Release 附件中的electron-api.json，存入 content/en-US/electron-api.json。

3. 清理"过期文件"，保持结构一致

这是结构同步的关键一环。脚本遍历所有语言目录下现存的文件（getObsoleteFiles），只要上游已经删除或移动了某个文档，它就会在每一种语言目录中同时删除对应文件，确保 7 种语言的文件树始终与英文源文档的当前结构一致——不会出现某语言残留已废弃文档的"结构漂移"。

4. 只写 en-US，不碰译文

writeContent函数把拉取到的内容统一写入 content/en-US/。翻译工作则交给 crowdin.yml 描述的配置：Crowdin 平台读取 en-US 源文件，分发给翻译者，回传的译文落到对应语言目录。

📌 一句话总结数据流：上游 Electron → collect 脚本 → en-US 母版 → Crowdin → 7 种语言目录。

三、构建流水线：解析、转换、生成

拉取完内容后，构建脚本（见 package.json 的build命令）会走三步：

1. 逐文件解析 Markdown

lib/parsers/docs-parser.ts 对每种语言的每个文档执行：

• 推导分类：从路径{locale}/docs/api/xxx.md中切分出api、tutorial、development等类别（映射表见 lib/constants.ts）；
• 提取元信息：解析出标题（取首个 H1/H2）和描述（取首个引用块）；
• 跳过特殊文档：若文档包含<!-- i18n-ignore -->标记，则跳过翻译统计，避免机器无法翻译的页面拉低进度。

2. 三个 Remark 转换器让链接"跨国可用"

lib/transfomers/ 下的插件是同步质量的守护者：

• remark-relative-links.ts：把文档里的相对链接统一改写成以/docs/...开头的绝对路径——这样中文页里的[API](https://link.gitcode.com/i/c414326bab491762d7445b73c75003b3)不会"串"到英文文档，各语言目录自成闭环；图片链接则自动拼上electronLatestStableTag版本前缀，7 种语言引用同一版本的图片；
• remark-fiddle-urls.ts/remark-plaintext-fix.ts：分别修正示例代码链接、清理纯文本中的格式问题。

3. 生成统计与语言清单

• script/stats.ts 从 Electron 官网的 Crowdin 状态接口拉取各语言翻译进度，落盘到 stats.json；
• script/wordcount.ts 统计 en-US 与全语言的总文件数、总词数、平均词数，产出 wordcount.md 报表；
• script/readme.ts 根据 locales 清单自动刷新 readme.md 中的语言进度表（<!-- language-table -->标记区块），翻译进度一目了然。

四、7 种语言进度从哪里来？

lib/locales.ts 中的逻辑值得细看：

1. 用locale-code库把de-DE解析为语言名、国家名（如德语 → German / Germany）；
2. 对zh-CN、zh-TW等库中缺失或不够精确的词条做手工覆盖（如 Simplified Chinese）；
3. en-US没有 Crowdin 统计（它是源语言），直接记为 101%；
4. 最终按翻译进度降序排列，谁翻译得最多谁排前面。

这套"自动扫描 + 数据覆盖 + 进度排序"的组合，让语言清单永远与实际目录内容保持一致，新增一种语言只需在 content/ 下加一个目录。

五、动手体验：快速上手指南

🚀 想在本地跑一遍完整同步流程？只需三步：

1. 克隆仓库：git clone https://gitcode.com/gh_mirrors/i18n/i18n
2. 安装依赖：npm install
3. 运行同步与构建：npm run collect && npm run build

跑完后你会发现：en-US 目录已更新为最新稳定版内容，过期文档在所有语言目录中被清理，wordcount.md 与 stats.json 也刷新到了最新数字——整个"母版驱动多语言"的机制就在你眼前完整复现了一遍。

六、总结：三个值得学习的 i18n 架构思想

机制	实现位置	解决的问题
单一源语言母版	script/collect.ts	各语言内容永不失真
结构漂移自动清理	getObsoleteFiles	上游删文档，7 语言同步删
相对链接绝对化	lib/transfomers/remark-relative-links.ts	各语言文档互不串线
语言清单自动发现	lib/locales.ts	新增语言零配置

一句话总结：electron-i18n 用"en-US 母版 + collect 同步 + 结构清理 + 链接转换"四件套，实现了 7 种语言文档结构与英文源文档的精确同步——这正是开源项目多语言文档基建的经典范式。

【免费下载链接】i18n🌍 The home of Electron's translated documentation项目地址: https://gitcode.com/gh_mirrors/i18n/i18n