What breaks when you translate technical docs

Translating a marketing page is straightforward. Translating technical documentation is not. The failure modes are specific, predictable, and damaging when they occur.

Here are the five most common ways technical doc translation goes wrong — and what correct output looks like. Every "correct" example below links to a live translated site you can verify yourself.

1. Code gets translated

The most destructive failure. A configuration example like:

{
  "scripts": {
    "test": "jest"
  }
}

gets partially translated — "scripts" becomes "スクリプト", or "test" becomes "tester". The code is now broken. A developer who copies it will get errors with no obvious explanation.

This happens because generic translation tools don't distinguish between code blocks and prose. They see text and translate it.

What correct looks like: Browse the Jest docs in Japanese. Every code block — installation commands, test files, configuration snippets — is preserved character-for-character. The surrounding Japanese text explains what the code does; the code itself is untouched.

2. Inline code references break

Even when code blocks survive, inline code often doesn't. A sentence like:

Use jest.fn() to create a mock function.

might become:

jest.fn() を使用してモック関数を作成します。

in a good translation. But generic tools often produce:

jest.fn（） を使用してモック関数を作成します。

Note the full-width parentheses （） replacing the ASCII (). This is a common CJK translation artifact. The function call is now invalid — copying it will fail silently.

What correct looks like: On the Jest mock functions page in Japanese, every inline code reference uses standard ASCII characters. jest.fn(), mockReturnValue, toHaveBeenCalledWith — all preserved exactly.

3. Terms are inconsistent across pages

"Repository" appears on 15 different pages. A generic tool translates each page independently. The result: "repository" becomes リポジトリ on page 3, レポジトリ on page 7, and 保管庫 on page 12.

Developers learning from translated docs absorb terminology. When the same concept has three different names, comprehension drops and trust erodes.

What correct looks like: Browse Prettier in Japanese across multiple pages. Technical terms translate consistently — the same Japanese word for the same English term, everywhere.

4. Component structure breaks

Modern documentation sites use interactive components: tabbed code examples, collapsible sections, admonition boxes (tips, warnings, notes), and custom React components.

Generic translation tools see the raw markup and either:

• Translate JSX attribute values (title="Warning" → title="Advertencia" — fine in this case, but the tool doesn't know when to stop)
• Break the component structure by translating props that should stay as-is
• Strip components entirely, leaving flat text

What correct looks like: The Jest Getting Started page in Japanese has tabbed installation instructions (npm / Yarn / pnpm / Bun), collapsible details sections, and admonition boxes ("tip", "info"). All render correctly in every language. The tab labels stay as proper nouns; the content inside is translated; the component structure is intact.

5. Navigation stays in English

The most visible failure. The sidebar says "Getting Started", "Configuration", "API Reference" — all in English — while the page content is in Japanese. Or worse, some sidebar items are translated and others aren't.

This happens because navigation labels live in separate configuration files (sidebars.js, docusaurus.config.js), not in the Markdown content. Tools that only translate .md files miss the navigation entirely.

What correct looks like: On any page of the Jest Japanese docs, the entire sidebar is in Japanese: "はじめに", "マッチャーの使い方", "セットアップとティアダウン", "モック関数". Footer links, breadcrumbs, and the top navigation bar are also translated.

Why these failures are predictable

These aren't edge cases. They're the normal output of translation tools that weren't designed for technical documentation. Generic tools work at the sentence level. Technical docs require understanding at the page, site, and component level:

• Code vs. prose boundaries need to be detected, not guessed
• Terminology needs to be enforced across the entire site, not per-page
• Component structure needs to be preserved, not flattened
• Navigation and metadata need to be translated alongside content

Each of these is a solved problem — but only if the translation system is built for it.

See for yourself

Browse any of our 19 live demo translations and check for these five failure modes. Pick a code-heavy page, switch to Japanese or Chinese, and verify:

1. Are code blocks untouched?
2. Are inline code references using ASCII characters?
3. Are terms consistent across pages?
4. Do tabs, admonitions, and interactive components still work?
5. Is the sidebar fully translated?

If you want this level of quality for your own documentation, contact us.