Machine Translation API

Comvi integrates with multiple machine translation providers to generate translation suggestions automatically. You can request suggestions for individual keys, translate in bulk, or stream real-time suggestions as they arrive from each provider.

Supported providers

Provider	ID	Glossary support
Google Translate	`google`	Yes
DeepL	`deepl`	Yes
Amazon Translate	`aws`	No
Azure Translator	`azure`	No
OpenAI	`openai`	No
Anthropic Claude	`anthropic`	No

Get configured providers

Check which machine translation providers are available on the server.

GET /api/v1/projects/:projectId/mt/configured-providers

Path parameters

Parameter	Type	Required	Description
`projectId`	`integer`	Yes	Project ID

Example request

curl -X GET \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/projects/1/mt/configured-providers

Example response

{
  "providers": {
    "google": true,
    "deepl": true,
    "aws": false,
    "azure": false,
    "openai": true,
    "anthropic": true
  }
}

Error codes

Status	Error	Description
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to view MT settings

Get MT suggestions

Request machine translation suggestions for a specific translation key. Returns suggestions from all enabled providers.

POST /api/v1/projects/:projectId/mt/suggestions

Path parameters

Parameter	Type	Required	Description
`projectId`	`integer`	Yes	Project ID

Request body

Field	Type	Required	Description
`key`	`string`	Yes	Translation key name (1-512 characters)
`namespace`	`string`	No	Namespace name (uses `default` if omitted)
`sourceLocale`	`string`	Yes	Source language code
`targetLocale`	`string`	Yes	Target language code
`sourceText`	`string`	No	Source text to translate (auto-resolved from key if omitted)
`limit`	`integer`	No	Max number of suggestions (1-10)

Example request

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "welcome.message",
    "sourceLocale": "en",
    "targetLocale": "uk",
    "limit": 3
  }' \
  https://api.comvi.io/api/v1/projects/1/mt/suggestions

Example response

[
  {
    "providerId": "google",
    "providerLabel": "Google Translate",
    "text": "Ласкаво просимо до нашого додатку!"
  },
  {
    "providerId": "deepl",
    "providerLabel": "DeepL",
    "text": "Ласкаво просимо до нашого застосунку!"
  },
  {
    "providerId": "openai",
    "providerLabel": "OpenAI",
    "text": "Вітаємо у нашому застосунку!"
  }
]

Error codes

Status	Error	Description
`400`	`INVALID_INPUT`	Source and target locales must be different
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to use machine translation
`429`	`TOO_MANY_REQUESTS`	Rate limit exceeded

Stream MT suggestions

Stream machine translation suggestions in real time. Suggestions arrive incrementally as each provider responds, rather than waiting for all providers to finish.

SSE stream (GET)

Browser-friendly variant using Server-Sent Events. Compatible with the EventSource API.

GET /api/v1/projects/:projectId/mt/suggestions/stream

Query parameters

Parameter	Type	Required	Description
`key`	`string`	Yes	Translation key name
`sourceLocale`	`string`	Yes	Source language code
`targetLocale`	`string`	Yes	Target language code
`namespace`	`string`	No	Namespace name
`sourceText`	`string`	No	Source text to translate
`limit`	`integer`	No	Max providers (1-10)

Example

const url = new URL('https://api.comvi.io/api/v1/projects/1/mt/suggestions/stream');
url.searchParams.set('key', 'welcome.message');
url.searchParams.set('sourceLocale', 'en');
url.searchParams.set('targetLocale', 'uk');

const source = new EventSource(url, { withCredentials: true });

source.addEventListener('suggestion', (event) => {
  const data = JSON.parse(event.data);
  console.log(`${data.providerLabel}: ${data.text}`);
});

source.addEventListener('done', () => {
  source.close();
});

NDJSON stream (POST)

Programmatic variant using newline-delimited JSON.

POST /api/v1/projects/:projectId/mt/suggestions/stream

Request body

Same as Get MT suggestions.

Example event format

