Languages API

Languages (locales) define which translations your project supports. You can add system locales from Comvi’s built-in list, or create custom locales for non-standard language codes.

List project languages

Retrieve all languages configured for a project, along with the project’s source locale.

GET /api/v1/projects/:id/locales/stats

Path parameters

Parameter	Type	Required	Description
`id`	`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/locales/stats

Example response

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

Error codes

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

Add language to project

Add a language to a project. You can add a system locale by code, or create a custom locale with your own code, name, and native name.

POST /api/v1/projects/:id/locales

Path parameters

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

Request body

Option A: Add a system locale

Field	Type	Required	Description
`isCustom`	`boolean`	Yes	Set to `false`
`localeCode`	`string`	Yes	System locale code (e.g., `uk`, `de`, `ja`)

Option B: Create a custom locale

Field	Type	Required	Description
`isCustom`	`boolean`	Yes	Set to `true`
`code`	`string`	Yes	Custom locale code (1-50 chars, alphanumeric with `-` and `_`)
`name`	`string`	Yes	Display name (e.g., “Pirate English”)
`nativeName`	`string`	Yes	Native name
`flagEmoji`	`string`	No	Flag emoji (max 10 characters)

Example request (system locale)

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "isCustom": false,
    "localeCode": "uk"
  }' \
  https://api.comvi.io/api/v1/projects/1/locales

Example request (custom locale)

curl -X POST \
  -H "X-API-Key: tlk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "isCustom": true,
    "code": "en-pirate",
    "name": "Pirate English",
    "nativeName": "Pirate English",
    "flagEmoji": "\u{1f3f4}\u{200d}\u{2620}\u{fe0f}"
  }' \
  https://api.comvi.io/api/v1/projects/1/locales

Example response

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

Error codes

Status	Error	Description
`400`	`LOCALE_NOT_FOUND`	The specified `localeCode` is not a valid system locale
`400`	`VALIDATION_ERROR`	Missing required fields for the chosen `isCustom` mode
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to edit this project
`403`	`LIMIT_EXCEEDED`	Language limit reached for the current plan
`409`	`LOCALE_ALREADY_EXISTS`	This locale is already added to the project

Remove language from project

Remove a language from a project. This deletes all translation values for that locale.

DELETE /api/v1/projects/:id/locales/:localeCode

Path parameters

Parameter	Type	Required	Description
`id`	`integer`	Yes	Project ID
`localeCode`	`string`	Yes	Locale code to remove (e.g., `uk`)

Example request

curl -X DELETE \
  -H "X-API-Key: tlk_your_api_key" \
  https://api.comvi.io/api/v1/projects/1/locales/uk

Example response

Returns 204 No Content with an empty body on success.

Error codes

Status	Error	Description
`400`	`LOCALE_NOT_FOUND`	The locale code is not valid or not in this project
`401`	`UNAUTHORIZED`	Missing or invalid authentication
`403`	`FORBIDDEN`	No permission to edit this project
`404`	`PROJECT_NOT_FOUND`	Project does not exist

List all available locales

Retrieve the full list of system locales supported by Comvi. This is a public endpoint that does not require authentication.

GET /api/v1/locales

Example request

curl -X GET \
  https://api.comvi.io/api/v1/locales

Example response

[
  {
    "id": 1,
    "code": "en",
    "name": "English",
    "nativeName": "English",
    "isCustom": false,
    "flagEmoji": "🇺🇸"
  },
  {
    "id": 2,
    "code": "uk",
    "name": "Ukrainian",
    "nativeName": "Українська",
    "isCustom": false,
    "flagEmoji": "🇺🇦"
  },
  {
    "id": 3,
    "code": "de",
    "name": "German",
    "nativeName": "Deutsch",
    "isCustom": false,
    "flagEmoji": "🇩🇪"
  }
]

Get locale by code

Retrieve details for a single locale by its code. This is a public endpoint.

GET /api/v1/locales/:code

Path parameters

Parameter	Type	Required	Description
`code`	`string`	Yes	Locale code (e.g., `en`, `uk`)

Example request

curl -X GET \
  https://api.comvi.io/api/v1/locales/uk

Example response

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

Error codes

Status	Error	Description
`404`	`LOCALE_NOT_FOUND`	No locale exists with the given code

Next steps

Projects API Create and manage translation projects.

Translations API Manage translation keys and values.

Import/Export API Bulk import and export translations.

Languages (Platform) Learn about language management in the Comvi dashboard.