Internationalization

Translating docs is expensive. Professional translators bill ~$0.10-0.20 per word. A 20,000-word docs site hits $2,000-4,000 per language per major revision. Multiply by quarterly updates × 5 target languages and the budget runs deep into six figures. This is why most docs sites ship English-only for years.

But docs-in-your-native-language drives conversion rates dramatically — non-English speakers are 3-5× more likely to adopt a product when docs are in their language. Strategy matters: translate the right things in the right order, not everything at once.

This guide is about what to translate, when, and how — before you burn the budget on the wrong pages.

When to internationalize (and when not to)

The realistic priority order

Don't translate everything. Translate the highest-impact pages first:

Most teams stop at step 2 or 3 — 15-25 translated pages cover 80% of user value.

NookDocs's internationalization model

NookDocs supports language-aware navigation via the languages config key. Each language gets its own URL prefix and its own page tree:

{
  "languages": [
    { "language": "en", "default": true, "label": "English" },
    { "language": "fr", "label": "Français" },
    { "language": "ja", "label": "日本語" }
  ]
}

Page structure:

docs/
  introduction.mdx        ← default English
  fr/
    introduction.mdx      ← French
  ja/
    introduction.mdx      ← Japanese

URLs:

docs.acme.com/introduction        (en, default)
docs.acme.com/fr/introduction     (fr)
docs.acme.com/ja/introduction     (ja)

Language switcher appears near the logo. Reader selects their language; sidebar updates to show that language's pages; search scopes to the selected language. See localization config for the full mechanics.

Translation workflow — three approaches

Approach 1: Full professional translation (highest quality, highest cost)

• Engage a vendor (Lokalise, Phrase, Crowdin) or direct translators.

• Per-page MDX files sent for translation. Component tags + URL anchors preserved; prose translated.

• Review cycle: translator draft → your native-speaker reviewer (ideally an employee in the market) → publish.

• Cost: $0.10-0.25/word. 20k-word site ≈ $2-5k per language per full translation.

Best for: customer-facing help center content, billing pages, legal text.

Approach 2: Translation memory + hybrid (balanced)

• First pass via professional translation for the top 20 pages.

• Subsequent updates (minor edits, new pages) use a translation memory (TM) tool — the tool proposes translations based on prior approved ones + MT for new content.

• Human reviewer on each proposal before merge.

Best for: mature docs that stabilise + get minor updates.

Approach 3: Machine translation (lowest quality, near-zero cost)

• Google Translate / DeepL API for bulk generation.

• Optional: lightweight human proofread.

• Usually lands at 70-85% quality for simple prose; worse for technical docs with terminology.

Best for: explanation / concept pages where approximate-correctness is OK. NEVER for security / billing / legal content where a mistranslation is dangerous.

Handling terminology

Technical docs have product-specific terms that shouldn't be translated:

• Brand names: "Acme" stays "Acme" in every language.

• API field names: customer_id stays customer_id.

• Feature names: "Smart routing" might stay "Smart routing" or get a localised name — decide upfront, apply consistently.

• Code examples: Don't translate variable names, comments, or strings in code.

Build a glossary early. Share with all translators. Update when product naming changes.

Example glossary entry:

- en: "API key"
  fr: "clé API"       # translated, lowercase kept
  de: "API-Schlüssel" # hyphenated per German convention
  ja: "APIキー"       # katakana for "API"

- en: "workspace"
  fr: "workspace"     # kept English — used as feature name
  de: "Workspace"     # kept English, German capitalisation rule
  ja: "ワークスペース" # transliterated

Decide per term whether to translate or keep English. Write both down.

RTL (right-to-left) languages

Arabic, Hebrew, Persian, Urdu require RTL layout. CSS logical properties handle most of it:

• Use margin-inline-start not margin-left throughout your theme tokens.

• <html dir="rtl"> set automatically by NookDocs for RTL language codes.

• Directional icons — chevron-right becomes chevron-left in RTL. Use CSS transform: scaleX(-1) or swap icons per direction.

• Test visually — RTL mode reveals layout issues you don't see in LTR. Budget an extra 20% engineering time for the first RTL language.

Our theme tokens ship with RTL-safe defaults. If you override theme tokens and use margin-left / padding-left, you'll break RTL layouts.

