Recipe

Translate docs to N languages

Ship localized documentation that stays in sync with your English source. Pick your target languages, run the pipeline, and automate the whole thing with CI.

~15 minintermediatei18n

Target languages

Select the languages you want to translate into. Count: 4

Pipeline steps

1

Export source docs

Pull your English docs from the CMS or repo. Flatten to one JSON file per doc page with keys: slug, title, body_md, frontmatter. Store in docs/en/.

2

Choose target languages

Pick N languages from the grid below. Each language gets its own directory: docs/es/, docs/fr/, etc. Mirror the English file structure exactly.

3

Run translation pipeline

Pipe each English JSON through DeepL or OpenAI batch API. Preserve markdown formatting, code fences, and frontmatter. Validate output with a JSON schema check.

4

Review & QA

Spot-check 10% of translated pages per language. Run a link checker to ensure internal doc links resolve. Flag untranslated segments with a <!-- TODO:i18n --> comment.

5

Wire up locale routing

Use Next.js middleware to detect Accept-Language header. Rewrite /docs/* to /docs/{locale}/*. Fall back to English when a translation is missing. Add a language switcher in the docs sidebar.

6

Sync & automate

Set up a GitHub Action that triggers on pushes to docs/en/. It diffs changed files, queues translation jobs, and opens a PR with the new translations. Merge after CI passes.