Localization

Send one notification in several languages and control which translation each user sees.

A notification's contents is keyed by locale. Each user gets the best available translation when their feed loads. More than one locale needs the Growth plan and up (see plan features).

{
  "audience": { "type": "all" },
  "defaultLocale": "en",
  "contents": {
    "en": { "title": "Scheduled maintenance on Sunday", "body": "Expect up to 10 minutes of downtime." },
    "de": { "title": "Wartung am Sonntag", "body": "Rechne mit bis zu 10 Minuten Ausfallzeit." },
    "pt-BR": { "title": "Manutenção programada no domingo" }
  }
}

Rules

• 1 to 50 locales per notification.
• Keys are BCP 47 language tags: a 2 or 3 letter language, optionally followed by subtags, such as en, de-AT, pt-BR or zh-Hant-TW. Matching is case-insensitive.
• Each locale has its own title (required, up to 200 characters), body (up to 2,000) and actionLabel (up to 60). actionUrl, imageUrl, category and data are shared by all locales.
• defaultLocale defaults to the project's default locale. If contents has no entry for it, the first locale in contents becomes the default.

Which translation a user sees

The feed tries, in order, the requested locale (the locale query parameter, which the SDKs send from their locale option), then the project user's locale (from their profile). For each of those it looks for:

1. an exact match: de-AT → de-AT;
2. the language: de-AT → de;
3. a regional sibling: de-AT → de-DE, or pt → pt-BR.

If none of those exist, it uses the notification's default locale.

Each feed item's locale field tells you which translation was used, which is handy for formatting dates in the same language as the text.

Setting the user's locale

• From the SDK: pass the UI language as the SDK's locale option. It is sent with every feed request. In React and React Native, changing the provider's locale prop reloads the feed in the new language; with the JavaScript client, create a new client. The SDKs don't detect the device or browser language on their own.
• On the profile: send locale in the SDK's user profile, or set it from your backend with PUT /v1/project-users/{userId}. The profile locale is also available to segments and as {{user.locale}} in templates.

UI strings

The SDKs' built-in strings ("Notifications", "Mark all as read", empty states) are configured separately through their labels option. Relative times ("5 minutes ago") are formatted with Intl.RelativeTimeFormat in each item's own locale. See the SDK pages.