Each line is a JSON object:

{"event":"suggestion","data":{"providerId":"google","providerLabel":"Google Translate","text":"Ласкаво просимо!"}}
{"event":"suggestion","data":{"providerId":"deepl","providerLabel":"DeepL","text":"Ласкаво просимо!"}}
{"event":"done","data":{}}

Batch machine translation

Translate multiple keys at once for a target locale. The job is queued and processed asynchronously. Returns a job ID you can use to poll for status.

POST /api/v1/projects/:projectId/keys/batch/mt

Path parameters

Parameter	Type	Required	Description
`projectId`	`integer`	Yes	Project ID

Request body

Field	Type	Required	Description
`keyIds`	`integer[]`	Yes	Array of translation key IDs to translate (at least 1)
`sourceLocaleCode`	`string`	Yes	Source language code
`targetLocaleCode`	`string`	Yes	Target language code
`overwriteExisting`	`boolean`	No	Overwrite existing translations (default: false)

Example request

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "keyIds": [42, 43, 44, 45],
    "sourceLocaleCode": "en",
    "targetLocaleCode": "uk",
    "overwriteExisting": false
  }' \
  https://api.comvi.io/api/v1/projects/1/keys/batch/mt

Example response

Returns 202 Accepted:

{
  "jobId": "mt_job_abc123",
  "status": "queued",
  "totalKeys": 4,
  "message": "Batch MT job queued successfully"
}

Check batch MT job status

Poll the status of a batch machine translation job.

GET /api/v1/projects/:projectId/keys/batch/mt/:jobId/status

Path parameters

Parameter	Type	Required	Description
`projectId`	`integer`	Yes	Project ID
`jobId`	`string`	Yes	Job ID from the batch MT response

Example request

curl -X GET \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/projects/1/keys/batch/mt/mt_job_abc123/status

Example response

{
  "jobId": "mt_job_abc123",
  "status": "completed",
  "progress": 100,
  "result": {
    "processed": 4,
    "failed": 0,
    "duration": 3200.5,
    "errors": []
  }
}

Job status values

Status	Description
`waiting`	Job is in the queue
`active`	Job is being processed
`completed`	Job finished successfully
`failed`	Job failed

Cancel batch MT job

Cancel a running or queued batch machine translation job.

POST /api/v1/projects/:projectId/keys/batch/mt/:jobId/cancel

Example request

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/projects/1/keys/batch/mt/mt_job_abc123/cancel

Example response

{
  "success": true,
  "message": "Job cancelled successfully"
}

Translate ICU forms

Translate ICU plural, select, or combined message forms. Returns translations for each form variant via an NDJSON stream.

POST /api/v1/projects/:projectId/mt/icu-translate

Request body

Field	Type	Required	Description
`sourceLocale`	`string`	Yes	Source language code
`targetLocale`	`string`	Yes	Target language code
`icuType`	`string`	Yes	ICU type: `plural`, `select`, or `combined`
`forms`	`object`	Yes	ICU form variants keyed by category (e.g., `one`, `other`)
`pluralVariable`	`string`	No	Variable name for plural (e.g., `count`)
`selectVariable`	`string`	No	Variable name for select (e.g., `gender`)

Example request

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceLocale": "en",
    "targetLocale": "uk",
    "icuType": "plural",
    "forms": {
      "one": "{count} item",
      "other": "{count} items"
    },
    "pluralVariable": "count"
  }' \
  https://api.comvi.io/api/v1/projects/1/mt/icu-translate

Example response (NDJSON stream)

{"event":"form","data":{"form":"one","text":"{count} елемент"}}
{"event":"form","data":{"form":"other","text":"{count} елементів"}}
{"event":"done","data":{}}

Next steps

Translations API Manage translation keys and apply MT suggestions.

Projects API Configure MT provider settings per project.

Machine Translation (Platform) Learn about MT configuration in the Comvi dashboard.

Glossaries API Use glossaries to improve MT quality with domain-specific terminology.