DEV Community: Penny Pan

Docusaurus i18n automation in 2026: comparing the tools for keeping translated docs in sync

Penny Pan — Mon, 03 Aug 2026 03:48:16 +0000

Docusaurus i18n automation in 2026: comparing the tools for keeping translated docs in sync

Docusaurus i18n handles the file structure. It doesn't handle the actual translation work or keep it from drifting out of date. Here's what's out there for that part, and where each one fits.

The problem this is actually about

Docusaurus's i18n setup is solid — the framework handles locale routing and file structure fine. The part nobody's site config solves is what happens six months later: English docs keep changing, the Chinese (or French, or Japanese) translation was done once by a volunteer, and now it's quietly out of date. Nobody notices until someone files an issue that a code sample in the translated version doesn't match anymore.

If your team is small and nobody reads the target language well enough to review a translation PR by eye, this gets worse, not better, over time.

Below is what I found looking at the actual options for docusaurus translation sync — including one I work on, disclosed up front so you can weigh that accordingly.

Docusaurus translation tools compared at a glance

Tool	Type	Pricing	Translation Source	Sync Detection	PR Workflow	Best For
GitDocs Sync	GitHub Action	Free / $19/mo Pro	OpenAI / DeepSeek / BYO key	Diff-based (only changed sections)	Auto PR per language	Teams wanting GitHub-native, set-and-forget
Azure Co-op Translator	Python CLI + Action	Free (Azure subscription required)	Azure OpenAI	Full file re-translation	Manual or CI script	Teams already on Azure
PageTurner	Managed CI/CD	Not public	Proprietary LLM	Full site rebuild	Managed service	Teams wanting hands-off managed solution
docusaurus-i18n	npm CLI	Free (bring OpenAI key)	OpenAI	None (full re-run)	None (local only)	Quick one-off translations
Crowdin	SaaS Platform	From $40/mo	Human + Machine	Per-string versioning	Crowdin UI / API	Large teams with dedicated localization staff

Detailed Breakdown

GitDocs Sync

What it is: A GitHub Action that watches your English docs, detects what changed, translates only the changed sections, and opens a PR per target language.

How it works:

You push an update to website/docs/introduction.md
The Action diffs the change against the last translated version
Only the new/modified paragraphs get translated (using OpenAI, DeepSeek, or your own API key)
A PR opens with [i18n] Update zh-CN: introduction.md
You review and merge — no manual diffing, no full re-translation

Key features:

Translation memory — repeated phrases aren't re-translated
Per-language PRs — merge Chinese updates independently from Japanese
Configurable review flow — require human approval or auto-merge
Works entirely inside GitHub — no external platform

Pricing: Free for public repos. Pro at $19/mo for private repos + priority translation queue.

GitHub: github.com/pennypansh-dotcom/gitdocs-sync

Azure Co-op Translator

What it is: Microsoft's open-source Python package for translating Markdown documentation, powered by Azure AI Services (Azure OpenAI or Azure AI Translator).

How it works:

Install the Python package: pip install co-op-translator
Configure Azure credentials
Run as a CLI command or in CI/CD
Translates entire Markdown files, including images (via Azure AI Vision)

Key features:

Image translation (screenshots, diagrams)
Supports multiple Azure AI backends
Can run as a GitHub Action
MIT licensed, open source

Limitations:

Requires Azure subscription (not free even for open source)
Full-file translation only — no incremental diff
Python-based, not native to Docusaurus/Node.js ecosystem
No built-in PR workflow — you write your own CI script

GitHub: github.com/Azure/co-op-translator — actively maintained by Microsoft (check the repo for current star count and release cadence, both move fast). Worth a look if you're already deep in the Azure ecosystem.

PageTurner

What it is: A managed translation service for open-source documentation. They host translated versions of your docs on their subdomain (e.g., yourproject.page-turner.com/zh-Hans/).

How it works:

They connect to your docs repo
Automatically translate and deploy translated versions
Keep translations in sync via their CI/CD pipeline

Key features:

Fully managed — no setup required
Claims to maintain translations for 87+ projects
Live demo available before commitment

Limitations:

