> ## 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.

# AI Translation

> Trigger and manage AI-powered translation jobs.

Entri's AI translation engine uses frontier language models — Anthropic Claude and OpenAI GPT — to generate high-quality translations with context awareness. The AI reads the key name, description, any comments left by translators, and neighboring strings to produce translations that fit the tone and terminology of your project.

Every AI translation includes a **confidence score** from 0 to 100. High-confidence translations (typically 85+) are production-ready in most cases. Lower-confidence results should be reviewed by a human translator before approval.

The AI also respects your [Glossary](/api-reference/endpoints/glossary) — terms marked as "do not translate" are kept verbatim, and approved translations for glossary terms are used consistently.

## Endpoints

```
GET    /api/projects/:projectId/ai/status
POST   /api/projects/:projectId/ai/translate
POST   /api/projects/:projectId/ai/translate/batch
POST   /api/projects/:projectId/ai/translate/batch/start
GET    /api/projects/:projectId/ai/translate/batch/stream/:jobId
POST   /api/projects/:projectId/ai/translate/batch/cancel/:jobId
```

## Supported Model IDs

Pass one of these values as the `model` parameter to override the project's default:

| `model` value       | Provider  | Name              |
| ------------------- | --------- | ----------------- |
| `claude-haiku-4-5`  | Anthropic | Claude Haiku 4.5  |
| `claude-sonnet-4-6` | Anthropic | Claude Sonnet 4.6 |
| `claude-opus-4-6`   | Anthropic | Claude Opus 4.6   |
| `gpt-4o-mini`       | OpenAI    | GPT-4o mini       |
| `gpt-4o`            | OpenAI    | GPT-4o            |
| `gpt-5`             | OpenAI    | GPT-5             |
| `gpt-5-mini`        | OpenAI    | GPT-5 mini        |
| `gpt-5.2`           | OpenAI    | GPT-5.2           |

If `model` is omitted, the project's `preferredModel` is used. If that is also unset, Entri falls back to `claude-sonnet-4-6` (or the value of `DEFAULT_AI_PROVIDER` in your environment).

## Check AI Status

Returns available providers and models for the organization:

```bash theme={null}
curl https://app.nt3.io/api/projects/proj_6abc123def456/ai/status \
  -H "X-API-Key: entri_your_token_here"
```

**Response:**

```json theme={null}
{
  "configured": true,
  "availableProviders": ["anthropic"],
  "availableModels": [
    { "id": "claude-haiku-4-5", "displayName": "Claude Haiku 4.5", "provider": "anthropic" },
    { "id": "claude-sonnet-4-6", "displayName": "Claude Sonnet 4.6", "provider": "anthropic" },
    { "id": "claude-opus-4-6", "displayName": "Claude Opus 4.6", "provider": "anthropic" }
  ]
}
```

## Translate a Single Key

Generates a translation for one key in one target language. Uses the project's `preferredModel` unless overridden with `model`:

```bash theme={null}
curl -X POST \
  https://app.nt3.io/api/projects/proj_6abc123def456/ai/translate \
  -H "X-API-Key: entri_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "key_abc123",
    "sourceLanguage": "en",
    "targetLanguage": "fr",
    "sourceText": "Home",
    "keyName": "nav.home",
    "model": "claude-opus-4-6"
  }'
```

**Request body:**

| Field               | Type   | Required | Description                                 |
| ------------------- | ------ | -------- | ------------------------------------------- |
| `keyId`             | string | ✓        | ID of the translation key                   |
| `sourceLanguage`    | string | ✓        | Source language code (e.g. `en`)            |
| `targetLanguage`    | string | ✓        | Target language code (e.g. `fr`)            |
| `sourceText`        | string | ✓        | Text to translate                           |
| `keyName`           | string | ✓        | Key name for context (e.g. `nav.home`)      |
| `keyDescription`    | string |          | Optional description for additional context |
| `toneInstruction`   | string |          | Override tone instruction for this request  |
| `styleInstruction`  | string |          | Override style instruction for this request |
| `additionalContext` | string |          | Additional context for this request         |
| `model`             | string |          | Model ID to use (overrides project default) |

**Response:**

```json theme={null}
{
  "translation": "Accueil",
  "confidence": 94,
  "provider": "claude-opus-4-6"
}
```

## Batch Translate

Translates all untranslated strings for a target language:

```bash theme={null}
curl -X POST \
  https://app.nt3.io/api/projects/proj_6abc123def456/ai/translate/batch \
  -H "X-API-Key: entri_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceLanguage": "en",
    "targetLanguage": "fr",
    "model": "gpt-4o-mini"
  }'
```

**Request body:**

| Field               | Type   | Required | Description                                 |
| ------------------- | ------ | -------- | ------------------------------------------- |
| `sourceLanguage`    | string | ✓        | Source language code                        |
| `targetLanguage`    | string | ✓        | Target language code                        |
| `toneInstruction`   | string |          | Override tone instruction                   |
| `styleInstruction`  | string |          | Override style instruction                  |
| `additionalContext` | string |          | Additional context                          |
| `model`             | string |          | Model ID to use (overrides project default) |
| `limit`             | number |          | Max keys to translate (default 50, max 200) |

The synchronous batch endpoint returns when all keys are translated. For large projects use the streaming endpoint below.

## Streaming Batch Translation

For large batches, use the SSE-based streaming workflow:

**1. Start a job:**

```bash theme={null}
curl -X POST \
  https://app.nt3.io/api/projects/proj_6abc123def456/ai/translate/batch/start \
  -H "X-API-Key: entri_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceLanguage": "en",
    "targetLanguage": "fr"
  }'
```

Response: `{ "jobId": "uuid", "total": 120, "skipped": 5, "totalKeys": 120, "page": 1, "hasMore": false }`

**2. Stream progress:**

```
GET /api/projects/:projectId/ai/translate/batch/stream/:jobId
Accept: text/event-stream
```

Events: `start`, `progress` (per key), `complete`, `cancelled`

The `complete` event may include `aborted: true` with an `abortReason` string when the job stops early after repeated consecutive failures (e.g. an AI provider outage) — items skipped because of the abort are not counted in `failed`.

**3. Cancel:**

```bash theme={null}
curl -X POST \
  https://app.nt3.io/api/projects/proj_6abc123def456/ai/translate/batch/cancel/uuid
```

## Key Notes

* AI translation is available only when at least one AI provider key is configured for your organization.
* The model used for each translation is recorded in the `provider` field of the response.
* AI-generated translations are saved with `source: "ai"` and status `translated`. They are not automatically approved — a reviewer should check them before they are promoted to `approved`.
* The AI uses your organization's [Translation Memory](/api-reference/endpoints/translation-memory) to stay consistent with previously approved translations.

<Tip>
  Set a `preferredModel` in **Project Settings → General → AI Settings** to pick the best model for your project's language pair and content type, without specifying it in every API call.
</Tip>