Code examples in translated docs

Preserve code blocks exactly. Translate prose around them. The prose should reference code elements by their English identifier:

Appelez `POST /api/payments` avec les champs suivants :

- `amount` : montant en cents
- `currency` : code ISO 4217 (`usd`, `eur`, `gbp`)
- `customer_id` : ID du client

La réponse contient :
```json
{
  "id": "pay_abc123",
  "status": "succeeded",
  "amount": 1000
}

The code is the code. Field names don't translate. Prose describes them in French.

## Search in multiple languages

Each language needs its own search index:

- **Postgres FTS** (what NookDocs ships) — supports multiple language configs (`english`, `french`, `german`, etc.) per index. Query uses the language-matching config.
- **Result ranking** scoped per language — a French reader searching "paiement" gets French results; the English "payments" page doesn't surface.

Language-specific tokenisation matters — French accents, German compound words, Japanese morpheme segmentation all work differently. The tokeniser choice affects search quality more than many other factors.

## When you MUST translate for legal reasons

Some regulations require docs in specific languages:

- **EU**: consumer-facing pricing + T&Cs need local language per market.
- **Japan**: financial / healthcare SaaS often requires Japanese docs.
- **France**: Toubon Law requires French docs for consumer-facing content.
- **Accessibility (WCAG)**: docs in the user's declared language, not just English.

These drive "translate or don't sell" decisions. Consult legal before assuming you can ship English-only.

## Measuring translation ROI

- **Conversion rate by language** — if French visitors signed up at 3% before translation, do they sign up at 5% after? Ship translations in waves + measure the delta.
- **Time-to-first-success by language** — cheaper than professional translation is asking "does the translation help real users complete tasks faster?"
- **Support ticket volume in target language** — if French-speaking users previously opened tickets in English (with awkward translations) and now open in French — that's adoption.
- **Churn by language cohort** — best leading indicator. Churn typically higher for non-English users pre-translation; watch for convergence.

If after 6 months the metrics haven't moved, reconsider the investment.

## The honest cost breakdown

For a typical 20,000-word dev docs site, per language, per year:

| Cost category | Amount |
|---|---|
| Initial translation (top 25 pages, 10k words) | $1,500-3,000 |
| Quarterly update translation (20% churn) | $400-800 × 4 = $1,600-3,200 |
| Internal reviewer time (5-10 hr/quarter) | Varies |
| Translation tool subscription | $0-1,200/year |
| Locale-specific QA (layout testing, RTL testing) | 5-20 hr/quarter eng time |
| **Total year 1** | **$4,000-12,000 per language + eng time** |

Multiply by number of languages. Budget accordingly.

## Common internationalization mistakes

<AccordionGroup>
  <Accordion title="Launching i18n before product-market fit">
    Translating your docs for a market you don't serve yet. Market changes, translations age, burn rate grows. Translate AFTER adoption signal, not before.
  </Accordion>
  <Accordion title="Machine-translating everything">
    Google Translate on 100 pages of docs. Native speakers spot errors within seconds. Trust erodes. Use MT only for approximate reference; professional for customer-facing.
  </Accordion>
  <Accordion title="Translating explanation pages before help-center pages">
    Explanations are philosophical ("why we designed X"); help-center pages are functional ("how to cancel"). Functional content has higher ROI per translated word.
  </Accordion>
  <Accordion title="Not handling terminology consistently">
    "API key" translated three different ways on different pages. Readers get confused; search breaks. Build the glossary first, enforce on every page.
  </Accordion>
  <Accordion title="Launching translations without a maintenance plan">
    Translations ship, then never update. Six months later they're wrong. Commit to the quarterly update cycle before translating, not after.
  </Accordion>
  <Accordion title="Skipping RTL visual QA">
    Arabic docs launch. Navigation is backwards, icons point the wrong way, margins collapse. Budget QA time — you can't eyeball RTL unless you speak Arabic.
  </Accordion>
</AccordionGroup>

## Related

- [Localization config](/content/localization) — the `languages` config + URL structure
- [Help center](/guides/help-center) — why translate help center before dev docs
- [Maintenance](/guides/maintenance) — freshness applies per-language
- [SEO for docs](/guides/seo) — localised SEO signals
- [Accessibility](/guides/accessibility) — language declaration + RTL support