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

# Translate

> Dialect-aware Arabic translation powered by HUMAIN's ALLaM model.

Translate text between English and Arabic with dialect awareness. Generates culturally appropriate translations in Gulf, Egyptian, Levantine, or MSA Arabic.

<Note>
  Cost: **\$0.005** per request (5 credits). Semantic cache hits are free (`X-NAWA-Cache: HIT`).
</Note>

## Request

### Headers

| Header          | Required | Description                                            |
| --------------- | -------- | ------------------------------------------------------ |
| `Authorization` | Yes      | `Bearer nawa_live_sk_xxx` or `Bearer nawa_test_sk_xxx` |
| `Content-Type`  | Yes      | `application/json`                                     |

### Body parameters

| Parameter  | Type   | Required | Description                                                                                   |
| ---------- | ------ | -------- | --------------------------------------------------------------------------------------------- |
| `text`     | string | Yes      | The text to translate. Max 5,000 characters.                                                  |
| `source`   | string | No       | Source language: `ar`, `en`, `auto`. Default: `auto` (detects automatically).                 |
| `target`   | string | Yes      | Target language: `ar`, `en`.                                                                  |
| `dialect`  | string | No       | Target dialect for Arabic output: `gulf`, `egyptian`, `levantine`, `msa`. Default: `msa`.     |
| `tone`     | string | No       | Translation tone: `formal`, `casual`, `social_media`. Default: `formal`.                      |
| `platform` | string | No       | Source platform for social media tone context: `youtube`, `instagram`, `twitter`, `facebook`. |
| `metadata` | object | No       | Arbitrary key-value metadata to attach to the translation.                                    |

### Example request

<CodeGroup>
  ```bash cURL theme={null}
    curl -X POST https://api.trynawa.com/v1/translate \
      -H "Authorization: Bearer nawa_test_sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "text": "Hello, how are you?",
        "source": "en",
        "target": "ar",
        "dialect": "gulf",
        "tone": "casual"
      }'
  ```

  ```typescript TypeScript theme={null}
    import { Nawa } from '@nawalabs/sdk'

    const nawa = new Nawa({ apiKey: process.env.NAWA_API_KEY })

    const { data, error } = await nawa.translate({
      text: 'Hello, how are you?',
      source: 'en',
      target: 'ar',
      dialect: 'gulf',
      tone: 'casual'
    })
  ```

  ```python Python theme={null}
    from nawa import Nawa

    nawa = Nawa(api_key="your_api_key")

    result = nawa.translate(
        text="Hello, how are you?",
        source="en",
        target="ar",
        dialect="gulf",
        tone="casual"
    )
  ```
</CodeGroup>

## Response

### Success response (200)

```json theme={null}
{
  "success": true,
  "result": {
    "id": "trn_nw_pon1yom9bkfe",
    "object": "translation",
    "text": "Hello, how are you?",
    "translated_text": "هلا، كيف حالك؟",
    "source_language": "en",
    "target_language": "ar",
    "source_dialect": null,
    "target_dialect": "gulf",
    "tone": "casual",
    "model": "nagl-v1",
    "provider": "allam",
    "fallback_used": false,
    "cached": false,
    "cost_usd": 0.005,
    "credits_used": 5
  },
  "errors": [],
  "request_id": "req_nw_4c11w71e44cb"
}
```

### Result fields

| Field             | Type           | Description                            |
| ----------------- | -------------- | -------------------------------------- |
| `text`            | string         | The original input text                |
| `translated_text` | string         | The translated output                  |
| `source_language` | string         | Detected or specified source language  |
| `target_language` | string         | Target language                        |
| `source_dialect`  | string or null | Detected dialect if source is Arabic   |
| `target_dialect`  | string or null | Target dialect if target is Arabic     |
| `tone`            | string         | The tone used for translation          |
| `model`           | string         | Model version used                     |
| `provider`        | string         | AI provider used (`allam` or `claude`) |
| `fallback_used`   | boolean        | Whether the fallback provider was used |
| `cached`          | boolean        | Whether served from semantic cache     |
| `cost_usd`        | number         | Cost in USD                            |
| `credits_used`    | number         | Credits deducted                       |

### Dialect examples

<AccordionGroup>
  <Accordion title="English to Gulf Arabic (casual)">
    **Input:** "The food was amazing, thank you so much"
    **Output:** "الأكل كان وايد حلو، مشكور وايد"

    ```bash theme={null}
        curl -X POST https://api.trynawa.com/v1/translate \
          -H "Authorization: Bearer nawa_test_sk_xxx" \
          -H "Content-Type: application/json" \
          -d '{"text": "The food was amazing, thank you so much", "source": "en", "target": "ar", "dialect": "gulf", "tone": "casual"}'
    ```
  </Accordion>

  <Accordion title="English to Egyptian Arabic (social media)">
    **Input:** "Subscribe to my channel for more content!"
    **Output:** "اشتركوا في القناة عشان يوصلكم كل جديد!"

    ```bash theme={null}
        curl -X POST https://api.trynawa.com/v1/translate \
          -H "Authorization: Bearer nawa_test_sk_xxx" \
          -H "Content-Type: application/json" \
          -d '{"text": "Subscribe to my channel for more content!", "source": "en", "target": "ar", "dialect": "egyptian", "tone": "social_media", "platform": "youtube"}'
    ```
  </Accordion>

  <Accordion title="Arabic to English (formal)">
    **Input:** "وش رايكم بالمحتوى الجديد؟"
    **Output:** "What do you think of the new content?"

    ```bash theme={null}
        curl -X POST https://api.trynawa.com/v1/translate \
          -H "Authorization: Bearer nawa_test_sk_xxx" \
          -H "Content-Type: application/json" \
          -d '{"text": "وش رايكم بالمحتوى الجديد؟", "source": "ar", "target": "en", "tone": "formal"}'
    ```
  </Accordion>

  <Accordion title="MSA to Gulf Arabic dialect conversion">
    **Input:** "كيف حالك اليوم؟" (MSA)
    **Output:** "شلونك اليوم؟" (Gulf)

    ```bash theme={null}
        curl -X POST https://api.trynawa.com/v1/translate \
          -H "Authorization: Bearer nawa_test_sk_xxx" \
          -H "Content-Type: application/json" \
          -d '{"text": "كيف حالك اليوم؟", "source": "ar", "target": "ar", "dialect": "gulf", "tone": "casual"}'
    ```
  </Accordion>
</AccordionGroup>

### Error responses

| Status | Type                    | When                                                                  |
| ------ | ----------------------- | --------------------------------------------------------------------- |
| 400    | `invalid_request_error` | Missing `text`, `source`, or `target`. Invalid values. Text too long. |
| 401    | `authentication_error`  | Invalid or missing API key                                            |
| 402    | `insufficient_credits`  | No credits remaining                                                  |
| 429    | `rate_limit_error`      | Rate limit exceeded                                                   |
| 500    | `api_error`             | Internal or provider error                                            |