Note: This feature is currently in beta, please share your feedback with us!

Authentication #️⃣

This translation endpoint is the only endpoint in the Localazy API available when using translation tokens and it’s recommended to use this type of token for these operations.

Credits #️⃣

Each translation request consumes Localazy credits from your Localazy account balance. The number of credits used depends on the number of translated words.

Translate #️⃣

[POST] /projects/{projectId}/ai
Description Value
Accessible with project token true
Accessible with organization token true
Accessible with translation token true
Need write permission false
Available from role owner

Translates provided items from the source language to the target language using Localazy AI and considering the provided context, project-defined style guide and glossary.

Params

Request Body #️⃣

The request body is a JSON object with the following fields:

Field Required Description
from required Source locale code (e.g. en, cs, de).
to required Target locale code (e.g. cs, de, ja).
items required Array of items to translate. See “Item Object” below.
fallback optional Fallback machine translation engine to use when Localazy AI is unavailable. MT engines google and deepl are supported as fallback.

Item Object

Field Required Description
key optional Localization key identifier (e.g. btn_submit, welcome_message). Provides context for more accurate translations. Maximum 512 characters.
source required The source text to translate. Can be a string for simple values, or an object with plural forms (e.g. {"one": "1 item", "other": "%d items"}).
comment optional A comment or note providing additional context for the translator (e.g. "This is a button label"). Maximum 1000 characters.
lengthLimit optional Maximum length for the translation in characters. Must be between 0 and 32767. If the limit should not be applied, do not provide.

Sample Request #️⃣

Simple strings:

curl --request POST \
  --url https://api.localazy.com/projects/{projectId}/ai \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "from": "en",
    "to": "cs",
    "items": [
      {
        "key": "btn_submit",
        "source": "Submit",
        "comment": "Button label for form submission"
      },
      {
        "key": "welcome_message",
        "source": "Welcome back, %s!",
        "lengthLimit": 50
      }
    ]
  }'

Plural forms:

curl --request POST \
  --url https://api.localazy.com/projects/{projectId}/ai \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "from": "en",
    "to": "cs",
    "items": [
      {
        "key": "item_count",
        "source": {
          "one": "%d item",
          "other": "%d items"
        }
      }
    ]
  }'

With fallback engine:

curl --request POST \
  --url https://api.localazy.com/projects/{projectId}/ai \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "from": "en",
    "to": "de",
    "fallback": "deepl",
    "items": [
      {
        "source": "Hello, world!"
      }
    ]
  }'

Sample Response #️⃣

Successful translation:

{
  "result": true,
  "items": [
    {
      "key": "btn_submit",
      "source": "Submit",
      "translation": "Odeslat"
    },
    {
      "key": "welcome_message",
      "source": "Welcome back, %s!",
      "translation": "Vítejte zpět, %s!"
    }
  ]
}

Successful translation with plurals:

{
  "result": true,
  "items": [
    {
      "key": "item_count",
      "source": {
        "one": "%d item",
        "other": "%d items"
      },
      "translation": {
        "one": "%d položka",
        "few": "%d položky",    
        "other": "%d položek"
      }
    }
  ]
}

Response Object

Field Required Description
result required true if the translation was successful, false otherwise.
message optional Error message. Only present when result is false.
items optional Array of translated items. Only present when result is true. See “Response Item Object” below.

Response Item Object

Field Required Description
key optional The key identifier as provided in the request. null if not provided.
source required The original source text as provided in the request.
translation optional The translated text. Can be a string or an object with plural forms, matching the format of the source. May be null if the translation failed for a specific item.

Error Response #️⃣

When the request fails, the response contains result: false and a message describing the error.

{
  "result": false,
  "message": "The number of items exceeds the limit of 100 items per translation."
}

Limits #️⃣

The following limits apply to the AI Translation endpoint. Note that specific limits may vary based on your organization’s plan.

Limit Default Value
Requests per minute 10
Items per translation 32
Total source text length per request 16384 characters
Key length 512 characters
Comment length 1024 characters