Machine translation

Machine translation gives translators a first draft of a string to start from. It uses your own account with the service: you connect an API key, the service bills you for what you use, and we never pay for or charge for machine translation. You can choose between translation services (DeepL, Google Cloud Translation, Azure Translator) and AI models (Claude, OpenAI, Gemini, Mistral, DeepSeek). The steps below apply to all of them; Services lists what differs. If you would rather use another tool, see Using your own AI tool instead.

What happens, step by step #

1. You connect a key. An organization owner or admin pastes an API key under Organization → Integrations (choose Set up on the service). We check the key with the service before we store it, so a wrong key is refused on the spot. A key that the service knows but that may not do everything we need (a DeepL key limited to some scopes, for example) is refused with a message saying so: create a new key with permission to read usage and to translate text.
2. The key is stored encrypted. After saving, the key can’t be read back, not even by admins: the page only shows its last four characters. It is never written to logs or to the audit log, and it is only used to make requests to that service.
3. A translator asks for a suggestion. In the editor, the Machine translation card (shown only once your organisation has added a key, and while the project allows suggestions) lists every service that is set up, each with its own Suggest button. It sends the source text of that one string to the service. Placeholders such as {name}, {{count}} or %s and HTML tags are replaced by markers first, so they come back intact. Nothing else goes with it: no key names, notes, other strings, project names, or names and email addresses of people. Strings with ICU plural or select blocks are never sent; translate those by hand.
4. The suggestion is shown, not saved. The translator reads it and chooses Use, edits it if needed, and saves as usual. It then goes through your normal review workflow.
5. We check the answer. If the service changed or dropped a placeholder, the suggestion is thrown away and the translator is told to translate the string by hand.

Services #

AI models differ from translation services in three ways. They also receive a fixed instruction that tells them how to translate and to leave the markers alone; the instruction contains the two language codes and no other data. They bill by tokens, while the monthly limit counts the characters we send, so treat the limit as a rough guard and also set a spending limit in your account with the provider. And because a model writes free text, a suggestion is more likely to be unusable: one that lost or changed a placeholder is discarded like for any other service, and every suggestion is only shown until a person uses it.

When you save a model, we check it with a very short request, so a model name the provider doesn’t know is refused on the spot.

Several services #

Each service has its own key, its own monthly limit and its own count. When more than one is set up, one of them is the default: the first one you set up, until you choose another with Use as the default on its page. The default is listed first in the editor and is what automatic filling uses. In the editor every service has its own Suggest button, and Ask all asks all of them at once. The suggestions stay next to each other until you open another string or language, so a translator can compare them and use the best one. A service whose key was refused drops out of the choices until its key is replaced, and the others keep working. Removing the default makes another service the default.

Cost and limits #

• Monthly limit. The limit is in characters per calendar month (UTC) and defaults to 500,000, the size of DeepL’s free plan. Each service has its own limit and its own count. Each request is counted before it is sent. Once the limit would be passed, no request is made and people see a message. You can raise or remove the limit on the page of the service under Organization → Integrations. Removing it leaves only the service’s own quota.
• Failed requests are not counted. If the service refuses a request, nothing is added to the count.
• Counting. What counts is the text that is sent, including the markers that replace placeholders. The service’s own count may differ slightly (AI models count tokens); the service’s bill is the one that decides what you pay.
• Usage. The page shows the characters used this month.

Machine translated label #

A translation that was taken from a suggestion and not changed afterwards shows a Machine translated label in the editor. Editing the text removes the label. A project can switch the label off under Project settings → Workflow.

Filling in new strings automatically #

By default nothing is translated unless someone asks. A project can switch on Translate new strings automatically under Project settings → Workflow → Automatic translation, and choose there which connected service does it (the organization’s default unless you pick one). After a push, strings that were added are machine translated into every active language as drafts, with a machine translated entry in their history. Notes:

• It only fills translations that don’t exist yet. It never replaces existing text, also not when a source string changed, and also not when somebody saves a translation while the machine translation is on its way.
• It happens in the background, a few strings at a time, and one organization at a time. There is no limit per push, but a large push takes a while. Your monthly limit still applies.
• Nothing is lost when a run is interrupted: it carries on with what is still missing and never translates a string twice. When the service is overloaded or down, it waits and tries again later, up to 8 times over about ten hours.
• It stops when the key is refused, the monthly limit or your account’s quota is reached, or no service is connected. If the service chosen for the project is disconnected, it stops too: it never switches to another service, because that would change what is billed. The push itself is never affected.
• It is recorded in the audit log: mt.autofill when strings were queued after a push, and mt.autofill_stopped, with the reason, when a run had to stop (at most once an hour for the same reason).
• It uses your key and counts towards your monthly limit.

Translate the strings that are missing #

Automatic translation only looks at the strings of a push. For the strings that are still without a translation (from before you switched it on, or after a run that had to stop), choose Translate missing strings under Project settings → Workflow → Automatic translation. It works whether or not the automatic translation is switched on. The app first says how many translations are missing and about how many characters that is, and starts only after you confirm, because they count towards the monthly limit of the service. It translates the main branch, in the languages of the project that are not inactive, in the background, as drafts. It is not started again while a run is under way. A language that the service cannot translate into is left out of the numbers and named in the message, because nothing would be sent for it: choose another service for those languages, or translate them by hand. The same is available from the command line with ct translate.

When something goes wrong #

Nothing is changed when a request fails, and you see a message that says what happened.

Keeping control #

• Remove the key at any time on the page of the service under Organization → Integrations. It is deleted from our servers and machine translation stops for everyone. Your translations stay.
• Switch it off per project with Offer suggestions in the editor under Project settings → Workflow → Automatic translation.
• The audit log records adding, replacing and removing the key, changing the limit, and every automatic fill. It never contains the key.
• What the service does with your text is covered by your own agreement with it. Check which plan your key belongs to and what that plan promises about the text you send, for example whether it is used to train models.

Using your own AI tool instead #

You don’t have to store a key with us. Any AI tool that speaks the Model Context Protocol, such as Claude Code, can connect to the MCP server, read the strings that need translating and save translations with your own token, so your roles and API key scopes apply. Translations saved that way go through your review workflow like any others.