# Translate

> POST /ai_agent/translate. Translate text, HTML or JSON in real-time or batch mode. Request fields, response shapes, formats, and every validation error.

Source: https://www.fluentc.ai/docs/api/translate/

```http
POST https://api.fluentc.ai/ai_agent/translate
```

Translates `input` into `target_language`. In `real-time` mode the translation is in the response. In `batch` mode the response is a `job_id` and you fetch the result with [Batch results](https://www.fluentc.ai/docs/api/batch-results.md).

## Request

Headers:

| Header | Value |
| --- | --- |
| `Authorization` | Your API key, with no `Bearer` prefix. See [Authentication](https://www.fluentc.ai/docs/authentication.md). |
| `Content-Type` | `application/json` |

Body:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `input` | string or object | Yes | The content to translate. A JSON object is accepted when `input_format` is `json`. |
| `input_format` | string | Yes | `text`, `html` or `json`. |
| `target_language` | string | Yes | Language to translate into. Two or three lowercase letters such as `es`. Must be enabled for your key. |
| `source_language` | string | No | Language of `input`. Same format as `target_language`. If omitted, it is worked out from the text. |
| `mode` | string | Yes | `real-time` or `batch`. Case-insensitive. |

Language codes and formats are explained in [Concepts](https://www.fluentc.ai/docs/concepts.md#language-codes).

## Response: real-time

`200 OK`

```json
{
  "status": "complete",
  "translation": "¡Hola, mundo!",
  "token_count": 15,
  "source_language_detected": "en"
}
```

| Field | Type | Description |
| --- | --- | --- |
| `status` | string | Always `complete` in real-time mode. |
| `translation` | string | The translated content. For `json` input this is a JSON-encoded string; parse it. |
| `token_count` | integer | The size of the translation in tokens. |
| `source_language_detected` | string | The source language code: detected, or the `source_language` you sent. |

## Response: batch

`200 OK`

```json
{
  "job_id": "abc123def456"
}
```

The request is accepted and translated in the background. Pass `job_id` to [Batch results](https://www.fluentc.ai/docs/api/batch-results.md) until `status` is `complete`.

The `job_id` is deterministic: the same `input` and `target_language` always produce the same ID, so it is safe to resubmit.

## Examples

### Text, real-time

```bash
curl -X POST https://api.fluentc.ai/ai_agent/translate \
  -H "Authorization: $FLUENTC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hello, world!",
    "input_format": "text",
    "target_language": "es",
    "source_language": "en",
    "mode": "real-time"
  }'
```

```python
import os
import requests

res = requests.post(
    "https://api.fluentc.ai/ai_agent/translate",
    headers={"Authorization": os.environ["FLUENTC_KEY"]},
    json={
        "input": "Hello, world!",
        "input_format": "text",
        "target_language": "es",
        "source_language": "en",
        "mode": "real-time",
    },
)
res.raise_for_status()
print(res.json()["translation"])  # ¡Hola, mundo!
```

```js
const res = await fetch("https://api.fluentc.ai/ai_agent/translate", {
  method: "POST",
  headers: {
    Authorization: process.env.FLUENTC_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    input: "Hello, world!",
    input_format: "text",
    target_language: "es",
    source_language: "en",
    mode: "real-time",
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${body.error}`);
console.log(body.translation); // ¡Hola, mundo!
```

### HTML, batch

Markup is preserved and the text inside it is translated.

```bash
curl -X POST https://api.fluentc.ai/ai_agent/translate \
  -H "Authorization: $FLUENTC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "<h1>Welcome</h1><p>This is a sample page.</p>",
    "input_format": "html",
    "target_language": "fr",
    "mode": "batch"
  }'
```

```json
{ "job_id": "abc123def456" }
```

### JSON, batch

Send the structure as an object. String values are translated and the keys and shape are kept.

```bash
curl -X POST https://api.fluentc.ai/ai_agent/translate \
  -H "Authorization: $FLUENTC_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "title": "Welcome", "cta": "Start now" },
    "input_format": "json",
    "target_language": "ja",
    "mode": "batch"
  }'
```

When the job completes, `translation` is a JSON-encoded string:

```json
{
  "status": "complete",
  "translation": "{\"title\":\"ようこそ\",\"cta\":\"今すぐ開始\"}",
  "token_count": 24,
  "source_language_detected": "en"
}
```

```python
import json

translated = json.loads(result["translation"])
print(translated["cta"])  # 今すぐ開始
```

## Errors

Errors are JSON with an `error` string. The full list is on [Errors](https://www.fluentc.ai/docs/api/errors.md). The ones specific to this endpoint:

| Status | Message | Fix |
| --- | --- | --- |
| `422` | `Input is missing` | Send a non-empty `input`. |
| `422` | `Invalid or missing input format. Allowed formats: text, html, json` | Set `input_format` to one of the three. |
| `422` | `Invalid or missing target language code.` | Use a lowercase two- or three-letter code. Region codes like `pt-BR` are not accepted. |
| `422` | `Target language 'xx' is not enabled for this site.` | Pick a language from [Languages](https://www.fluentc.ai/docs/api/languages.md). |
| `422` | `Invalid source language code: 'xx'.` | Fix `source_language`, or omit it. |
| `422` | `Source language 'xx' is not enabled for this site.` | Pick a language from [Languages](https://www.fluentc.ai/docs/api/languages.md). |
| `422` | `Invalid or missing mode. Allowed modes: batch, real-time` | Set `mode` to `batch` or `real-time`. |
| `422` | `Realtime translation is not supported for this agent.` | Your key is on the Batch plan. Use `batch`, or move to the Real-time plan. |
| `422` | `Agent translation is not supported for this site.` | The key isn't set up for the translation API. [Contact us](https://www.fluentc.ai/contact/). |
| `422` | `Invalid JSON format` | `input_format` is `json` but `input` isn't valid JSON. |

## Notes

- **Choose `batch` for large JSON.** It runs in parallel and reassembles the result for you.
- **Pass `source_language` when you know it.** It avoids guesses on very short strings.
- **Repeat requests are cheap.** Identical input and target language are answered from [translation memory](https://www.fluentc.ai/docs/concepts.md#translation-memory).
- **Request size.** Batch requests carry up to 50,000 rows. The n8n node limits a single input to 100,000 bytes; see [n8n](https://www.fluentc.ai/docs/integrations/n8n.md).