Typemark Documentation

Languages

Publish your docs in several languages, each at its own address, with a language picker for readers. On every plan.

Aktualisiert am 19. Nov. 20268 Min. Lesezeit

Publish your site in more than one language. Each translation is an MDX file next to the page it translates, readers switch languages from the site header, and search engines find every version. Languages are on every plan. On Pro and Enterprise, AI can write the translations into 12 languages and keep them up to date.

Add your languages

In Settings > Languages, the project owner sets the language your pages are written in, then adds the others:

  1. Under Default language, check the code and name of the language your pages are in. A site without languages is in English.
  2. Click Add a language and type its code, such as fr. Typemark fills in its name in that language, which you can change. A code that isn't a real language code is refused.
  3. Under Translated by, choose AI to have AI translate every page (Pro and Enterprise), or Your team to write the translations yourself.
  4. Click Save languages. Typemark saves the list to typemark.json and rebuilds your site.

A saved language's code can't be changed: remove the language and add it again. Removing a language unpublishes its translations, and their files stay in your repository.

Settings writes the languages list in typemark.json, and you can also edit it there, the language your pages are written in first:

"languages": [
  { "code": "en", "name": "English" },
  { "code": "fr", "name": "Français" },
  { "code": "pt-BR", "name": "Português (Brasil)" }
]
KeyWhat it does
codeThe language code, such as fr, pt-BR or zh-Hans. It's part of the address: /fr/quickstart.
nameWhat readers see in the language picker, up to 50 characters. Write it in the language itself, like Français.
defaulttrue on the language your pages are written in. Without it, the first language is the default.
translate"ai" to have AI translate every page into this language (Pro and Enterprise). "manual", the default, leaves the translations to you. See AI translations.

You can list up to 30 languages. An entry Typemark can't use, such as a code that appears twice or a language without a name, is left out, and the publish lists it as a warning on your project's overview.

Edit typemark.json in your connected repository, or with the CLI for a project Typemark hosts. Settings > Languages shows entries it can't use as warnings, and saving removes them.

Language codes

A code is a real language code: a language, then optionally a script and a region, such as fr, pt-BR, zh-Hans, es-419 or sr-Latn-RS. Typemark checks each part against the IANA language subtag registry.

  • Settings > Languages refuses a code that isn't one, such as zz or a typo, and says so under the field. For an old code, it names the current one: iw is now he.
  • A code in typemark.json that Typemark doesn't know is still published, and the publish lists a warning on your project's overview. Settings keeps it too, with a note, when you save other changes.
  • Codes are matched exactly as written, so use the same code in typemark.json and in your folder names.
  • mcp and ai-search can't be codes, since every site already uses those addresses.

The default language

Your existing pages are the default language. They keep their addresses, such as /quickstart, and nothing about them changes.

A site without languages is in English. A site that lists one language is entirely in that language: the page's lang attribute and search use it, and there's no language picker.

Where translations go

A translation has the same path as the page it translates, inside a folder named after the language code:

PageFrench translationAddress
quickstart.mdxfr/quickstart.mdx/fr/quickstart
guides/authentication.mdxfr/guides/authentication.mdx/fr/guides/authentication

With a docs_root, the language folders go inside it: docs/fr/quickstart.mdx. The language's home page is /fr.

A translation is a full page, with its own frontmatter (a translated title and description) and its body in that language. To start one by hand, copy the page's file into the language folder and translate it, in your repository or with the CLI. In the editor, the language switcher opens the translations a page already has.

What readers see

  • A language picker in the site header lists your languages and opens the page they're on in the one they pick. Typemark never chooses a language from the browser's settings.
  • The same navigation in every language. Tabs, groups and their order come from your navigation, with each page's title in the reader's language where it has a translation, and tab and group names translated where you give them a translation.
  • The site itself in their language. "On this page", search, the page actions menu, Ask AI, "Was this page helpful?", previous and next, dates and the 404 page are in the reader's language. See The site's own words.
  • Every page in every language. A page without a translation shows the default-language page at the language's address, so /fr/billing works before it's translated, and navigation never has gaps.
  • Links in the reader's language. On a French page, a link to /quickstart goes to /fr/quickstart once that page has a published French translation, and to /quickstart until then. Write links to the default addresses as usual: Typemark adjusts them when it serves the page, and your files don't change. Anchors, links to other sites, files such as /llms.txt, and links that already name a language (/de/setup) stay as written.
  • Search in the reader's language. Searching on a French page finds the French translations, and the default-language pages that have none yet. Search uses each language's word rules where Typemark has them, so different forms of a word match, and matches words as written for the others. See What each language gets.
  • Redirects in every language. A redirect from /old to /new also sends /fr/old to /fr/new.

