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.
on:
push:
branches: [main]
paths:
- "docs/**/*.md"
- "docs/**/*.mdx"
jobs:
sync-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pennypansh-dotcom/gitdocs-sync@v0.1.1
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
The honest tradeoff: this approach assumes your translators (if you have them) are comfortable reviewing a GitHub PR, and it assumes machine translation quality is acceptable for your content — which, for technical docs, it usually is, but for anything where tone and nuance really matter, a platform with human translators in the loop is still the better call.
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.
Top comments (0)