---
title: "Translations"
description: "A project's own translation bundles, the shared ones it uses, its overrides and the composed locale its build pulls."
order: 9
---

A project's own translation bundles, the shared ones it uses, its overrides and the composed locale its build pulls.

## `GET /api/v1/projects/{slug}/translations`

What this project translates: its own bundles, and the shared ones it composes.

| Parameter | In | Type | About |
| --- | --- | --- | --- |
| `slug` | path | string |  |

| Status | Means | Body |
| --- | --- | --- |
| 200 | Done | [ProjectTranslationsResponse](#projecttranslationsresponse) |
| 403 | Not a member, or the role lacks translations.read |  |

## `POST /api/v1/projects/{slug}/translations/attachments`

Attach a package bundle at the version this project installs, or move an existing attachment to a new version.

| Parameter | In | Type | About |
| --- | --- | --- | --- |
| `slug` | path | string |  |

**Body:** [AttachRequest](#attachrequest)

| Status | Means | Body |
| --- | --- | --- |
| 200 | Attached at that version |  |
| 404 | No such bundle, or that version is not registered |  |
| 422 | Refused, and the error says why |  |

## `DELETE /api/v1/projects/{slug}/translations/attachments/{bundle}`

Stop composing a package bundle.

| Parameter | In | Type | About |
| --- | --- | --- | --- |
| `slug` | path | string |  |
| `bundle` | path | integer |  |

| Status | Means | Body |
| --- | --- | --- |
| 204 | Done, with no body |  |
| 404 | Not attached |  |

## `POST /api/v1/projects/{slug}/translations/bundles`

Create a translation bundle for one of the project's own namespaces, or for a package it publishes.

| Parameter | In | Type | About |
| --- | --- | --- | --- |
| `slug` | path | string |  |

**Body:** [CreateBundleRequest](#createbundlerequest)

| Status | Means | Body |
| --- | --- | --- |
| 201 | Created | [CreateBundleResponse](#createbundleresponse) |
| 403 | Your role does not allow this |  |
| 404 | No such project, or no such claim in it |  |
| 409 | That bundle already exists |  |
| 422 | Refused, and the error says why |  |

## `POST /api/v1/projects/{slug}/translations/bundles/{bundle}/versions`

Register the locale files a published version carries. Called by the publish that ships them, once per locale.

| Parameter | In | Type | About |
| --- | --- | --- | --- |
| `slug` | path | string |  |
| `bundle` | path | string |  |

**Body:** [RegisterVersionRequest](#registerversionrequest)

| Status | Means | Body |
| --- | --- | --- |
| 200 | Done | [RegisterVersionResponse](#registerversionresponse) |
| 404 | No such bundle here, or that version was never published |  |
| 422 | Not a package bundle |  |

## `GET /api/v1/projects/{slug}/translations/entries`

One of the project's own bundles, key by key with every locale side by side.

| Parameter | In | Type | About |
| --- | --- | --- | --- |
| `slug` | path | string |  |
| `bundle` | query | string | The bundle: its id, or the name of one of this project's own bundles. |
| `namespace` (optional) | query | string or null |  |
| `q` (optional) | query | string or null | Substring match on the key and every locale's value (case insensitive). |
| `missing_only` (optional) | query | boolean | Only keys missing a value in at least one of the bundle's locales. |

| Status | Means | Body |
| --- | --- | --- |
| 200 | Done | array of [EntryResponse](#entryresponse) |
| 404 | No such bundle in this project |  |

## `PUT /api/v1/projects/{slug}/translations/entries`

Create or edit one value in a bundle this project owns.

| Parameter | In | Type | About |
| --- | --- | --- | --- |
| `slug` | path | string |  |

**Body:** [SetOwnEntryRequest](#setownentryrequest)

| Status | Means | Body |
| --- | --- | --- |
| 200 | Done | [SetEntryResponse](#setentryresponse) |
| 404 | No such bundle in this project |  |
| 422 | Empty value / malformed namespace or key |  |

## `DELETE /api/v1/projects/{slug}/translations/entries`

Remove one key of an own bundle in every locale; the values land in history.

| Parameter | In | Type | About |
| --- | --- | --- | --- |
| `slug` | path | string |  |
| `bundle` | query | string |  |
| `namespace` | query | string |  |
| `key` | query | string |  |

| Status | Means | Body |
| --- | --- | --- |
| 204 | Done, with no body |  |
| 404 | No such bundle, or no such key |  |

## `GET /api/v1/projects/{slug}/translations/export/{locale}`

One locale, composed: the project's own text, its overrides and the bundles it uses, at the versions it uses.

| Parameter | In | Type | About |
| --- | --- | --- | --- |
| `slug` | path | string |  |
| `locale` | path | string |  |
| `bundle` (optional) | query | string or null | Which of the project's own bundles the composition is built on. Defaults to the one named like the project, which is the shape a single bundle project has. |

| Status | Means | Body |
| --- | --- | --- |
| 200 | The composed locale tree |  |
| 404 | No such bundle in this project |  |

## `GET /api/v1/projects/{slug}/translations/shared/{bundle}`

One shared bundle with this project's overrides applied on the side.

| Parameter | In | Type | About |
| --- | --- | --- | --- |
| `slug` | path | string |  |
| `bundle` | path | integer |  |
| `locale` (optional) | query | string or null | Defaults to the source locale. |

| Status | Means | Body |
| --- | --- | --- |
| 200 | Done | [SharedBundleResponse](#sharedbundleresponse) |
| 404 | The project does not share that bundle |  |

## `PUT /api/v1/projects/{slug}/translations/shared/{bundle}/overrides`

Override one shared key for this project.

| Parameter | In | Type | About |
| --- | --- | --- | --- |
| `slug` | path | string |  |
| `bundle` | path | integer |  |

**Body:** [SetOverrideRequest](#setoverriderequest)

| Status | Means | Body |
| --- | --- | --- |
| 200 | Done | [OverrideResponse](#overrideresponse) |
| 404 | The project does not share that bundle |  |
| 422 | Empty value / malformed namespace or key |  |

## `DELETE /api/v1/projects/{slug}/translations/shared/{bundle}/overrides`

Drop one override; the shared bundle's own value composes again.

| Parameter | In | Type | About |
| --- | --- | --- | --- |
| `slug` | path | string |  |
| `bundle` | path | integer |  |
| `locale` | query | string |  |
| `namespace` | query | string |  |
| `key` | query | string |  |

| Status | Means | Body |
| --- | --- | --- |
| 204 | Done, with no body |  |
| 404 | No such override |  |

## `GET /api/v1/tms/bundles`

Every translation bundle you can see: the shared ones, then the package ones, then the project ones.

| Status | Means | Body |
| --- | --- | --- |
| 200 | Done | array of [BundleSummary](#bundlesummary) |

## Types

### ProjectTranslationsResponse

| Field | Type | About |
| --- | --- | --- |
| `own` | array of [OwnBundleSummary](#ownbundlesummary) |  |
| `shared` | array of [SharedBundleSummary](#sharedbundlesummary) |  |

### AttachRequest

| Field | Type | About |
| --- | --- | --- |
| `bundle` | integer | The package bundle's id (`GET /tms/bundles`). |
| `version` | string | The installed version of the package. A bump is the same call again. |

### CreateBundleRequest

| Field | Type | About |
| --- | --- | --- |
| `estate` (optional) | boolean |  |
| `name` | string | Slug shaped for an own bundle; ignored when `package` is given, because a package bundle is named by its package. |
| `package` (optional) | string or null | `<registry>:<name>` of a package THIS project claimed, to create the package bundle other projects attach. Absent creates one of the project's own. |

### CreateBundleResponse

| Field | Type | About |
| --- | --- | --- |
| `id` | integer |  |
| `name` | string |  |
| `owner` | string |  |

### RegisterVersionRequest

| Field | Type | About |
| --- | --- | --- |
| `locale` | string | The locale the tree is in. The source locale's tree DEFINES the key set. |
| `tree` | any | The locale file's tree, exactly as it ships inside the package. |
| `version` | string |  |

### RegisterVersionResponse

| Field | Type | About |
| --- | --- | --- |
| `keys` | integer | Keys this version ships. |
| `skipped` | integer | Non string or empty leaves, which are not translations. |
| `written` | integer | Values written (a key whose translation was already there is not rewritten). |

### EntryResponse

| Field | Type | About |
| --- | --- | --- |
| `key` | string |  |
| `namespace` | string |  |
| `updated_at` | string |  |
| `values` | map of string | locale → value; a locale the key has no value in is absent. |
| `version` | integer | Highest version across the locales (the editor's staleness hint). |

### SetOwnEntryRequest

Also: [SetEntryRequest](#setentryrequest).

| Field | Type | About |
| --- | --- | --- |
| `bundle` | string | The bundle: its id, or the name of one of this project's own bundles. |

### SetEntryResponse

| Field | Type | About |
| --- | --- | --- |
| `version` | integer |  |

### SharedBundleResponse

| Field | Type | About |
| --- | --- | --- |
| `id` | integer |  |
| `locale` | string |  |
| `name` | string |  |
| `owner` | string |  |
| `project` | string | The home project, the one place the source copy is edited. |
| `rows` | array of [SharedKeyRow](#sharedkeyrow) |  |
| `version` (optional) | string or null |  |

### SetOverrideRequest

| Field | Type | About |
| --- | --- | --- |
| `key` | string |  |
| `locale` | string |  |
| `namespace` | string |  |
| `value` | string |  |

### OverrideResponse

| Field | Type | About |
| --- | --- | --- |
| `version` | integer |  |

### BundleSummary

| Field | Type | About |
| --- | --- | --- |
| `id` | integer |  |
| `languages` | integer |  |
| `latest_version` (optional) | string or null | The newest registered version of a package bundle, absent for the other two. |
| `name` | string | 'common'; a project's own namespace bundle; a package name verbatim. |
| `owner` | string |  |
| `package` (optional) | string or null | The package a package bundle follows, `<registry>:<name>`, else absent. |
| `project` | string | The HOME project: whose `translations.write` members may edit it. |
| `strings` | integer |  |

### OwnBundleSummary

| Field | Type | About |
| --- | --- | --- |
| `id` | integer |  |
| `languages` | integer |  |
| `name` | string |  |
| `namespaces` | integer |  |
| `strings` | integer |  |

### SharedBundleSummary

| Field | Type | About |
| --- | --- | --- |
| `id` | integer |  |
| `keys` | integer |  |
| `name` | string |  |
| `overrides` | integer |  |
| `owner` | string |  |
| `project` | string | The home project: who edits the source copy. |
| `removed` | integer | Overridden keys the bundle no longer ships. |
| `version` (optional) | string or null |  |

### SetEntryRequest

| Field | Type | About |
| --- | --- | --- |
| `key` | string |  |
| `locale` | string |  |
| `namespace` | string |  |
| `status` (optional) | string or null | translated (default) \| review, pre-translated strings await approval. |
| `value` | string |  |

### SharedKeyRow

| Field | Type | About |
| --- | --- | --- |
| `key` | string |  |
| `namespace` | string |  |
| `override_value` (optional) | string or null | This project's override for the picked locale, if it set one. |
| `removed` | boolean | Flagged, never dropped. |
| `values` | map of string | The bundle's own values, locale by locale. Read only for this project. |