AI translation

AI translation fills the missing values of a branch in the background. It does not work from the source text alone: key names, descriptions, character limits, your glossary, your style guide, similar translations from memory and the translations of related keys go along with it, so the result fits your product. AI translation is part of the Professional and Agency plans.

Start an AI translation

A run fills the values that are empty in the target languages you choose. Values that already have a translation are left alone unless you ask the API to overwrite them. Labels without text in the source language are skipped and reported. A project runs one AI translation at a time.

In the app

1. Open the project and switch to the branch you want to translate.
2. Click Auto-Translate above the labels table.
3. Pick the source language and one or more target languages. The dialog shows how many AI characters are left this month and how many values translation memory can fill without using any.
4. Click Start Translation.

The run continues in the background, so you can close the dialog. When it finishes you get a notification in the app and an email with a summary like this one:

Translated 69 values (DE, FR) in "Harbor"; 6 filled from translation memory; 4 set to the source text (marked "do not translate"); 1 could not be translated.

Any project member can start a run. AI characters come from the plan of the account that pays for the project – the project owner, or the workspace owner for a project in a workspace. When that plan has no AI translation, the dialog says so instead of showing the form.

With an API token

Tokens of any role can start a run and read its status. Only targetLangs is required:

curl -X POST https://api.translatize.com/v1/integrations/projects/$PROJECT_ID/translation/auto-translate \
  -H "Authorization: Bearer $TRANSLATIZE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "targetLangs": ["de", "fr"] }'

The answer is 202 with the started job, or 200 with nothingToTranslate: true when there is nothing to translate. Then follow the run with the status endpoint:

curl https://api.translatize.com/v1/integrations/projects/$PROJECT_ID/translation/status \
  -H "Authorization: Bearer $TRANSLATIZE_API_TOKEN"

{
  "activeJob": null,
  "lastJob": {
    "id": "6659f1a2b3c4d5e6f7081920",
    "status": "completed",
    "branch": "main",
    "sourceLang": "en",
    "targetLangs": ["de", "fr"],
    "counts": {
      "requestedLabels": 40,
      "translatedValues": 69,
      "failedValues": 1,
      "skippedValues": 0,
      "fromMemory": 6,
      "keptValues": 4
    },
    "chars": { "estimated": 2140, "actual": 1985 },
    "error": null,
    "startedAt": "2026-11-03T09:25:00.000Z",
    "finishedAt": "2026-11-03T09:25:48.311Z"
  },
  "aiQuota": { "used": 1985, "limit": 2000000, "remaining": 1998015 }
}

Every error code of both endpoints is listed in the Integration API reference.

From an AI agent

The MCP server has an auto_translate tool and a translation_job_status tool for the same two calls. On a plan without AI translation, auto_translate answers feature_not_available, and the agent can translate the missing values itself with get_missing_translations, get_glossary and find_translation_memory.

What the AI sees

Open Project Settings → AI translation. The section What the AI sees lists the sources of context. Each one is a switch, and all of them are on for a new project. Context is not counted against your AI characters: you use characters for the source text, nothing else.

The style guide and the guidance per language are not switches. The style guide goes with every AI translation, and the guidance for a language with every translation into it; an empty field sends nothing. With every switch off and no style guide or guidance for the language, the AI gets the source text alone.

Admins and owners can change these settings. Developers see them read-only, and translators don't see the tab.

Write a style guide

In Project Settings → AI translation, the Style guide takes up to 4,000 characters and goes with every AI translation. Under Guidance per language, click Add a language to write up to 2,000 characters for one target language; it is sent only when translating into that language. Save the text with Save style guide. The switches save as soon as you click them.

The style guide shapes how text is translated: tone, form of address, wording, spelling, punctuation, capitalisation, number and date formats, length and terminology. It does not change what a run does. Placeholders and keys stay as they are whatever the guide says.

AI review judges translations against the same style guide and glossary, so one document serves both.

An example

A style guide for a booking app called Harbor:

Product: Harbor, a booking app for small boat-rental businesses.
Audience: owners and front-desk staff, not developers. Plain words, no jargon.
Tone: friendly and direct. Short sentences. No exclamation marks in error messages.
Buttons and menu items: a verb, as short as the language allows.
Keep in English: Harbor, Harbor Pay, CSV, iCal.
"Booking" is a confirmed reservation. "Request" is one the owner has not accepted yet. Never mix them.
Errors: say what happened and what to do next. Never blame the user.

