Translated documentation
Publish your docs in more than one language, and give readers a way to switch.
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:
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.
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:
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:
Where translated pages live
Your default locale keeps the URLs it already has. Every other locale is served under a prefix:
| Locale | guides/install | Home |
|---|---|---|
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
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:
index, path and simple headers have no
version control, so the chip sits in the header's free space instead./ or /es/) instead of a missing
page. The #section you're reading is kept.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.
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:
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.