Languages

View .md

Locales define which languages a project supports. Add a system locale from Comvi’s list, or create a custom locale with your own code. The locales attached to a project are on locales in GET /v1/projects/{id}.

Common errors: 401 AUTHENTICATION_REQUIRED (missing or invalid credentials, or a Bearer key on a session-only route), 403 FORBIDDEN, 403 READ_ONLY_MODE on writes. See Errors.

Locale object

{ "id": 2, "code": "uk", "name": "Ukrainian", "nativeName": "Українська", "isCustom": false, "flagEmoji": "🇺🇦" }

`GET /v1/projects/{id}/locales/stats`

Translation counts and percentages per language. A caller with language restrictions sees only their languages.

Session cookie or API key with translations:read.

Parameter	In	Type	Required	Meaning
`id`	path	`integer`	Yes	Project ID

curl -H "Authorization: Bearer $COMVI_API_KEY" https://api.comvi.io/v1/projects/1/locales/stats

[
  { "localeCode": "uk", "totalKeys": 250, "translated": 200, "notReviewed": 30, "notTranslated": 20, "translatedPct": 80, "notReviewedPct": 12, "notTranslatedPct": 8 }
]

`POST /v1/projects/{id}/locales`

Add a language. Existing keys get placeholder values in the new language with not_translated status.

Session cookie only, with locale.create.

isCustom selects which field set applies; fields of the other set are ignored, and a missing field of the chosen set returns 400 VALIDATION_ERROR rather than a schema error.

Parameter	In	Type	Required	Meaning
`id`	path	`integer`	Yes	Project ID
`isCustom`	body	`boolean`	Yes	`false` for a system locale, `true` for a custom one
`localeCode`	body	`string`	System	System locale code, such as `uk`
`code`	body	`string`	Custom	1 to 50 characters; letters, digits, `-` and `_`
`name`	body	`string`	Custom	Display name
`nativeName`	body	`string`	Custom	Native name
`flagEmoji`	body	`string`	No	Up to 10 characters, custom only

curl -X POST -b cookies.txt -H "Content-Type: application/json" \
  -d '{"isCustom": true, "code": "en-pirate", "name": "Pirate English", "nativeName": "Pirate English", "flagEmoji": "🏴‍☠️"}' \
  https://api.comvi.io/v1/projects/1/locales

Returns 201 Created with the locale object.

Status and code	When
`400 LOCALE_NOT_FOUND`	`localeCode` is not a valid system locale
`400 VALIDATION_ERROR`	A required field for the chosen `isCustom` mode is missing
`403 LIMIT_EXCEEDED`	The organization has a custom language limit and the project is at it. No plan sets one
`409 LOCALE_ALREADY_EXISTS`	The locale is already on the project, or a custom `code` is a built-in language once canonicalised (`pt_br`, `PT-BR` and `pt-BR` are all the built-in `pt-BR`)
`422 FIELD_REQUIRED`	`isCustom` is missing

`PATCH /v1/projects/{id}/locales/{localeCode}`

Update per-language settings. The one setting is aiContext, the context passed to AI providers when translating into this language.

Session cookie or API key with translations:write.

Parameter	In	Type	Required	Meaning
`id`	path	`integer`	Yes	Project ID
`localeCode`	path	`string`	Yes	Locale code
`aiContext`	body	`string \| null`	No	Up to 2000 characters. `null` clears it; omitting it leaves the stored value

curl -X PATCH -H "Authorization: Bearer $COMVI_API_KEY" -H "Content-Type: application/json" \
  -d '{"aiContext": "Use formal address. Keep product names in English."}' \
  https://api.comvi.io/v1/projects/1/locales/uk

Returns 204 No Content. The value comes back as locales[].aiContext on the project. An empty body still checks that the locale is attached to the project.

Status and code	When
`404 LOCALE_NOT_FOUND`	No such locale, or not attached to the project
`422 FIELD_TOO_LONG`	`aiContext` is over 2000 characters

`DELETE /v1/projects/{id}/locales/{localeCode}`

Remove a language and permanently delete every translation value in it.

Session cookie only, with locale.delete.

Parameter	In	Type	Required	Meaning
`id`	path	`integer`	Yes	Project ID
`localeCode`	path	`string`	Yes	Locale code

curl -X DELETE -b cookies.txt https://api.comvi.io/v1/projects/1/locales/uk

Returns 204 No Content.

Status and code	When
`400 LOCALE_NOT_FOUND`	The code is invalid or not on the project
`400 CANNOT_REMOVE_DEFAULT_LOCALE`	The locale is the source language. Change the source locale first
`404 PROJECT_NOT_FOUND`	Project does not exist

`GET /v1/locales`

List every system locale. Public, no authentication.

curl https://api.comvi.io/v1/locales

Returns an array of locale objects.

Status and code	When
`429 TOO_MANY_REQUESTS`	The global limit of 500 requests per minute was exceeded

`GET /v1/locales/{code}`

Read one system locale. Public, no authentication.

Parameter	In	Type	Required	Meaning
`code`	path	`string`	Yes	Locale code

curl https://api.comvi.io/v1/locales/uk

Returns one locale object.

Status and code	When
`404 LOCALE_NOT_FOUND`	No locale with that code

Next steps

Projects to read the locales attached to a project
Translations for values per locale
Languages in the platform for the dashboard