Translation Versions

Translation version management endpoints.

Base path: /api/v1/translation-versions

---

List Versions by Status

GET /api/v1/translation-versions

Required permission: translations:read

Query parameters

Parameter	Type	Default	Description
status	string	draft	Filter by status: draft, published, archived
language_ids	string	—	Comma-separated UUID list for language filter
full_key	string	—	Filter by label full_key (case-insensitive)
page	int	1	Page number
per_page	int	20	Items per page

Response 200 OK

{
  "data": [
    {
      "id": "uuid",
      "label_id": "uuid",
      "language_id": "uuid",
      "parent_id": null,
      "value": "Save changes",
      "status": "draft",
      "published_at": null,
      "published_by": null,
      "created_by": "uuid",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": null,
      "label": {
        "id": "uuid",
        "full_key": "common.btn.save",
        "namespace": "common",
        "group": "btn",
        "key": "save"
      },
      "language": {
        "id": "uuid",
        "code": "en",
        "name": "English",
        "is_default": true,
        "is_active": true
      }
    }
  ],
  "pagination": {
    "total": 45,
    "page": 1,
    "per_page": 20,
    "pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

---

List Latest Versions per Label

Returns the most recent version for each label and language combination.

GET /api/v1/translation-versions/latest

Required permission: translations:read

Query parameters

Parameter	Type	Default	Description
language_ids	string	—	Comma-separated UUID list for language filter
full_key	string	—	Filter by label full_key (case-insensitive)
value	string	—	Filter by translation value (case-insensitive)
page	int	1	Page number
per_page	int	20	Items per page

Response 200 OK — same structure as List Versions by Status.

Info

Returns one record per label_id + language_id combination — the version with the latest created_at.

---

Get Version

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

Required permission: translations:read

Response 200 OK

{
  "id": "uuid",
  "label_id": "uuid",
  "language_id": "uuid",
  "parent_id": "uuid",
  "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,
  "label": {
    "id": "uuid",
    "full_key": "common.btn.save",
    "namespace": "common",
    "group": "btn",
    "key": "save"
  },
  "language": {
    "id": "uuid",
    "code": "en",
    "name": "English",
    "is_default": true,
    "is_active": true
  }
}

Errors

Status	Description
404	Translation version not found

---

Update Version

Only draft versions can be updated.

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

Required permission: translations:update

Request body

{
  "value": "Save all changes"
}

Response 200 OK — updated TranslationVersionResponse object.

Errors

Status	Description
400	Only draft versions can be updated
404	Translation version not found

---

Bulk Publish

Publishes multiple draft versions in a single atomic operation. If any version cannot be published, the entire request fails.

POST /api/v1/translation-versions/publish

Required permission: translations:publish

Request body

{
  "version_ids": [
    "uuid-1",
    "uuid-2",
    "uuid-3"
  ]
}

Field	Type	Required	Constraints
version_ids	UUID array	✅	Min 1 item

Response 200 OK — list of published TranslationVersionResponse objects.

Atomic operation

All versions are published in a single transaction. If one fails, none are published.

Previous versions archived

When a version is published, the previously published version for the same label and language is automatically archived.

Errors

Status	Description
400	One or more versions are not drafts
404	One or more version IDs not found

---

Revert Version

Creates a new draft version with the value copied from a previous version. Used to roll back to an earlier translation.

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

Required permission: translations:create

Response 201 Created — new draft TranslationVersionResponse object.

Revert flow

Version A → "Save"         archived
Version B → "Save it"      archived
Version C → "Save changes" published  ← currently active
Version D → "Apply"        draft      ← in progress

POST /translation-versions/{version_B_id}/revert

Version E → "Save it"      draft      ← copied from B, parent = C

The reverted version must still be reviewed and published via bulk publish before it becomes active.

Errors

Status	Description
404	Translation version not found