Electron-i18n 翻译文档同步机制揭秘en-US 源内容如何驱动 7 种语言文档结构精确同步【免费下载链接】i18n The home of Electrons translated documentation项目地址: https://gitcode.com/gh_mirrors/i18n/i18nelectron-i18nElectron 官方文档多语言仓库是整个 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. 逐文件解析 Markdownlib/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.jsonscript/wordcount.ts 统计 en-US 与全语言的总文件数、总词数、平均词数产出 wordcount.md 报表script/readme.ts 根据 locales 清单自动刷新 readme.md 中的语言进度表!-- language-table --标记区块翻译进度一目了然。四、7 种语言进度从哪里来lib/locales.ts 中的逻辑值得细看用locale-code库把de-DE解析为语言名、国家名如德语 → German / Germany对zh-CN、zh-TW等库中缺失或不够精确的词条做手工覆盖如 Simplified Chineseen-US没有 Crowdin 统计它是源语言直接记为 101%最终按翻译进度降序排列谁翻译得最多谁排前面。这套自动扫描 数据覆盖 进度排序的组合让语言清单永远与实际目录内容保持一致新增一种语言只需在 content/ 下加一个目录。五、动手体验快速上手指南 想在本地跑一遍完整同步流程只需三步克隆仓库git clone https://gitcode.com/gh_mirrors/i18n/i18n安装依赖npm install运行同步与构建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 Electrons translated documentation项目地址: https://gitcode.com/gh_mirrors/i18n/i18n创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Electron-i18n 翻译文档同步机制揭秘en-US 源内容如何驱动 7 种语言文档结构精确同步【免费下载链接】i18n The home of Electrons translated documentation项目地址: https://gitcode.com/gh_mirrors/i18n/i18nelectron-i18nElectron 官方文档多语言仓库是整个 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. 逐文件解析 Markdownlib/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.jsonscript/wordcount.ts 统计 en-US 与全语言的总文件数、总词数、平均词数产出 wordcount.md 报表script/readme.ts 根据 locales 清单自动刷新 readme.md 中的语言进度表!-- language-table --标记区块翻译进度一目了然。四、7 种语言进度从哪里来lib/locales.ts 中的逻辑值得细看用locale-code库把de-DE解析为语言名、国家名如德语 → German / Germany对zh-CN、zh-TW等库中缺失或不够精确的词条做手工覆盖如 Simplified Chineseen-US没有 Crowdin 统计它是源语言直接记为 101%最终按翻译进度降序排列谁翻译得最多谁排前面。这套自动扫描 数据覆盖 进度排序的组合让语言清单永远与实际目录内容保持一致新增一种语言只需在 content/ 下加一个目录。五、动手体验快速上手指南 想在本地跑一遍完整同步流程只需三步克隆仓库git clone https://gitcode.com/gh_mirrors/i18n/i18n安装依赖npm install运行同步与构建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 Electrons translated documentation项目地址: https://gitcode.com/gh_mirrors/i18n/i18n创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