And the guidance for two of its languages:

Address the user with "du", in lower case.
Buttons in the infinitive: "Speichern", "Buchung stornieren".
Dates as 31.12.2026, prices as 1.234,50 €.

Address the user with "vous".
Buttons in the infinitive: "Enregistrer", "Annuler la réservation".
Non-breaking space before : ; ? ! and inside « ».

What makes a good one

• Rules, not adjectives. "Professional but warm" leaves the AI guessing. "Address the user with du" and "no exclamation marks in errors" don't.
• Name what stays in English. A line like "Keep in English: Harbor, Harbor Pay" covers the name inside sentences. A label that is only the name gets the do not translate switch.
• Define the words that matter. Pairs that are easy to mix up, like booking and request above, are where translations drift most easily.
• Keep language rules in the language guidance. Form of address, date formats and typography differ per language; the style guide holds what is true for all of them.
• Leave single strings to their descriptions. "Toolbar button that saves the current draft" belongs on that label, not in the style guide.
• Try one language first. Translate it, read a few dozen values, adjust the guide. A changed guide applies to the next run; to redo values that already exist, start a run through the API with overwriteTranslated: true.

"Do not translate" labels

Some strings read the same in every language: product names, brands, codes. Mark their label "do not translate" and they stay that way.

In the app

Open the label editor and turn on Do not translate under Context & Info. Developers, admins and owners can change it; translators see the setting read-only. With the switch on, the editor offers a button that fills the other languages with the source text right away, for example Copy the EN text to the other 3 languages; save the label to keep them. It works on every plan, with or without AI translation. In the labels table, the label shows a Don't translate badge.

What it changes

• AI translation copies the source text into the empty target values instead of translating it. The text is never sent to the AI and is not counted against your AI characters. The summary lists these values as "set to the source text".
• Quality checks, the merge gate and AI review skip the label, so the copy is never reported as untranslated.
• Translation memory does not learn from it, so the copy never turns up as a suggestion.
• The setting travels with the label through branches and merges, like its description.
• Turning it off makes it an ordinary label again. The next run translates values that are still empty; values that hold the copy stay until someone edits them or a run overwrites them.

Through the API

Send context.doNotTranslate with a label write, on PATCH …/labels or per item on PATCH …/labels/batch. Setting context needs a token with the developer role or higher; a translator token gets insufficient_permissions. false clears the setting.

curl -X PATCH https://api.translatize.com/v1/integrations/projects/$PROJECT_ID/labels \
  -H "Authorization: Bearer $TRANSLATIZE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "brand.name",
    "values": { "en": "Harbor" },
    "context": {
      "description": "Product name in the app header",
      "doNotTranslate": true
    }
  }'

{
  "key": "brand.name",
  "branch": "main",
  "created": true,
  "values": { "en": "Harbor" },
  "status": "draft",
  "tags": [],
  "context": {
    "description": "Product name in the app header",
    "doNotTranslate": true
  }
}

A request that only sets context on a key that does not exist yet fails with label_not_found instead of creating the label. Agents do the same with the MCP tools set_label_context, upsert_label and upsert_labels.

Placeholders and character limits

Every AI translation is compared with the placeholders of its source text, in the placeholder styles chosen under Project Settings → Quality checks. When a placeholder is lost or changed, the value is translated again. If it still does not match, it is not saved: it is left for a person, the summary counts it as "could not be translated", and it uses no AI characters.

When a label has a character limit and the translation is longer, the AI is asked for a shorter one. If nothing fits, the translation is saved and the Character limit quality check flags it, so a person can shorten it. The label editor shows the count under each language.

Plans and allowances

AI translation counts source characters once per target language: a 20-character text translated into three languages uses 60 characters. Context, exact memory matches, "do not translate" copies and values that fail the placeholder check are not counted.

A run that needs more characters than are left this month does not start: the dialog says so, and the API answers ai_quota_exceeded with the numbers. If the allowance runs out during a run, the run stops and the summary says how far it got.

On Free and Starter, "do not translate" labels work as described above, apart from the AI copy: use the editor's copy button instead. An AI agent connected over MCP can translate missing values itself on any plan.