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.

Updated Nov 19, 20265 min read

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, one page at a time, and commits each translation as it's done.

  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").

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.

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 tipsComponent 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. If AI changed code, a link, a component, a frontmatter key, or a term it should have kept, 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
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

In manual deploy mode, new and updated AI translations wait, like your own edits, until someone clicks Publish. Read them in the editor first, and Publish becomes your review step. 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.