What each language gets

Every language gets its own addresses, the language picker, translated navigation and hreflang links. Some things depend on the language:

FeatureLanguages
The site's own wordsEnglish, German, French, Spanish, Portuguese, Japanese and Estonian. Other languages show them in English.
Search that matches different forms of a wordArabic, Danish, Dutch, English, Finnish, French, German, Greek, Hungarian, Indonesian, Irish, Italian, Lithuanian, Nepali, Norwegian, Portuguese, Romanian, Russian, Spanish, Swedish, Tamil and Turkish. Other languages, such as Estonian, Japanese, Chinese and Korean, match words as written.
AI translationsAny language the AI model writes. Pro and Enterprise.

Right-to-left languages, such as Arabic, Hebrew, Persian and Urdu, aren't supported yet. You can publish them, but the layout stays left-to-right.

The site's own words

Everything your site says itself is in the reader's language on a translated page: the table of contents, search, the page actions menu, the "Use these docs with AI" card, Ask AI's panel, the feedback widget, previous and next, "Updated" dates and reading time, the mobile menu, "Powered by Typemark", the 404 page, and the sign-in form of a private site.

Typemark has these words in English, German, French, Spanish, Portuguese, Japanese and Estonian. A regional code uses its language's words, so pt-BR gets Portuguese and es-419 Spanish. Other languages show them in English. Product names, MCP, llms.txt and Markdown stay as they are.

Tab and group names, top navigation links and footer links come from your typemark.json. Give them a translation per language under translations.labels, keyed by the name as you wrote it:

"translations": {
  "labels": {
    "fr": { "Get started": "Premiers pas", "Guides": "Guides", "Status": "État du service" },
    "de": { "Get started": "Erste Schritte" }
  }
}

A name without a translation shows as written, and default-language pages always show the names as written. Because translations are keyed by the name, moving a group keeps its translation; renaming it needs a new one. For a language AI translates, AI fills in the names you haven't translated and never changes one you wrote.

Search engines

  • Every page sets its language in <html lang>.
  • Each page lists its versions in other languages with hreflang links, plus x-default for the default language. Only languages the page has its own translation in are listed, and hidden pages list none.
  • The sitemap lists each translation, with the same alternates.
  • A page shown in the default language at a translation's address points search engines to the default page as its canonical URL, so the same text isn't indexed twice.

What stays in the default language

In the editor

On a site with more than one language, the editor's top bar has a language switcher next to Visual and Source. It opens the page you're on in another language. Languages the page has no translation in yet are greyed out. A translation saves like any page.

Rename, move and delete pages in the default language. To rename or delete a translation, change its file in your repository or with the CLI.

The editor shows links as you wrote them. Preview opens the page on your site, with links in the page's language.

Check before you publish

typemark dev previews every language on your computer: the language picker, translated pages and labels, and links in the reader's language.

typemark check reads languages the way a publish does, and treats a link to /fr/<page> as a link to that page:

RuleSeverityWhat it means
config-languagesErrorA language entry Typemark leaves out, such as a code that isn't shaped like a language code or appears twice
language-codeWarningA code that isn't a real language code, such as zz or a typo. It's still published.
config-translationsWarningA translate other than "ai" or "manual", "ai" on a language AI doesn't translate into, a translations.do_not_translate that isn't a list, or translations.labels or translations.glossary that isn't an object of terms per language
languages-singleWarninglanguages lists one language, so the whole site is in it and there's no picker. List the default language first, then the others.
language-folderWarningA page in navigation sits in a language's folder, such as fr/intro. Readers can't reach it, since /fr/intro is the French version of intro. Move it out of the folder.
translation-unlistedWarningA translation of a page that isn't in navigation, so it isn't published