Localization and i18n

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

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.):

"i18n": {
  "pt-BR": "Olá, Maria!",
  "en": "Hello, Maria!"
}

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

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

Voice (spoken speakText + DTMF prompt):

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

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.

Example (SMS, manual)

{
  "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: speed and smsSkippedRecipients
Send by template: multichannel localization
Template variables and CRUD: localeTranslations in the dashboard/API

API E-mail

E-mail

Domínios

E-mails recebidos

Localization and i18n

What are `localization` and `i18n`?

Modes (`localization.mode`)

`i18n` format

202 response

Where to use in API v1

Variables and placeholders

Common errors

Example (SMS, manual)

Next steps

​What are localization and i18n?

​Modes (localization.mode)

​i18n format

​202 response

​Where to use in API v1

​Variables and placeholders

​Common errors

​Example (SMS, manual)

​Next steps

What are `localization` and `i18n`?

Modes (`localization.mode`)

`i18n` format

202 response

Where to use in API v1

Variables and placeholders

Common errors

Example (SMS, manual)

Next steps