Translations hosted on their domain, not yours — worth checking how that interacts with your existing deploy setup
Pricing and service details aren't publicly documented; you'd need to request a demo to see specifics
No public GitHub repository or self-hosted option, so you can't inspect how translations are generated or run it yourself

Website: page-turner.com

docusaurus-i18n

What it is: A lightweight npm CLI that runs OpenAI translation against your Docusaurus i18n directory.

How it works:

OPENAI_API_KEY=sk-xxxxxx npx docusaurus-i18n

Key features:

Dead simple — one command
Works with your existing Docusaurus i18n setup
Free (you bring your own OpenAI key)

Limitations:

No sync detection — retranslates everything every time
No PR workflow — runs locally, you commit manually
Small project, low star count — check the repo's commit history before depending on it for anything ongoing
No translation memory or incremental updates

GitHub: github.com/moonrailgun/docusaurus-i18n — worth noting it's listed as a community resource on the official Docusaurus i18n docs, which says something about it being a known quantity even at a small scale.

Crowdin

What it is: The enterprise localization platform. Supports Docusaurus via a dedicated integration.

How it works:

Connect your Docusaurus repo to Crowdin
Source strings are extracted and uploaded
Translators work in Crowdin's web UI
Translated content is synced back as a PR

Key features:

Human + machine translation workflows
Translation memory and glossary
Review and approval workflows
Enterprise-grade security and compliance

Limitations:

Pricing starts at $40/mo (free for OSS with approval)
External platform — translators work outside GitHub
Overkill for teams with <100 documentation pages
Docusaurus integration requires configuration

Website: crowdin.com

Which Docusaurus translation tool fits your team

Go with GitDocs Sync if:

You want everything in GitHub — no external platforms
You need incremental translation (only changed content, not full re-runs)
You maintain 2-5 languages with a small team
You want auto-PRs you can review and merge

Go with Azure Co-op Translator if:

You're already on Azure and have credits
You need image translation (screenshots with text)
You're comfortable writing your own CI/CD scripts
You don't need per-language PR separation

Go with Crowdin if:

You have a dedicated localization team
You need human review workflows with multiple translators
Budget isn't a constraint
You're managing 10+ languages across a large organization

Go with docusaurus-i18n if:

You just need a one-time bulk translation
You don't plan to update translations regularly
You're comfortable running CLI commands locally

FAQ

Q: Can I just use Google Translate on my Markdown files?
A: You can, but you'll break Docusaurus's MDX syntax, code blocks, and frontmatter. Documentation-specific tools handle these edge cases.

Q: Do I need Crowdin if Docusaurus already supports i18n?
A: No. Docusaurus's built-in i18n handles the file structure. You only need a translation tool if you want to automate the actual translation work and keep it in sync.

Q: How do I detect which translations are out of date?
A: GitDocs Sync and Co-op Translator both detect changes automatically. For a manual check, compare last-commit dates between your English docs and translated copies. If built-with.md was updated in English 3 months ago but the Chinese version hasn't been touched since 2022, it's out of date.

Q: Can I use my own OpenAI/DeepSeek API key with these tools?
A: GitDocs Sync and docusaurus-i18n support BYO key. Co-op Translator requires Azure. PageTurner uses their own model.

Q: What about VitePress and Nextra?
A: GitDocs Sync currently focuses on Docusaurus (the most widely-used docs framework with built-in i18n). VitePress and Nextra support is on the roadmap.

Disclosure: I work on GitDocs Sync, one of the tools covered above (repo · pricing & docs). Tried to be straight about where it isn't the right fit — Crowdin and Azure Co-op Translator both cover real cases GitDocs Sync doesn't.

Last updated: August 2026 — tools, pricing, and star counts change, so check each project's page for anything current before you decide.

Docusaurus i18n: How to keep translations in sync (manual vs Crowdin vs GitHub Action)

Penny Pan — Tue, 28 Jul 2026 12:37:28 +0000

If you maintain a Docusaurus site in more than one language, you already know the actual problem isn't translation — it's staying in sync. Someone updates three paragraphs in the English docs, and six months later the Chinese (or Spanish, or whatever) version is quietly wrong, and nobody notices until a user files an issue about it.

