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

# Localização e i18n

> Traduza mensagens por idioma do contato em SMS, e-mail, WhatsApp e outros canais na mesma requisição.

<Tip>
  **Localização** escolhe o idioma de cada destinatário. Você manda um conceito; a Notifique entrega o texto certo para quem prefere português, inglês ou outro idioma.
</Tip>

## O que são `localization` e `i18n`?

Na raiz do body de envio (ou em **Enviar por template**), use:

* **`localization`** — como traduzir (`mode`, `sourceLocale` opcional)
* **`i18n`** — mapa **locale → texto** (string simples ou objeto com chaves por campo)

O idioma de cada pessoa vem do **cadastro do contato** (`language` / preferências). Se não houver match, a API usa fallback (texto fonte ou primeiro locale disponível).

## Modos (`localization.mode`)

| `mode`   | Comportamento                                                      |
| -------- | ------------------------------------------------------------------ |
| `off`    | Sem tradução automática (padrão quando omitido)                    |
| `manual` | Você envia todas as traduções em `i18n`                            |
| `ai`     | A Notifique traduz do texto fonte com IA (consome uso de tradução) |

`localization.sourceLocale` (opcional) indica o idioma do texto em `payload` quando usa `manual` ou `ai`.

## Formato de `i18n`

**Texto simples** (SMS, Telegram, etc.):

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

**Vários campos** (e-mail, push, WhatsApp, **voz**):

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

**Voz** (`speakText` falado + prompt de DTMF):

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

Chaves comuns por canal: `message`, `caption`, `subject`, `html`, `text`, `title`, `body`, `speakText`, `gatherPrompt`. Veja a referência OpenAPI do canal para a lista exata.

## Resposta **202**

Quando `localization.mode` é `manual` ou `ai`, a resposta pode incluir `data.localization` com metadados (`appliedAiLocales`, `fallbackLocales`, etc.). No SMS, destinatários pulados por política de tamanho podem aparecer em `data.smsSkippedRecipients`.

## Onde usar na API v1

| Canal     | Rota                         | Notas                                                                        |
| --------- | ---------------------------- | ---------------------------------------------------------------------------- |
| SMS       | `POST /v1/sms/messages`      | `message` em `i18n`                                                          |
| E-mail    | `POST /v1/email/messages`    | `subject`, `html`, `text`                                                    |
| RCS       | `POST /v1/rcs/messages`      | Campos do `type` enviado                                                     |
| Push      | `POST /v1/push/messages`     | `payload.title`, `payload.body` (e `i18n` por locale)                        |
| WhatsApp  | `POST /v1/whatsapp/messages` | Texto e mídia; **não** use `ai` em template **oficial** Meta                 |
| Telegram  | `POST /v1/telegram/messages` | Texto e caption                                                              |
| Templates | `POST /v1/templates/send`    | Tradução na hora + `localeTranslations` no CRUD do template                  |
| Instagram | Envio direto                 | Sem `localization` no POST — use bloco `instagram` no template ou texto fixo |
| Voz       | `POST /v1/voice/calls`       | `speakText` e `gatherPrompt` em `i18n`; `type: speak` ou `gather`            |

## Variáveis e placeholders

`variables` na raiz (ou `payload.variables` em template) substituem `{{name}}` **depois** da escolha do locale. Guia: [Variáveis disponíveis](/template-api/como-funciona/variaveis-disponiveis-e-crud).

## Erros comuns

| `code`                                            | Quando                                   |
| ------------------------------------------------- | ---------------------------------------- |
| `LOCALIZATION_TOO_MANY_LOCALES`                   | Excesso de locales em `i18n`             |
| `LOCALIZATION_AI_NOT_SUPPORTED_OFFICIAL_TEMPLATE` | `ai` em template WhatsApp oficial (Meta) |

Catálogo completo: [Respostas de erro](/guides/conceitos/resposta-de-erros).

## Exemplo (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}}!"
  }
}
```

## Próximos passos

* [SMS — Introdução](/sms-api/como-funciona/introducao): detalhes de `speed` e `smsSkippedRecipients`
* [Enviar por template](/template-api/api-reference/api-reference): `localization` multicanal
* [Variáveis e CRUD de templates](/template-api/como-funciona/variaveis-disponiveis-e-crud): `localeTranslations` no painel/API