Suggestions help a translator pick a value for a key that is already in your project. The three sources are deliberately split across separate endpoints so the cost of each call is obvious from the method and the URL.

Source	Endpoint	Cost
Translation Memory	[GET] .../suggestions/tm	Free
Machine Translation	[GET] .../suggestions/mt	Free
Localazy AI	[POST] .../suggestions/ai	Spends Localazy credits

All three describe an existing key. To translate arbitrary text you supply yourself, use the AI Translation endpoint instead.

Authentication #️⃣

All three endpoints accept project tokens and organization tokens.

Selecting languages #️⃣

Every endpoint takes the same two languages:

Field	Required	Description
to	required	The target language, as a language code (e.g. pt_BR, cs) or its numeric language id (e.g. 112, 60). An unrecognised value returns 400 with error unknown_lang.
from	optional	Overrides the source language the suggestions are computed from, in the same code-or-numeric form. When omitted, the project’s source language is used.

When from equals to there is nothing to translate: the result is empty with enabled set to false.

Reading the response #️⃣

All three endpoints share one envelope, and the three fields answer different questions. Reading them in order avoids the most common mistake — reporting “no suggestions exist” when the feature was simply switched off.

Field	Description
enabled	Whether the source could run at all for this project and language pair.
errors	Soft failures keyed by engine name. These never change the HTTP status.
items	One entry per source form. A singular key yields one entry; a plural or array key yields one per form.

• enabled: false — the source is switched off in the project’s settings, or the target equals the source language.
• enabled: true with empty items — it ran and found nothing.
• errors — one engine failing does not fail the request. The reserved key general carries failures that belong to no single engine, most commonly the key having no value in the source language.

Translation Memory suggestions #️⃣

[GET] /projects/{projectId}/keys/{id}/suggestions/tm

Description	Value
Accessible with project token	true
Accessible with organization token	true
Accessible with translation token	false
Need write permission	false
Available from role	translator
API level	normal

Returns translations reused from other phrases already in the project. This is free and reads only existing content.

Params

• {projectId} - Your project id or slug. Use the value from the projects endpoint.
• {id} - The key (phrase) id. Use the value from the file content endpoint.

Sample Request #️⃣

curl --request GET \
  --url 'https://api.localazy.com/projects/{projectId}/keys/{keyId}/suggestions/tm?to=cs' \
  --header 'Authorization: Bearer {{token}}'

Sample Response #️⃣

{
  "enabled": true,
  "items": [
    {
      "source": "Save changes",
      "suggestions": [
        {
          "value": "Uložit změny",
          "phraseId": "_e845123154101354564",
          "project": {
            "id": "_a8f2c1b4d5e6f708",
            "name": "My App",
            "image": "https://cdn-data.localazy.com/project-images/_a8f2c1b4d5e6f708",
            "url": "/p/my-app"
          }
        }
      ]
    }
  ]
}

Suggestion Object

Field	Description
value	The suggested translation.
phraseId	The key the translation was reused from.
project	The project holding that key — id, name, image, and url. url is a path relative to the Localazy site root, for example /p/my-app.

Machine Translation suggestions #️⃣

[GET] /projects/{projectId}/keys/{id}/suggestions/mt

Description	Value
Accessible with project token	true
Accessible with organization token	true
Accessible with translation token	false
Need write permission	false
Available from role	translator
API level	normal

Returns one suggestion per translation engine that returned a result. These suggestions do not consume Localazy credits. A result that is not already cached is produced by a live call to the translation engine, so the first request for a given string may take longer.

The response may also include allowedEngines, the project’s explicit engine allow-list. It is present only when such a restriction has been configured, which is uncommon — treat its absence as “no restriction”, not as “no engines available”.

Sample Request #️⃣

curl --request GET \
  --url 'https://api.localazy.com/projects/{projectId}/keys/{keyId}/suggestions/mt?to=cs&from=en' \
  --header 'Authorization: Bearer {{token}}'

Sample Response #️⃣

{
  "enabled": true,
  "items": [
    {
      "source": "Save changes",
      "suggestions": [
        { "value": "Uložit změny", "engine": "google" },
        { "value": "Uložit úpravy", "engine": "deepl" }
      ]
    }
  ]
}

Response with a soft engine failure

{
  "enabled": true,
  "errors": {
    "azure": "Translation engine timed out."
  },
  "items": [
    {
      "source": "Save changes",
      "suggestions": [
        { "value": "Uložit změny", "engine": "google" }
      ]
    }
  ]
}

Localazy AI suggestions #️⃣

[POST] /projects/{projectId}/keys/{id}/suggestions/ai

Description	Value
Accessible with project token	true
Accessible with organization token	true
Accessible with translation token	false
Need write permission	false
Available from role	translator
API level	normal

Returns Localazy AI suggestions for the key. This is a POST rather than a GET because generating a suggestion spends the organization’s AI credits.

enabled requires both AI suggestions and Machine Translation to be switched on in the project’s settings.

Permissions #️⃣

When the project uses language-level permissions, a translator assigned to specific languages may request AI suggestions only for those languages; any other target language returns 401. Managers and owners are not restricted.

Request Body #️⃣

Field	Required	Description
to	required	The target language, as a code or numeric language id.
from	optional	Source language override. Defaults to the project’s source language.

Sample Request #️⃣

curl --request POST \
  --url https://api.localazy.com/projects/{projectId}/keys/{keyId}/suggestions/ai \
  --header 'Authorization: Bearer {{token}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": "cs"
  }'

Sample Response #️⃣

{
  "enabled": true,
  "items": [
    {
      "source": "Save changes",
      "suggestions": [
        { "value": "Uložit změny", "engine": "localazyAi" }
      ]
    }
  ]
}

Caching and credits #️⃣

A suggestion is generated once and then reused, so credits are spent the first time a given suggestion is produced, not on every request. Asking again for the same key and language returns the stored result and costs nothing.

The stored suggestion is discarded and regenerated when any of the inputs that shaped it change:

• the key’s source text,
• the project’s style guide and other context settings,
• the glossary for the target language,
• the key’s own comment or character limit.

This means you can call the endpoint freely while building a UI, but editing the style guide or glossary makes the next request a fresh, credit-consuming generation.

Rate limiting #️⃣

The Localazy AI endpoint is limited to 10 requests per minute per project by default. The limit is counted together with the other AI endpoints, so the same budget cannot be multiplied across endpoints. Exceeding it returns 429 with error rate_limited.

Translation Memory and Machine Translation have no endpoint-specific limit and are subject to the standard Localazy API limits.

Error responses #️⃣

Status	Error	When
400	bad_request	to is missing.
400	unknown_lang	to or from is not a recognised language.
401	unauthorized	The token’s role is below translator, the key does not exist in this project, or language-level permissions deny the target language.
429	rate_limited	The per-project per-minute AI limit was exceeded. Localazy AI only.

Engine-level problems are not errors in this sense — an engine failing or being temporarily unavailable is reported in the errors object with a 200 status.