I went looking at how teams actually solve this, and it mostly comes down to three approaches. Writing this down mostly for my own reference, but sharing in case it saves someone else the research.

Approach 1: Just do it manually

This is what most small-to-mid docs sites do, at least at first. A maintainer (or a translator on Slack) watches for doc PRs and manually updates the other language folders.

It works fine until it doesn't. The failure mode is always the same: it's invisible. Nobody gets paged when a translated page goes stale — it just sits there, slightly wrong, until a reader notices the code sample doesn't match anymore. For a project with a handful of docs and one contributor doing translations, this is honestly fine. Past ~50-100 pages or more than one language, it stops scaling — not because the translation work is hard, but because tracking what changed becomes a full-time job nobody signed up for.

Approach 2: A translation management platform (Crowdin, Lokalise, etc.)

These are built for exactly this problem and they're genuinely good at it — string extraction, translator workflows, in-context editing, the works. If you have a dedicated localization team or professional translators involved, this is probably still the right call.

The tradeoff for a docs-only, engineering-driven project: they're built around the assumption that there's a human translator (or a review pipeline) doing the actual translating, plus a separate sync step to pull translations back into your repo. That's the right tool when translation quality and nuance matter enormously (marketing copy, legal text) or when you have translators who aren't developers and shouldn't be touching YAML or Git directly. For a docs site where the content is mostly technical explanation, code samples, and API reference, it's often more infrastructure than the problem needs — you're paying (in setup complexity, sometimes in dollars) for a workflow built around human translators when what you actually want is "keep the mirror in sync automatically, and let a human review before it ships."

Approach 3: Diff-based translation directly in CI

This is the category we ended up building in (GitDocs Sync, disclosure up front), and the design point is narrow on purpose: only translate what changed, open it as a normal PR, let translation memory handle repeats.

The mechanics, roughly:

A GitHub Action watches your docs/ directory for changes on push
It diffs the Markdown/MDX against what was last translated — untouched paragraphs get skipped entirely, so you're not re-translating (and re-paying for) content that hasn't moved
Front matter, code blocks, links, and HTML tags are left alone; only prose gets sent to the model
It opens a normal pull request with the translated content, so review happens the same way every other doc change gets reviewed
Once merged, the source/translation pair gets stored, so identical strings anywhere else in the repo reuse it instead of hitting the API again

There's also a dry-run mode that just produces an audit — "these pages are missing translations, these are stale" — without spending any translation budget, which is useful for figuring out how big the problem actually is before turning anything on.

Rough comparison

	Manual	Crowdin / TMS	Diff-based Action
Setup time	none	hours–days	~3 min
Who reviews	whoever remembers to	dedicated translators	anyone, via normal PR
Cost model	your time	seats / word volume	per translated doc
Re-translates unchanged content?	no (if you remember)	depends on config	no, by design
Best fit	tiny docs, 1 language	big team, human translators, non-technical content	solo/small teams, technical docs, English + a couple langs

Where this actually falls down

Worth being upfront about this since it's easy to gloss over in anything written by the people who built the tool: diff-based translation is only as good as the underlying model for your target language pair, and for languages with fewer high-quality training resources, you'll want a human pass before you fully trust it. It's also not a fit if your "translation" is really localization — adapting examples, currency, cultural references — rather than a faithful port of the same content into another language. For straight technical docs where the English version is the source of truth and you want the other languages to track it closely, it's a good fit. For a marketing site that needs each locale to feel native, it isn't.

FAQ

Does this replace a translation management platform for large teams?
No — if you have dedicated translators and a formal localization workflow, a TMS is still the right tool. This is for teams that don't have that and just want the docs to stop drifting.

What happens to code blocks and links?
They're left untouched. Only the prose gets sent for translation; Markdown/MDX structure, front matter, and code fences are protected.

Does it re-translate the whole file every time?
No — that's the whole point. Only the changed paragraphs get sent for translation; unchanged content is skipped and translation memory covers repeats.

Disclosure: I work on GitDocs Sync, mentioned above as one of the options. Wrote this comparison to be useful even if you land on a different tool for your situation.