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.
Actualizado el 19 nov 20267 min de lectura
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
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 tolanguageswith"translate": "ai":"languages": [ { "code": "en", "name": "English" }, { "code": "fr", "name": "Français", "translate": "ai" }, { "code": "de", "name": "Deutsch", "translate": "ai" } ]Publish the change
Settings publishes it when you save. If you edited
typemark.json, push it to your deployment branch, or withtypemark 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.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
| 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 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) 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:
| 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 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. 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.