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

# Localization and i18n

> Translate messages per contact language on SMS, email, WhatsApp, and other channels in a single request.

<Tip>
  **Localization** picks each recipient’s language. You send one intent; Notifique delivers the right text for Portuguese, English, or other preferences.
</Tip>

## What are `localization` and `i18n`?

At the root of the send body (or on **Send by template**), use:

* **`localization`** — how to translate (`mode`, optional `sourceLocale`)
* **`i18n`** — map **locale → text** (plain string or object with field keys)

Each person’s language comes from the **contact record** (`language` / preferences). If there is no match, the API falls back to the source text or the first available locale.

## Modes (`localization.mode`)

| `mode`   | Behavior                                                                   |
| -------- | -------------------------------------------------------------------------- |
| `off`    | No automatic translation (default when omitted)                            |
| `manual` | You send every translation in `i18n`                                       |
| `ai`     | Notifique translates from the source text with AI (uses translation quota) |

Optional `localization.sourceLocale` marks the language of the text in `payload` when using `manual` or `ai`.

## `i18n` format

**Plain text** (SMS, Telegram, etc.):

```json theme={null}
"i18n": {
  "pt-BR": "Olá, Maria!",
  "en": "Hello, Maria!"
}
```

**Multiple fields** (email, push, WhatsApp, **voice**):

```json theme={null}
"i18n": {
  "pt-BR": { "subject": "Pedido confirmado", "html": "<p>Olá</p>" },
  "en": { "subject": "Order confirmed", "html": "<p>Hello</p>" }
}
```

**Voice** (spoken `speakText` + DTMF prompt):

```json theme={null}
"i18n": {
  "en": {
    "speakText": "Hello! Your delivery arrives today.",
    "gatherPrompt": "Press 1 to confirm."
  }
}
```

Common keys per channel: `message`, `caption`, `subject`, `html`, `text`, `title`, `body`, `speakText`, `gatherPrompt`. See the channel OpenAPI reference for the exact list.

## **202** response

When `localization.mode` is `manual` or `ai`, the response may include `data.localization` metadata (`appliedAiLocales`, `fallbackLocales`, etc.). On SMS, skipped recipients due to length policy may appear in `data.smsSkippedRecipients`.

## Where to use in API v1

| Channel   | Route                        | Notes                                                                            |
| --------- | ---------------------------- | -------------------------------------------------------------------------------- |
| SMS       | `POST /v1/sms/messages`      | `message` in `i18n`                                                              |
| Email     | `POST /v1/email/messages`    | `subject`, `html`, `text`                                                        |
| RCS       | `POST /v1/rcs/messages`      | Fields for the sent `type`                                                       |
| Push      | `POST /v1/push/messages`     | `payload.title`, `payload.body` (and `i18n` per locale)                          |
| WhatsApp  | `POST /v1/whatsapp/messages` | Text and media; **do not** use `ai` on **official** Meta templates               |
| Telegram  | `POST /v1/telegram/messages` | Text and caption                                                                 |
| Templates | `POST /v1/templates/send`    | Runtime translation + `localeTranslations` on template CRUD                      |
| Instagram | Direct send                  | No `localization` on POST — use the `instagram` block on templates or fixed text |
| Voice     | `POST /v1/voice/calls`       | `speakText` and `gatherPrompt` in `i18n`; `type: speak` or `gather`              |

## Variables and placeholders

Root `variables` (or `payload.variables` on templates) replace `{{name}}` **after** locale selection. Guide: [Available variables](/en/template-api/como-funciona/variaveis-disponiveis-e-crud).

## Common errors

| `code`                                            | When                                       |
| ------------------------------------------------- | ------------------------------------------ |
| `LOCALIZATION_TOO_MANY_LOCALES`                   | Too many locales in `i18n`                 |
| `LOCALIZATION_AI_NOT_SUPPORTED_OFFICIAL_TEMPLATE` | `ai` on official WhatsApp (Meta) templates |

Full catalog: [Error responses](/en/guides/conceitos/resposta-de-erros).

## Example (SMS, manual)

```json theme={null}
{
  "type": "text",
  "payload": { "message": "Hello, {{name}}!" },
  "to": ["5511999999999"],
  "variables": { "name": "Maria" },
  "localization": { "mode": "manual", "sourceLocale": "en" },
  "i18n": {
    "pt-BR": "Olá, {{name}}!",
    "en": "Hello, {{name}}!"
  }
}
```

## Next steps

* [SMS — Introduction](/en/sms-api/como-funciona/introducao): `speed` and `smsSkippedRecipients`
* [Send by template](/en/template-api/api-reference/api-reference): multichannel `localization`
* [Template variables and CRUD](/en/template-api/como-funciona/variaveis-disponiveis-e-crud): `localeTranslations` in the dashboard/API