Skip to content

Translation Labels

Translation label management endpoints. Labels define the keys used for translations, organized in a namespace.group.key hierarchy.

Base path: /api/v1/translation-labels

Key Structure

Labels follow a three-level naming convention: 

{namespace}.{group}.{key}

common.btn.save
common.btn.cancel
nav.main.home
pages.home.title
errors.form.required
emails.welcome.subject

List Labels

GET /api/v1/translation-labels

Required permission: translations:read

Query parameters

Parameter Type Default Description
namespace string — Filter by namespace
skip int 0 Pagination offset
limit int 100 Pagination limit

Response 200 OK 

[
  {
    "id": "uuid",
    "namespace": "common",
    "group": "btn",
    "key": "save",
    "full_key": "common.btn.save",
    "description": "Save button label"
  }
]

Create Label

POST /api/v1/translation-labels

Required permission: translations:create

Request body 

{
  "namespace": "common",
  "group": "btn",
  "key": "save",
  "description": "Save button label"
}

Field Type Required Constraints
namespace string ✅ 1–100 characters
group string ✅ 1–100 characters
key string ✅ 1–100 characters
description string ❌ Max 500 characters

Response 201 Created — full TranslationLabelResponse object.

Info

full_key is automatically generated as {namespace}.{group}.{key} and must be unique.

Auto-created versions

Upon creation, empty draft versions are automatically created for every language currently in the database — including inactive ones. This ensures all languages have a version ready to be translated when the language becomes active.

Errors

Status Description
409 Label key already exists

Get Label

GET /api/v1/translation-labels/{id}

Required permission: translations:read

Response 200 OK — full TranslationLabelResponse object.

Errors

Status Description
404 Translation label not found

Update Label

Only description can be updated. Key components (namespace, group, key) are immutable after creation. 

PATCH /api/v1/translation-labels/{id}

Required permission: translations:update

Request body 

{
  "description": "Updated description for translators"
}

Response 200 OK — updated TranslationLabelResponse object.

Delete Label

Soft-deletes a label and all its associated versions. 

DELETE /api/v1/translation-labels/{id}

Required permission: translations:delete

Response 204 No Content

List Label Versions

Returns the full version history for a label, optionally filtered by language. 

GET /api/v1/translation-labels/{id}/versions

Required permission: translations:read

Query parameters

Parameter Type Default Description
language_id UUID — Filter by language

Response 200 OK 

[
  {
    "id": "uuid",
    "label_id": "uuid",
    "language_id": "uuid",
    "parent_id": null,
    "value": "Save changes",
    "status": "published",
    "published_at": "2026-01-01T00:00:00Z",
    "published_by": "uuid",
    "created_by": "uuid",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": null
  }
]

Create Version

Creates a new draft version for a label in a specific language. 

POST /api/v1/translation-labels/{id}/versions

Required permission: translations:create

Request body 

{
  "language_id": "uuid",
  "value": "Save changes"
}

Field Type Required Constraints
language_id UUID ✅ Must exist in DB
value string ✅ Min 1 character

Response 201 Created 

{
  "id": "uuid",
  "label_id": "uuid",
  "language_id": "uuid",
  "parent_id": "uuid",
  "value": "Save changes",
  "status": "draft",
  "published_at": null,
  "created_at": "2026-01-01T00:00:00Z"
}

Parent ID

The parent_id is automatically set to the currently published version for the same label and language combination, establishing the version history chain.