我们为什么要开发 Localizeflow
Updated: 11/28/2025 · 4 min read
技术文档不仅仅需要翻译。它需要一个自动化流程，能够在不同语言之间保持结构、上下文和一致性。
技术文档是一个活系统
技术文档随着产品不断发展而持续演进。
每次功能新增、更新或 API 变更都需要同步更新文档，这些更新必须反映到所有语言版本，而不仅仅是原始源语言。
翻译文本是容易的部分。
保持翻译版本始终一致并最新才是真正的挑战。
在实际操作中，维护多语言文档引入了一系列持续不断的工作：
- 跟踪哪些页面发生了变化
- 识别哪些章节需要重新翻译
- 确保代码块、HTML、frontmatter 和格式保持完整
- 准备干净的 PR 以供审查
- 管理越来越复杂的目录结构
文档越多，这种运营负担就越沉重。
在管理了几个文档项目后，我得出了一个不可忽视的结论：
文档的维护比翻译更难。
FastAPI 让这个问题被所有人看到
2025 年，FastAPI 团队宣布将停止依赖社区驱动的翻译 PR，而转向内部自动化流水线。
这说明了问题的严重性。
这个问题并不仅限于某个大型开源项目，而是所有维护多语言文档的团队普遍面临的挑战。
大项目可以负担内部系统的建设。
但大部分团队、小规模开源维护者以及初创公司则无力承担。
Localizeflow 是为了解决这种现实而诞生的。
我们需要一个流水线，而非另一个翻译工具
Localizeflow 从未打算成为一个简单的翻译器。
我们要的是一个系统，能够让每一步由文档更新触发，自动在 GitHub 内完成：
- 更新文档，仅重新生成所需的语言版本
- 保持 Markdown 结构不变
- 代码、HTML 和 frontmatter 保持完整
- 扫描图片并翻译其中内容
- 结果以干净的 PR 形式出现，准备好审核
只需安装一个 GitHub App。
无需自定义脚本。
无需手动管理目录。
这是一个完整的流水线，当文档变更时自动激活。
为什么我们在文档结构层面重新生成
大多数翻译工具按句子级别操作。
技术文档不是单纯的句子列表，而是由 Markdown、元数据、代码示例、图表和模板结构化组合而成。
Localizeflow 在文档结构层级评估变更，并据此重新生成输出。
虽然有时差异会更大，但带来的好处十分明显：
- 术语一致
- 上下文保留
- 稳定的文档结构
在多个真实项目中，这种方法证明更可靠。
构建于 Co-op Translator 引擎之上
Localizeflow 由 Co-op Translator 引擎驱动。
该系统是在超过一年时间内翻译和维护真实 GitHub 文档的过程中开发出来的。
它不是 API 的简单封装。
而是经过生产环境验证的引擎，目前被微软多个开源文档流水线采用。
它包括：
- 强大的 Markdown 解析
- 代码、HTML 和 frontmatter 的完整保留
- Mermaid 图表翻译
- 图片文字提取与翻译
- 术语和上下文一致性功能
这些功能都是基于实际文档工作流需求构建的。
随着 Astro、Hugo 和 Docusaurus 等文档引擎的广泛应用，内容体量和复杂性持续增长。
保持文档更新已成为产品的一大优势。
Localizeflow 的存在是因为这种需求已变得根本。
技术领域语言仍是障碍
运营 Co-op Translator 揭示了一个明显的事实。
许多开发者仍无法以自己的语言获得高质量文档。
文档是产品的一部分。
如果信息传达迟缓或难以获取，学习效率降低，反馈环路变长，产品采纳率下降。
Localizeflow 的使命很简单：
没有团队应该被迫自己搭建翻译系统。
无论是 DevRel、文档团队、SaaS 公司、开源维护者还是早期初创团队，文档更新应当自动更新所有语言，只重新生成必要部分，并产生一个统一的 PR 以供审核。
Localizeflow 旨在消除断点
大多数团队最终都会放弃维护多语言文档。
随着文档增长和更新频率增加，翻译很快就会落后。
Localizeflow 致力于消除这一断点。
它不仅仅让翻译更简单，
更让翻译文档的维护变得可持续。