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

# Localización e i18n

> Traduzca mensajes por idioma del contacto en SMS, correo, WhatsApp y otros canales en una sola solicitud.

<Tip>
  **Localización** elige el idioma de cada destinatario. Usted envía una intención; Notifique entrega el texto correcto para quien prefiere portugués, inglés u otro idioma.
</Tip>

## ¿Qué son `localization` e `i18n`?

En la raíz del body de envío (o en **Enviar por plantilla**), use:

* **`localization`** — cómo traducir (`mode`, `sourceLocale` opcional)
* **`i18n`** — mapa **locale → texto** (string simple u objeto con claves por campo)

El idioma de cada persona viene del **registro del contacto** (`language` / preferencias). Si no hay coincidencia, la API usa fallback (texto fuente o primer locale disponible).

## Modos (`localization.mode`)

| `mode`   | Comportamiento                                                          |
| -------- | ----------------------------------------------------------------------- |
| `off`    | Sin traducción automática (predeterminado si se omite)                  |
| `manual` | Usted envía todas las traducciones en `i18n`                            |
| `ai`     | Notifique traduce del texto fuente con IA (consume cuota de traducción) |

`localization.sourceLocale` (opcional) indica el idioma del texto en `payload` cuando usa `manual` o `ai`.

## Formato de `i18n`

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

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

**Varios campos** (correo, 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` hablado + prompt DTMF):

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

Claves comunes por canal: `message`, `caption`, `subject`, `html`, `text`, `title`, `body`, `speakText`, `gatherPrompt`. Vea la referencia OpenAPI del canal para la lista exacta.

## Respuesta **202**

Cuando `localization.mode` es `manual` o `ai`, la respuesta puede incluir `data.localization` con metadatos (`appliedAiLocales`, `fallbackLocales`, etc.). En SMS, destinatarios omitidos por política de longitud pueden aparecer en `data.smsSkippedRecipients`.

## Dónde usar en API v1

| Canal      | Ruta                         | Notas                                                                         |
| ---------- | ---------------------------- | ----------------------------------------------------------------------------- |
| SMS        | `POST /v1/sms/messages`      | `message` en `i18n`                                                           |
| Correo     | `POST /v1/email/messages`    | `subject`, `html`, `text`                                                     |
| RCS        | `POST /v1/rcs/messages`      | Campos del `type` enviado                                                     |
| Push       | `POST /v1/push/messages`     | `payload.title`, `payload.body` (y `i18n` por locale)                         |
| WhatsApp   | `POST /v1/whatsapp/messages` | Texto y media; **no** use `ai` en plantilla **oficial** Meta                  |
| Telegram   | `POST /v1/telegram/messages` | Texto y caption                                                               |
| Plantillas | `POST /v1/templates/send`    | Traducción al enviar + `localeTranslations` en CRUD                           |
| Instagram  | Envío directo                | Sin `localization` en POST — use bloque `instagram` en plantilla o texto fijo |
| Voz        | `POST /v1/voice/calls`       | `speakText` y `gatherPrompt` en `i18n`; `type: speak` o `gather`              |

## Variables y placeholders

`variables` en la raíz (o `payload.variables` en plantilla) sustituyen `{{name}}` **después** de elegir el locale. Guía: [Variables disponibles](/es/template-api/como-funciona/variaveis-disponiveis-e-crud).

## Errores comunes

| `code`                                            | Cuándo                                    |
| ------------------------------------------------- | ----------------------------------------- |
| `LOCALIZATION_TOO_MANY_LOCALES`                   | Demasiados locales en `i18n`              |
| `LOCALIZATION_AI_NOT_SUPPORTED_OFFICIAL_TEMPLATE` | `ai` en plantilla WhatsApp oficial (Meta) |

Catálogo completo: [Respuestas de error](/es/guides/conceitos/resposta-de-erros).

## Ejemplo (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 pasos

* [SMS — Introducción](/es/sms-api/como-funciona/introducao): detalles de `speed` y `smsSkippedRecipients`
* [Enviar por plantilla](/es/template-api/api-reference/api-reference): `localization` multicanal
* [Variables y CRUD de plantillas](/es/template-api/como-funciona/variaveis-disponiveis-e-crud): `localeTranslations` en panel/API