Localizing documentation: when (and how) to translate your docs

Your docs get 40% of their traffic from Brazil, Japan, and Germany, and every one of those visitors is reading English pages, bouncing off jargon they half-understand, and opening a support ticket instead of self-serving. That’s the actual signal. “We have EU customers” is not — plenty of EU customers read English documentation just fine and would rather have accurate English than mediocre German.

Localization is expensive to do right and worse than useless to do wrong. A half-translated docs site with stale pages in three languages erodes trust faster than an English-only site ever would. So before anyone opens a translation vendor’s pricing page, it’s worth being precise about when localization actually pays for itself, and how to structure it so it doesn’t become a second documentation project you now have to maintain forever.

The signal that tells you it’s time to localize

“We have customers in the EU” is a market fact, not a localization trigger. Most developers in Germany, the Netherlands, and the Nordics read English technical documentation daily — it’s the lingua franca of software. Translating your docs into German for that audience is a nice-to-have, not a retention lever. Watch for signals that actually correlate with churn and support cost instead:

1. Support ticket language mismatches. Your support queue has a growing share of tickets in non-English languages, or tickets where the customer clearly misunderstood an English-only doc page (wrong parameter, wrong endpoint, a concept confused with a similar one). This is the strongest signal — it means people are already trying to use the docs and failing.
2. A sales or CS requirement, not a marketing wish. A deal is stuck because procurement requires documentation in the local language, or an enterprise contract has a documentation-language clause. This is a hard requirement with a revenue number attached, which makes the localization ROI calculation trivial.
3. Self-serve funnel drop-off concentrated by geography. If your product analytics show signup-to-activation conversion is meaningfully lower for traffic from non-English-speaking regions, and onboarding is doc-driven, that’s a usage signal, not a vanity metric.
4. Regulatory or compliance requirement. Some markets (parts of the EU, Quebec, some government procurement) have language requirements for product documentation. This isn’t a judgment call — it’s a checkbox you either need or don’t.
5. A market you’re actively expanding into, not one that showed up organically. If you’re opening a Tokyo office and hiring local sales reps, your docs should be ready before the first prospect asks for them, not six months after.

Notice what’s missing from this list: raw traffic-by-country numbers with no other context, a single enterprise prospect asking “do you have docs in French,” or a general sense that “we should be more global.” Those are worth logging, not acting on. The mistake most teams make is treating localization as a checkbox for international credibility. It’s an investment with an ongoing carrying cost — every language you add is a page you now have to keep in sync forever — so the bar for starting should be a real, measurable signal, not a vibe.

Machine translation vs. professional review — where each one is good enough

The honest answer is: it depends on what the page is for, not on some universal quality bar. Treat this as a spectrum, not a binary choice.

Machine translation alone is good enough for:

• High-volume, low-stakes reference content — API parameter tables, changelogs, auto-generated SDK docs. The cost of a slightly awkward translation is low, and the cost of manually translating hundreds of parameter descriptions is high.
• Content with a short shelf life — release notes, temporary migration notices, anything that will be superseded in weeks.
• Internal or beta-stage docs where the audience already tolerates rough edges in exchange for existing at all.

Machine translation needs professional review for:

• Conceptual and onboarding content — the pages that form a new user’s first impression. A slightly wrong nuance in a “getting started” guide compounds into real confusion three steps later.
• Anything with legal, security, or compliance implications — auth flows, data-handling descriptions, terms embedded in docs. Machine translation can silently invert a negation or soften a warning, and nobody catches it until it matters.
• Marketing-adjacent doc pages — landing-page-style docs, pricing explanations, anything a prospect reads before they trust you. Tone matters here in a way it doesn’t for a parameter table.
• Idiom-heavy source content. If your English docs lean on developer slang, humor, or cultural references, machine translation degrades badly. (This is also a good argument for writing plainer source English in the first place — it translates better and reads better.)

A workable default: run everything through machine translation first as a baseline, then route a defined subset — top 20 pages by traffic, anything in the getting-started flow, anything with legal weight — through a human reviewer who’s a native speaker and ideally also technical. Don’t pay for professional translation on pages nobody reads; don’t ship raw machine translation on the page that decides whether a trial converts.

❌ Bad approach: Hire a translation agency to professionally translate all 400 pages of your docs before launch, because “quality matters.” Eight weeks and a five-figure invoice later, 350 of those pages get single-digit monthly views, and by the time the project ships, a third of the source pages have already changed underneath the translation.

✅ Good approach: Machine-translate everything on day one so nothing is a 404 in the target language. Identify the 15–20 pages that account for 80% of traffic and support tickets, and send only those to a professional reviewer. Re-run the machine translation pass automatically on every source update; re-review the human-reviewed subset only when the diff is substantial.

Structuring docs so translation doesn’t break every release

The most common failure mode isn’t bad translation — it’s a docs structure that makes translation a manual, error-prone chore every time you ship. If your locale strategy is “duplicate the folder and hope someone remembers to update both,” it will fall over within two releases.

Structure your content so that a locale is a layer on top of the source, not a parallel copy of it:

