Skip to main content

​
Docs languages and translations

This documentation site ships in six languages — English (the source corpus), Turkish, Arabic, German, French, and Spanish. Read this page when you want to know which pages exist in your language today, what you get when a page has no translated variant yet, and how the rollout to full coverage proceeds.

​
Coverage matrix

Eight pages have a native variant in every locale. All eight are the pages a new tenant reads before their first compliant send — the onboarding anchors, the launch gate, the compliance posture, first-channel setup, the two-way message flow quickstart, and the delivery state machine. Beyond the always-everywhere matrix, three Reference entries and the troubleshooting runbooks carry a partial variant — a locale variant exists only where a translation has shipped, and the rest follow the fallback-note convention below: The glossary is the one Reference page whose variant differs per locale: Turkish ships a fully native A–Z glossary; Arabic, German, French, and Spanish ship the fallback-note convention — a localized language note at the top of the file, then the complete reviewed English body underneath. What those variants never ship is a pointer-only stub: a page that lists a letter index and links away to /reference/glossary while carrying no definitions is a THIN page, and the fallback decision must be stated at the top of the file, not implied by an empty body. Every other page — endpoint references, channel guides, compliance matrices, SDK docs, concepts — renders its English version in all locales. Nothing is machine-translated on the fly, and no page is silently hidden per locale: you always see the complete corpus.

​
How locale switching works

The docs site declares its locales in one place (docs.json → localization: default en, plus tr, ar, de, fr, es). From that declaration:
  • URL prefix. Each locale lives under its own URL prefix — for example, /tr/quickstart or /es/authentication. The prefix preserves the page path, so switching language never jumps you to a different page.
  • Selector. A language selector in the site header lists the six locales. Picking one rewrites the current page’s URL prefix; you stay on the same page.
  • Right-to-left. Arabic pages render right-to-left — body text, page headings, and navigation chrome all flip direction. Code blocks, endpoint paths, and parameter names stay left-to-right, because those are the literal strings you send in a request.
  • English fallback. A locale variant exists only for pages in the matrices above. When you visit a page with no variant — say, /es/compliance/send-gates — the site serves the English corpus at that locale-prefixed URL. No redirect happens: the URL keeps your chosen prefix, and the page body renders the complete English page inside it. You never hit a blank translation or a 404.
  • Fallback-note convention. Where a locale variant exists as the fallback form, the file carries a localized language note directly under its frontmatter (for German, ## Sprachhinweis), stating that the English body below is the deliberate fallback and that error codes, API paths, and code blocks stay un-translated. The note keeps the fallback LOUD — the documented intent — rather than silent.

​
Why one corpus

The documentation tracks the product API one-to-one — endpoint references, request fields, response shapes, and error codes are written and reviewed in English. Routing pages through per-locale translation before they ship would delay updates and risk mistranslating the exact field names you send in a request, so one correct version ships in English.

​
English-only titles

Page titles (the string the page and search put in front of a reader) are swept for non-Latin scripts, so an English reader never meets e.g. an Arabic phrase embedded mid-sentence on the English corpus. Translated variants retitle in their own language as expected.

​
What is not affected

The product dashboard localises its chrome fully (menus, buttons, labels) and the product changelog is a separate published surface with its own language policy — only this docs site follows the English-corpus rule above.

​
Rollout tracker

Translated coverage widens page-by-page. Each newly translated page becomes available in all six locales at once — a locale never gets a partial subset of the matrix. The product changelog announces each widening, and the matrix above is the live authoritative tracker: it is updated in the same change that ships the translation. If a page you depend on is still English-only, prefer the English source — it is the reviewed, current version.

​
For maintainers

If you edit this docs tree, three rules keep the locales honest:
  1. File layout. The English source lives at the repo root of apps/docs/. Each locale has a mirror-root directory — tr/, ar/, de/, fr/, es/ — whose subpaths match the English path exactly (e.g. tr/guides/go-live-checklist.mdx pairs with guides/go-live-checklist.mdx). A variant file must pair with a real English sibling; unpaired files are rejected.
  2. Bounded variant set. A parity gate (apps/docs/scripts/check-docs-i18n-parity.mjs) holds every locale root to the pages in the matrix above. Add a translated page only by deliberately widening that set, then update the matrix here in the same change.
  3. Navigation points at English. docs.json nav references English page paths only (e.g. quickstart, never tr/quickstart). The locale-prefix rewrite is handled by the site itself — wiring a variant straight into nav is how broken translations reach readers.
The same gate also checks that docs.json declares only the six product locales and that no invariant above is silently violated.