# 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.

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

<Steps>
  <Step title="Add the language">
    In **Settings** > **Languages**, click **Add a language**, type its code, choose **AI** under **Translated by**, and click **Save languages**. See [Languages](https://docs.typemark.dev/configuration/languages) for the rest of the setup.

    Or, in [`typemark.json`](https://docs.typemark.dev/configuration/typemark-json), add the language to `languages` with `"translate": "ai"`:

    ```json title="typemark.json"
    "languages": [
      { "code": "en", "name": "English" },
      { "code": "fr", "name": "Français", "translate": "ai" },
      { "code": "de", "name": "Deutsch", "translate": "ai" }
    ]
    ```
  </Step>
  <Step title="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.
  </Step>
  <Step title="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](#statuses-in-the-editor).
  </Step>
</Steps>

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:

```json title="typemark.json"
"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:

```json title="typemark.json"
"translations": {
  "glossary": {
    "de": { "workspace": "Arbeitsbereich", "deploy": "bereitstellen" },
    "et": { "project": "projekt", "page": "leht" }
  }
}
```

AI also uses your translated [tab, group and link names](#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](https://docs.typemark.dev/editor/ai-writing#tell-ai-how-you-write): 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

| Translated | Kept exactly as written |
|------------|-------------------------|
| The text readers read: headings, paragraphs, lists, tables, and link text | Code blocks and `inline code` |
| `title`, `description` and `sidebarTitle` in the frontmatter | Every 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 included | Component 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](https://docs.typemark.dev/api-reference/openapi) generated from an OpenAPI spec.

## Tab, group and link names

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](https://docs.typemark.dev/configuration/languages#translate-tab-group-and-link-names)) 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](https://docs.typemark.dev/github/sync), 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:

| Status | What it means | What AI does |
|--------|---------------|--------------|
| **Source** | The default language, which translations are made from | |
| **Not translated yet** | There's no translation yet | Translates the page |
| **Translating…** | A translation is on its way | |
| **Up to date** | AI's translation of the page as it is now | Nothing |
| **Needs review** | AI's translation, waiting for someone to [approve](#review-before-readers-see-it) it | Nothing |
| **Updating soon** | AI's translation of an older version of the page | Translates it again |
| **Edited by hand** | Someone changed the translation, and the page hasn't changed since | Nothing |
| **Out of date** | Someone changed the translation, and the page has changed since | Nothing. 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](#limits). 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`:

```json title="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](https://docs.typemark.dev/configuration/publishing#manual-deploy) 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](https://docs.typemark.dev/github/previews) or [branches in the editor](https://docs.typemark.dev/editor/branches). 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](https://docs.typemark.dev/editor/ai-writing#your-content). It asks the provider to route requests only to model providers that don't store or train on your data.