docs/
├── en/
│   ├── getting-started.mdx
│   ├── api/
│   │   ├── authentication.mdx
│   │   └── webhooks.mdx
│   └── guides/
│       └── migrations.mdx
├── de/
│   ├── getting-started.mdx
│   ├── api/
│   │   ├── authentication.mdx
│   │   └── webhooks.mdx        # missing = falls back to en/
│   └── guides/
│       └── migrations.mdx      # stale = flagged by sourceHash mismatch
└── ja/
    ├── getting-started.mdx
    └── api/
        └── authentication.mdx

Every translated file mirrors the exact path of its English source, so tooling can pair them up by convention instead of a manually maintained mapping file. Two things make this survive real release cycles:

1. A source hash in the translated file’s frontmatter. Every translated page records which version of the English source it was translated from. When the source changes, the hash mismatches and the page gets flagged as stale — automatically, not by someone remembering to check.

---
title: 'Authentication'
lang: 'de'
sourcePath: 'en/api/authentication.mdx'
sourceHash: 'a3f9c21'
translatedAt: '2026-04-02'
status: 'stale'
---

2. A fallback rule, not a broken link. If a locale doesn’t have a translated version of a page yet, the site serves the English version rather than a 404 or an empty page. This turns “we haven’t translated this yet” from a bug into an expected, visible state — most doc frameworks (Docusaurus, Fumadocs, Nextra) support this natively if you set the locale fallback correctly.

The underlying principle is: translation should never require restructuring content. If adding German means your writers have to change how they organize English docs — different heading levels, different file splits, different embedded components — you’ve coupled two things that should be independent, and every future edit pays that tax.

Keeping translated docs in sync with source updates

This is the part that actually kills localization programs, and it’s rarely the initial translation cost. It’s the fact that documentation isn’t static — it changes every time the product changes — and now every change has to propagate to N languages instead of one.

The naive workflow looks like this: an engineer updates the English docs in a PR, it merges, and… nothing happens to the other four languages. Three months later someone notices the Japanese docs still describe the old rate-limit values, and by then there are eleven other silently stale pages behind it. This is the same rotting problem every unsynced doc set has, multiplied by however many locales you support.

The fix has the same shape as keeping any docs in sync with a fast-moving codebase — you need a system that notices the diff and acts on it, rather than relying on someone to remember. Concretely:

• Diff-aware retranslation. When a source page changes, don’t retranslate the whole page — diff it, translate only the changed sections, and preserve the human-reviewed parts that didn’t move. This keeps machine-translation costs low and avoids re-review fatigue on pages where 95% of the content is unchanged.
• Staleness as a visible, tracked state, not a silent failure. The status: 'stale' field in the frontmatter example above should drive a dashboard, not just sit in a file nobody opens.
• A review queue per language, not a single global backlog. A German reviewer doesn’t need to see the Japanese queue, and vice versa — route staleness notifications to whoever owns that locale.
• A defined tolerance window. Not every locale needs to be updated the instant the English source changes. High-traffic pages might need same-week turnaround; low-traffic reference pages can tolerate a monthly batch.

This is precisely the problem GitDoc is built to solve on the English side — watching the repo, diffing what changed, and turning that into a reviewable pending update instead of a task someone has to remember. The same structural logic extends to localization: the trigger that should kick off a re-translation is the same commit-level diff that triggers an English docs update, not a separate manual audit six weeks later.

What to localize first — support-heavy pages, not everything at once

Once you’ve decided localization is warranted, the instinct is to translate the whole docs site in one project so nothing looks unfinished. Resist it. A full-site translation is slow to ship, expensive to keep current, and spreads your review budget across pages nobody reads in that language.

Prioritize by where the pain actually is, using the same signals that told you to localize in the first place:

1. Pages tied to your highest-volume support tickets. If “why is my webhook signature invalid” generates 30 tickets a month from Japanese-speaking users, that page goes first — full stop, ahead of anything else on the list.
2. The onboarding path. Getting-started, first API call, authentication setup. This is where a confused non-native reader is most likely to give up rather than push through, because they haven’t built trust in the product yet.
3. Error messages and troubleshooting guides. These are read at the moment of maximum frustration; a clear translation here has outsized impact on support load relative to its size.
4. High-traffic reference pages for the specific endpoints or features that market actually uses — not the full API reference, just the 20% that gets 80% of the calls from that region.
5. Everything else, translated opportunistically or left in English with a visible, honest fallback.

❌ Bad approach: Translate the entire docs site alphabetically, starting with accessibility.mdx and advanced-configuration.mdx, because that’s the order the files appear in the sidebar. Three weeks in, the highest-traffic authentication page still isn’t translated, but seven pages almost nobody reads are done.

✅ Good approach: Pull the last 90 days of support tickets and page analytics, rank pages by ticket volume and traffic from the target locale, and translate the top 15 first. Ship those, measure whether ticket volume from that region drops, then expand the list based on what’s actually being read.

Localization done well looks boring from the outside — pages just happen to be accurate in the reader’s language, updates just happen to keep pace with the English source, and nobody notices the machinery underneath. That’s the goal: not a translation project with a launch date, but another layer of docs that stays synchronized the same way your English docs should. GitDoc keeps your docs in sync with your codebase on every push — start with the English source getting this right, and the localization layer becomes a lot easier to keep honest.

GitDoc keeps your docs in sync with your codebase on every push. Start free →