> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nt3.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Translations

> Read and update translation values for keys.

A **translation** is the value of a specific [key](/api-reference/endpoints/keys) in a specific language. Every translation goes through a status workflow: `untranslated` → `translated` → `reviewed` → `approved`. Each status change is recorded in version history, and any previous value can be restored with the revert endpoint.

Translations are scoped to a project and a key. Most translation write endpoints identify a single translation via the `:projectId` and `:keyId` path parameters; the bulk `overwrite` endpoint is the exception — it resolves translations by key string supplied in the request body.

## Endpoints

```
GET    /api/projects/:projectId/translations/:language
PUT    /api/projects/:projectId/keys/:keyId/translations/:language
POST   /api/projects/:projectId/translations/overwrite
PATCH  /api/projects/:projectId/keys/:keyId/translations/:language/status
POST   /api/projects/:projectId/keys/:keyId/translations/:language/revert
POST   /api/projects/:projectId/keys/:keyId/translations/:language/revert/:historyId
GET    /api/projects/:projectId/keys/:keyId/translations/:language/history
GET    /api/projects/:projectId/keys/:keyId/translations
```

## Get All Translations for a Language

Returns all translations in a given language for the entire project. Useful for building export workflows or analytics dashboards.

```bash theme={null}
curl "https://app.nt3.io/api/projects/proj_6abc123def456/translations/fr?page=1&limit=50" \
  -H "X-API-Key: entri_your_token_here"
```

**Response:**

```json theme={null}
{
  "data": [
    {
      "keyId": "key_abc123",
      "key": "nav.home",
      "value": "Accueil",
      "status": "approved",
      "language": "fr"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1
  }
}
```

## Upsert a Translation

Creates the translation if it does not exist, or updates it if it does. The `PUT` method is used for idempotent upsert behavior.

```bash theme={null}
curl -X PUT \
  https://app.nt3.io/api/projects/proj_6abc123def456/keys/key_abc123/translations/fr \
  -H "X-API-Key: entri_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "Accueil",
    "source": "human"
  }'
```

The `source` field indicates who produced the value. Valid values are `human` and `ai`. When `source` is `ai`, you may also include `aiConfidence` (0–100) to record the confidence score.

## Overwrite Translations by Key

Force-overwrite one or more existing translations identified by **key + language** (rather than `keyId`). This is the endpoint behind [`nt3 overwrite`](/developers/cli/overwrite) and is designed for tooling and agents that correct wrong translations spotted in local files.

Each overwritten translation is set to status `translated` with source `api`. Unknown keys are reported back in `notFound` — they are not created.

```bash theme={null}
curl -X POST \
  https://app.nt3.io/api/projects/proj_6abc123def456/translations/overwrite \
  -H "X-API-Key: entri_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "translations": [
      { "key": "common.save_button", "language": "nl", "value": "Opslaan" },
      { "key": "save_button", "namespace": "common", "language": "fr", "value": "Enregistrer" }
    ]
  }'
```

**Response:**

```json theme={null}
{
  "overwritten": 1,
  "notFound": [
    { "key": "save_button", "namespace": "common", "language": "fr" }
  ]
}
```

## Change Translation Status

Advance or roll back a translation through the workflow without changing the value:

```bash theme={null}
curl -X PATCH \
  https://app.nt3.io/api/projects/proj_6abc123def456/keys/key_abc123/translations/fr/status \
  -H "X-API-Key: entri_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"status": "approved"}'
```

Valid status values: `untranslated`, `translated`, `reviewed`, `approved`.

## Revert to Previous Version

Reverts the translation to the most recent previous value:

```bash theme={null}
curl -X POST \
  https://app.nt3.io/api/projects/proj_6abc123def456/keys/key_abc123/translations/fr/revert \
  -H "X-API-Key: entri_your_token_here"
```

To revert to a specific historical version, include the history entry ID:

```bash theme={null}
curl -X POST \
  https://app.nt3.io/api/projects/proj_6abc123def456/keys/key_abc123/translations/fr/revert/hist_789 \
  -H "X-API-Key: entri_your_token_here"
```

## Get Version History

Returns the full change history for a translation, ordered newest first:

```bash theme={null}
curl https://app.nt3.io/api/projects/proj_6abc123def456/keys/key_abc123/translations/fr/history \
  -H "X-API-Key: entri_your_token_here"
```

**Response:**

```json theme={null}
[
  {
    "_id": "hist_789",
    "previousValue": "Page d'accueil",
    "newValue": "Accueil",
    "previousStatus": "translated",
    "newStatus": "approved",
    "changedBy": "user_xyz",
    "changedByName": "Alice Martin",
    "source": "human",
    "created": "2025-03-02T09:15:00.000Z"
  },
  {
    "_id": "hist_456",
    "previousValue": null,
    "newValue": "Page d'accueil",
    "previousStatus": "untranslated",
    "newStatus": "translated",
    "changedBy": "ai",
    "changedByName": null,
    "source": "ai",
    "created": "2025-03-01T14:30:00.000Z"
  }
]
```

## Key Notes

* The `source` field on a translation helps you distinguish human edits (`human`), AI-generated values (`ai`), file imports (`import`), translation-memory fills (`tm`), and programmatic overwrites (`api`).
* History entries record both `previousValue` and `newValue`, giving you a full diff of every change. The `changedByName` field contains the display name of the user who made the change.
* The translations list endpoint (`GET /api/projects/:projectId/translations/:language`) supports `page` and `limit` query parameters for offset-based pagination.