Internationalization

Serve your documentation in more than one language from a single repo. You write each translation as a parallel set of files, add one field to docs.json, and Bloques handles routing, the language switcher, and a fallback for pages you haven't translated yet.

This page is for site owners adding a second language to a published site.

Prerequisites

• A Bloques site that's already deployed. See the Quickstart.
• Familiarity with docs.json. See the docs.json overview.

Supported languages

Two languages are available:

English (en) is the default language and can't be changed. Default-language pages keep their existing URLs, so adding a translation never breaks links you've already shared.

Enable a language

Add a languages array to docs.json, listing the codes your site serves:

{
  "name": "Acme docs",
  "languages": ["en", "es"],
  "navigation": [{ "group": "Get started", "pages": ["introduction"] }]
}

A language switcher appears in the header as soon as languages holds more than one code. A site without a languages field is unaffected.

Add translated content

Default-language content stays at the root of your repo. Each additional language gets a top-level folder named after its code, mirroring the same file paths.

introduction.mdx
guide/setup.mdx

introduction.mdx
guide/setup.mdx
es/introduction.mdx
es/guide/setup.mdx

How language URLs work

The default language is hidden from the URL. Other languages are served under a prefix matching their code.

An English page requested under /en redirects to its canonical, unprefixed URL — /en/guide/setup becomes /guide/setup.

Fallback for untranslated pages

Translations can be partial. When a reader opens a page that isn't translated for the current language, Bloques renders the English content at the same URL instead of a 404.

Language switcher

Once languages is set, the header shows a language switcher. Selecting a language keeps the reader on the same page — it swaps the language prefix in the URL rather than returning to the home page.

Interface language

Built-in interface text translates with the selected language — the search box, the on-this-page table of contents, the previous and next page links, and the theme and language pickers. Translate your own content; Bloques handles the rest of the interface.

Per-language navigation

All languages share the navigation in docs.json by default. To give one language a different sidebar, group labels, or ordering, add a docs.<lang>.json file next to docs.json:

{
  "name": "Documentación de Acme",
  "languages": ["en", "es"],
  "navigation": [{ "group": "Primeros pasos", "pages": ["introduction"] }]
}

Bloques uses docs.es.json when a reader views the site in Spanish and falls back to docs.json when it's absent. Page paths stay repo-relative — Bloques resolves them inside the language folder.

Search and metadata

• The canonical URL reflects the active language: unprefixed for English, /es/... for Spanish on a custom domain.
• Social preview images, the llms.txt endpoint, and search results are generated from your default-language content.

Troubleshooting

A translated page shows English content

The file is missing from the language folder, or its path doesn't match the English page. Confirm es/<path>.mdx exists at the same relative path as the English file.

The language switcher doesn't appear

languages is missing or holds a single code. Add at least two supported codes — for example, ["en", "es"].

A translated page is missing from the sidebar

Expected when the page isn't translated yet. Add the file under the language folder, then push.

Next steps