Asks a machine translation service for a machine translation of the source text of a key. The suggestion is only returned: save it to keep it. Needs a key for at least one service, see Machine translation.
POST /keys/{keyId}/translations/{language}/suggestionAccess: Session token, or an API key with the translations:write scope.
Role: Translator or higher in the project.
What is sent #
The source text of this one key, with placeholders and HTML tags swapped for markers and restored afterwards, and the two language codes. AI models also get a fixed instruction on how to translate. Nothing else: no key name, notes, other strings or user data. Messages with ICU plural or select blocks are refused instead of sent.
Path parameters #
| Parameter | Description |
|---|---|
keyId | The id of the key. |
language | The target language code, such as de-de. It must be an active language of the project. |
Request body #
| Field | Type | Required | Description |
|---|---|---|---|
provider | string | no | The service to ask, for example deepl. Left out, the organisation’s default service is used. |
Response 200 #
{
"text": "Hallo {name}, Sie haben 3 neue Nachrichten",
"provider": "deepl",
"characters": 54,
"usage": { "period": "2026-10", "characters": 1334, "requests": 15, "limit": 500000 }
}provider is the service that answered. characters is what this request added to that service’s count for the month. Request failures are not counted.
Errors #
Every failure leaves everything unchanged. The body never repeats what the service answered, and none of these is a 401 or 403, which would sign a person out.
| Status | error | When |
|---|---|---|
| 401 | unauthenticated | The token is missing or not valid. |
| 403 | forbidden | Your role in the project is below translator. |
| 404 | not_found | The key or an active language does not exist, or you have no access to the project. |
| 409 | mt_not_configured | The organisation has no key for the service (or for any service when provider is left out). |
| 409 | mt_key_rejected | The service refused the key. An admin has to replace it. Other services are not affected. |
| 409 | mt_limit_reached | The monthly limit of that service would be passed. limit is in the response. |
| 409 | mt_provider_quota | The service’s own quota is used up. |
| 409 | mt_suggestions_off | The project switched suggestions off. |
| 409 | branch_frozen, project_frozen | The branch or project is frozen. |
| 422 | mt_source_empty | The key has no source text. |
| 422 | mt_icu_unsupported | The message has ICU plural or select blocks. |
| 422 | invalid_request | fields.provider is invalid: not a service we know. |
| 422 | mt_model_unknown | The service does not know the model that is set. |
| 422 | mt_language_unsupported | The service does not support the language pair. |
| 422 | mt_placeholders_changed | The service changed or dropped a placeholder; the suggestion was discarded. |
| 422 | mt_text_too_long, mt_request_refused | The service refused the text. |
| 429 | mt_provider_rate_limited | The service is receiving too many requests. |
| 502 | mt_provider_unavailable, mt_provider_invalid_answer | The service could not be reached or answered with something unusable. |
See Errors for the error format.