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.
Top comments (0)