Typemark Documentation

AI translations

Let AI translate every page into your other languages and keep each translation up to date as your docs change. Available on Pro and Enterprise.

Aktualisiert am 19. Nov. 20267 Min. Lesezeit

Turn on AI translation for a language and Typemark translates every page into it, then translates a page again whenever it changes. Translations are ordinary MDX files in your repository: read them, edit them, or rewrite them by hand, and Typemark never overwrites a translation someone edited. AI translations are on Pro and Enterprise, and follow the project owner's plan.

Turn it on

  1. Add the language

    In Settings > Languages, click Add a language, type its code, choose AI under Translated by, and click Save languages. See Languages for the rest of the setup.

    Or, in typemark.json, add the language to languages with "translate": "ai":

    "languages": [
      { "code": "en", "name": "English" },
      { "code": "fr", "name": "Français", "translate": "ai" },
      { "code": "de", "name": "Deutsch", "translate": "ai" }
    ]
  2. Publish the change

    Settings publishes it when you save. If you edited typemark.json, push it to your deployment branch, or with typemark push. After the publish, Typemark starts translating, your languages side by side, and commits each translation as it's done. A page takes about 10 to 20 seconds.

  3. Read the translations

    In the editor, open a page and pick the language from the language switcher in the top bar. Each language shows the translation's status.

You can mix: translate some languages with AI and others by hand, which is the default ("translate": "manual").

Languages AI translates into

AI translates into 12 languages we've tested for quality: English, Spanish, French, German, Portuguese, Italian, Dutch, Polish, Japanese, Korean, Chinese and Estonian. Regional codes count too, such as pt-BR, es-419 or zh-Hant.

Any other language can be translated by your team. In Settings > Languages, a language AI doesn't translate into yet offers Ask us to add it, which tells us you need it. If typemark.json has "translate": "ai" on one, your site is still published and the language is translated by hand; typemark check and the build say so.

Keep terms as they are

List product names, feature names and other terms that must never be translated in Settings > Languages > Terms AI keeps as written, one per line, or under translations.do_not_translate. Up to 200 terms of up to 100 characters each:

"translations": {
  "do_not_translate": ["Acme Pay", "Workspace", "acme.config.json"]
}

AI writes them exactly as given, in the text and in component props. Typemark checks that every one of them survives before it saves a translation.

Translate terms the same way everywhere

Give AI a glossary per language under translations.glossary: how to translate the words your docs use, so every page says the same thing. AI adapts each term to the sentence (plural, case) where the language needs it. Up to 200 terms of up to 100 characters each, per language:

"translations": {
  "glossary": {
    "de": { "workspace": "Arbeitsbereich", "deploy": "bereitstellen" },
    "et": { "project": "projekt", "page": "leht" }
  }
}

AI also uses your translated tab, group and link names, so a page calls a section what the navigation calls it.

Set the tone

AI translations follow the same instructions as AI writing: what you write in Settings > AI writing, saved as ai.instructions. Say how formal to be, whether to address readers as "tu" or "vous", or which spelling to use.

What gets translated

TranslatedKept exactly as written
The text readers read: headings, paragraphs, lists, tables, and link textCode blocks and inline code
title, description and sidebarTitle in the frontmatterEvery other frontmatter key and value
The text in components: card, tab, step, accordion and callout titles, descriptions, labels, image alt text, captions, placeholders, hints and tips, and the text between their tags, examples includedComponent names, prop names, and props that aren't text, such as href, src, icon and url
Link and image targets
Props written as {expressions}, text props included
The terms in do_not_translate

Typemark checks every translation before it saves it: that AI didn't change code, a link, a component, a frontmatter key, or a term it should have kept, and that the page is written in the language you asked for. When a check fails, AI tries once more, told what was wrong. If that fails too, the translation is thrown away and the page keeps the translation it had, or shows the default-language page if it had none. Typemark tries again later.

Pages longer than 40,000 characters aren't translated, and neither are API reference pages generated from an OpenAPI spec.

AI also translates your site's names from typemark.json: tabs, groups, top navigation links and footer links. It writes them into translations.labels for the language (Languages) as a commit by Typemark AI, keeping the terms in do_not_translate.

It only fills in names that have no translation yet. A name you wrote or edited is never changed. To keep a name as written in a language, give it an empty translation ("Changelog": ""), and AI leaves it alone. When you rename a group, AI translates the new name and removes its own translation of the old one.

Where translations are saved

A translation goes where a hand-written one would: fr/quickstart.mdx for quickstart.mdx, inside your docs_root if you have one. Each is a commit of its own, named like "Translate quickstart into Français", by Typemark AI. On a connected repository, it's pushed to GitHub like a save in the editor.

Typemark keeps a record of what AI wrote, pages and names, in .typemark/translations.json. Leave it in your repository: it's how Typemark tells AI's text from your edits.

Statuses in the editor

The editor's language switcher shows each AI language's status for the page you're on:

StatusWhat it meansWhat AI does
SourceThe default language, which translations are made from
Not translated yetThere's no translation yetTranslates the page
Translating…A translation is on its way
Up to dateAI's translation of the page as it is nowNothing
Needs reviewAI's translation, waiting for someone to approve itNothing
Updating soonAI's translation of an older version of the pageTranslates it again
Edited by handSomeone changed the translation, and the page hasn't changed sinceNothing
Out of dateSomeone changed the translation, and the page has changed sinceNothing. Update it by hand, or re-translate it.

Edit a translation

Open the translation from the language switcher, change it, and save. It's now Edited by hand, and AI leaves it alone from then on, even when the page changes. When the page does change, it shows Out of date, so you know to update it.

A translation you add yourself in an AI language is treated the same way: AI never replaces it.

Re-translate

To start again from AI's version, open the translation and choose Re-translate into followed by the language in the language switcher. It replaces the translation, your edits included, and counts towards the monthly limit. Editors and the project owner can re-translate.

Review before readers see it

To have someone who speaks the language read every AI translation before it goes live, turn on Review before publishing for the language in Settings > Languages, or add "review": true to it in typemark.json:

{ "code": "et", "name": "Eesti", "translate": "ai", "review": true }

New and updated translations in that language then wait as Needs review, and readers see the default-language page, or the version approved before, meanwhile. Open the translation in the editor, read it, and click Approve next to its status: it goes live, and the approval is saved in .typemark/translations.json as a commit by you. Fix anything first by editing it; a translation edited by hand goes live when you save it, like any page. Editors and the project owner can approve.

Without review, in manual deploy mode new and updated AI translations wait, like your own edits, until someone clicks Publish. In auto-deploy mode, each translation goes live as soon as it's built.

When translations run

AI translates what's on your deployment branch: after a save in the editor, a push to the deployment branch, or a typemark push.

It never translates preview deployments or branches in the editor. A branch keeps the translations it has, and its pages are translated once it's merged. Re-translate isn't offered while the editor is on a branch.

Limits

AI translates up to 2,000 pages a month across all of the owner's sites and languages. A page translated into three languages counts three times, and so does each update. Translating a language's tab, group and link names counts as one page. When the limit is reached, AI stops translating until the 1st of the next month. Translations already published stay, and pages without one show the default language until then.

If the owner's plan changes

AI translations follow the project owner's plan. If the owner moves to Free, translations already published stay on the site, but AI stops translating new and changed pages, and Re-translate isn't available. You can still edit translations by hand. Upgrade again and AI picks up where it left off.

Your content

Typemark sends the page and the instructions above to its AI provider, the same way as for AI writing. It asks the provider to route requests only to model providers that don't store or train on your data.