Why we built Localizeflow
Updated: 11/28/2025 · 4 min read
Technical documentation requires more than translation. It needs an automated pipeline that preserves structure, context, and consistency across languages.
Technical documentation is a living system
Technical documentation evolves continuously as a product evolves.
Every feature addition, update, or API change requires documentation updates, and those updates must be reflected across all languages, not just the original source.
Translating text is the easy part.
Keeping translated versions consistently up to date is the real challenge.
In practice, maintaining multilingual documentation introduces a constant stream of work:
- tracking which pages changed
- identifying which sections require retranslation
- ensuring code blocks, HTML, frontmatter, and formatting remain intact
- preparing clean PRs for review
- managing increasingly complex directory structures
The more documentation you have, the heavier this operational burden becomes.
After managing several documentation projects myself, one conclusion became impossible to ignore:
Documentation is harder to maintain than to translate.
FastAPI made the problem visible for everyone
In 2025, the FastAPI team announced that they would stop relying on community-driven translation PRs and move to an internal automated pipeline instead.
This was telling.
The problem was not limited to one large open-source project. It reflected a universal issue faced by any team maintaining multilingual documentation.
Big projects can afford to build internal systems.
Most teams, small OSS maintainers, and early-stage startups cannot.
Localizeflow was created to address this reality.
We needed a pipeline, not another translation tool
Localizeflow was never meant to be a simple translator.
What we wanted was a system where every step triggered by a documentation update flows automatically inside GitHub:
- update a document and only the required languages are regenerated
- Markdown structure is preserved
- code, HTML, and frontmatter remain intact
- images are scanned and translated
- results appear as a clean PR ready for review
One GitHub App installation.
No custom scripts.
No manual directory management.
A complete pipeline that activates when documentation changes.
Why we regenerate at the document structure level
Most translation tools operate at the sentence level.
Technical documentation is not a list of sentences. It is a structured combination of Markdown, metadata, code samples, diagrams, and templates.
Localizeflow evaluates changes at the document structure level and regenerates the output accordingly.
The diff may be larger at times, but the benefits are clear:
- consistent terminology
- preserved context
- stable document structure
Across multiple real-world projects, this method proved significantly more reliable.
Built on the Co-op Translator engine
Localizeflow is powered by the Co-op Translator engine.
This system was developed through more than a year of translating and maintaining real GitHub documentation.
It is not a wrapper around an API.
It is a production-tested engine used in several Microsoft open-source documentation pipelines today.
It includes:
- robust Markdown parsing
- preservation of code, HTML, and frontmatter
- Mermaid diagram translation
- image text extraction and translation
- terminology and context consistency features
These capabilities were built because real documentation workflows required them.
As documentation engines such as Astro, Hugo, and Docusaurus spread, content volume and complexity continue to increase.
Keeping documentation updated has become a product advantage.
Localizeflow exists because this need is now fundamental.
Language is still a barrier in tech
Operating Co-op Translator revealed a clear truth.
Many developers still cannot access high-quality documentation in their own language.
Documentation is part of the product.
If information is delayed or difficult to access, learning slows down, feedback loops widen, and product adoption declines.
Localizeflow’s mission is simple:
No team should have to build its own translation system.
Whether it is DevRel, documentation teams, SaaS companies, OSS maintainers, or early-stage startups, a documentation update should automatically update every language, regenerate only the necessary changes, and produce a single PR for review.
Localizeflow exists to remove the breaking point
Most teams eventually give up on maintaining multilingual documentation.
As documentation grows and updates become frequent, translations fall behind quickly.
Localizeflow aims to remove that breaking point.
It does not just make translation easier.
It makes maintaining translated documentation sustainable.