/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Translated documentation

Translated documentation

Publish your docs in more than one language, and give readers a way to switch.

5 min read

Syntext can translate your pages into ten languages and keep the translations in step with the source as it changes. This guide covers the part readers see: the language switcher in the top bar, and the hreflang annotations that let a search engine serve the right language to the right person.

Turn the switcher on

Add an i18n block to syntext.json naming the locales you publish:

json
{
"i18n": {
"defaultLocale": "en",
"locales": ["es", "fr", "de", "ja"]
}
}

That is all you need. Every page now carries a globe control in the top bar listing those languages, and a matching list inside the mobile menu.

Note

The switcher appears only when locales names at least one language other than defaultLocale. A site with no i18n block, an empty list, or a list containing only the default renders exactly as it did before — no control, no extra markup, nothing.

If you already configured the translation add-on

The add-on stores the same information as sourceLocale and targetLocales. In syntext.json write them as defaultLocale and locales:

json
{
"i18n": {
"defaultLocale": "en",
"locales": ["es", "ja"]
}
}

The old spellings still work, but they're deprecated: stx check warns on them and stx migrate renames them.

Renaming the control

The trigger's accessible name is "Language" by default. Set label to change it — in your default language, since that is the language the rest of your chrome is in:

json
{ "i18n": { "defaultLocale": "de", "locales": ["en"], "label": "Sprache" } }

Where translated pages live

Your default locale keeps the URLs it already has. Every other locale is served under a prefix:

Localeguides/installHome
en (default)/guides/install/
es/es/guides/install/es/
ja/ja/guides/install/ja/

Nothing about your existing links changes when you turn translations on, so no inbound link breaks and nothing needs re-crawling.

What the switcher does

•
Each language is named in its own language. Japanese reads 日本語, not "Japanese" — a reader looking for their language is looking for the word they would write. The English name is available as the option's tooltip.
•
The language you are reading is marked, with a check as well as weight, so the state does not depend on colour.
•
Every option is an ordinary link to that language's copy of the page you are on — not the home page.
•
It opens, closes and is keyboard operable without JavaScript. Tab to it, press Enter, Tab through the languages, Escape to close; focus returns to the control it came from.
•
Right-to-left is handled. The menu hangs off the reading edge, and an Arabic option lays out right to left even inside an English menu.
•
It is not printed — it is a control, not content.

On doc engine v2

Sites on doc engine v2 show the switcher as a languages chip in the header, labelled with the language you're reading:

•
Header — next to the version control, in that control's chip style, in header styles that have one. The index, path and simple headers have no version control, so the chip sits in the header's free space instead.
•
Drawer — on phones and tablets it also sits in the menu drawer, beside the version select. On phones the language list opens as a sheet from the bottom of the screen.
•
Same page, or that language's home — each language links to the page you're on in that language. When the page has no translation in a language, that language's entry goes to its home (/ or /es/) instead of a missing page. The #section you're reading is kept.
•
Keyboard — the chip opens with a click, Enter or Space, focus moves to the current language, and Escape closes the list and returns focus to the chip. Unlike the v1 switcher, the v2 menu needs JavaScript.
•
Pages under a locale prefix get that locale as their lang attribute, unless the page sets its own lang.

Search engines

Each page also carries <link rel="alternate" hreflang> for every locale you publish, plus x-default pointing at your default language. That is what tells Google to serve /ja/guides/install to a Japanese reader rather than treating it as a duplicate of the English page.

html
<link rel="alternate" hreflang="en" href="https://docs.example.com/guides/install" />
<link rel="alternate" hreflang="ja" href="https://docs.example.com/ja/guides/install" />
<link rel="alternate" hreflang="x-default" href="https://docs.example.com/guides/install" />

On doc engine v2 the alternates list only the languages the page actually exists in: a language whose entry falls back to its home isn't an alternate of the page, so it's left out. x-default is added when the page exists in your default language, and a page that exists in only one language gets no alternates at all.

The URLs are absolute, built from your custom domain — or, without one, your <slug>-docs.syntext.dev address. Add your custom domain before you rely on them, and redeploy after adding it.

Per-page language

i18n describes the site. A single page can still declare its own language and direction in frontmatter, and the switcher reads that to decide which entry to mark as current:

yaml
---
title: はじめに
lang: ja
---

See Page frontmatter for lang and dir, and syntext.json for the site-wide locale.

Supported languages

Spanish, French, German, Japanese, Chinese (Simplified), Portuguese, Korean, Italian, Dutch and Russian can be translated for you.

Generating translations needs the Pro plan or higher: enabling or configuring the translation add-on, and POST /v1/projects/{projectId}/i18n/translate, both return 402 plan_required (feature: translations) on lower plans. The language switcher, and translations you have already published, keep working on any plan, and you can still read or delete stored translations after a downgrade.

defaultLocale is not limited to those — it is whatever language you write in, including a right-to-left one such as Arabic or Hebrew, and any BCP-47 tag you put in locales will be listed and linked whether or not Syntext generates it.

Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext