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

# Localized messages

> Write push messages in multiple languages and connect localized popup templates to campaigns and user journeys.

Send push notifications or show popups in multiple languages within a single campaign or user journey. If no version matches the user's language, Notifly uses the default.

## Supported channels

* App push
* Web push
* In-app popups
* Web popups

> [!NOTE]
>
> Localized messages must be enabled for your project.

## 1. Enable localized messages

Choose where you want to set up localized messages.

### Campaigns

1. On the campaign creation page, select **App Push**, **Web Push**, **In-App Popup**, or **Web Popup**.
2. Open **Advanced Settings**.
3. Turn on **Use localized messages**.

### User journeys

1. Add a message node or open an existing one.
2. Select **App Push**, **Web Push**, **In-App Popup**, or **Web Popup**.
3. Turn on **Use localized messages**.

The editor now shows a **Default** tab.

## 2. Write push messages

For app and web push, write the default message and the messages for each language directly in the editor.

### 2-1. Write the default message

In **Default**, enter the title and body to send when none of the localized versions matches the user's language.

Make sure recipients can understand the default message and take the intended action.

### 2-2. Add a language

1. Select **Add language**.
2. In **Search languages**, enter a code such as `ja` or a language name shown in the list, such as 日本語.
3. Choose a language.
4. Enter the message to send in that language.

A check mark means the message is complete. An exclamation mark means a required field is missing or the Liquid syntax is invalid.

### 2-3. Auto-fill translation drafts

Use the default message as the source for the translation drafts.

1. Enter the default title and message content.
2. Add the languages you want to translate into.
3. Select **Auto-fill N languages**. The number on the button shows how many languages will be filled.
4. Review and edit the translations.

Auto-fill leaves any titles or message text you’ve already entered in place and fills only empty fields.

> [!WARNING]
>
> The generated translations are drafts. Before saving, check the brand wording, variable placement, links, and Liquid syntax.

### 2-4. Write promotional messages

> [!WARNING]
>
> Localized messages do not automatically handle promotional message requirements.
>
> Add the required advertising disclosures and opt-out instructions to each language version. The sender is responsible for compliance with applicable law.

## 3. Connect popup templates

Popup localization uses templates you create in advance.

1. Create a popup template for each language you plan to use.
   * In-app popup: [Create an in-app popup template](https://docs.notifly.tech/en/user-guide/channel/in-app-message/guide.md#3-set-the-message)
   * Web popup: [Create a web popup template](https://docs.notifly.tech/en/user-guide/channel/web-message/guide.md#1-build-a-popup-template)
2. Under **Default**, select the popup template to show by default.
3. Select **Add language**, then choose a language.
4. Select the added language, then choose the template you created for it.

If no template matches the user's language, Notifly shows the template selected under **Default**. Popup templates are not translated automatically.

## 4. Set a user's language

By default, Notifly checks the user's `$locale` first, then the last observed locale (`$last_observed_locale`). For each value, it looks for a match on the full code, then on the language subtag. If neither value matches, it uses the default message or popup template.

If your service lets users choose a language, save their choice in `$locale`.

### 4-1. Save `$locale`

When a user signs in or changes their language, call the Notifly SDK's `setUserProperties` method to save `$locale`.

> [tab] Android
>
> ```kotlin theme={null}
> Notifly.setUserProperties(
>     context,
>     mapOf("\$locale" to "zh-TW")
> )
> ```

> [tab] iOS
>
> ```swift theme={null}
> Notifly.setUserProperties(
>     userProperties: ["$locale": "zh-TW"]
> )
> ```

> [tab] JavaScript
>
> ```javascript theme={null}
> notifly.setUserProperties({
>   "$locale": "zh-TW",
> });
> ```

> [tab] React Native
>
> ```javascript theme={null}
> notifly.setUserProperties({
>   "$locale": "zh-TW",
> });
> ```

> [tab] Flutter
>
> ```dart theme={null}
> await NotiflyPlugin.setUserProperties({
>   r'$locale': 'zh-TW',
> });
> ```

To set the language immediately after sign-in, identify the user with `setUserId` before calling `setUserProperties`. Save `$locale` again whenever the user changes their language in the app or website.

For SDK-specific instructions, see the [Android SDK](https://docs.notifly.tech/en/developer-guide/android-sdk.md), [iOS SDK](https://docs.notifly.tech/en/developer-guide/ios-sdk.md), [JavaScript SDK](https://docs.notifly.tech/en/developer-guide/javascript-sdk.md), [React Native SDK](https://docs.notifly.tech/en/developer-guide/react-native-sdk.md), and [Flutter SDK](https://docs.notifly.tech/en/developer-guide/flutter-sdk.md) guides.

### 4-2. Language code format

Store a BCP 47 language code in `$locale`. Use the same code as the language you added in the message editor.

| Language | Recommended code |
| - | - |
| Korean | `ko` |
| English | `en` |
| Japanese | `ja` |
| French | `fr` |
| Simplified Chinese | `zh-CN` |
| Traditional Chinese | `zh-TW` |

You can include a region, as in `en-US`, `ko-KR`, or `ja-JP`. For example, if `$locale` is `en-US`, Notifly looks for an `en-US` message first, then an `en` message.

> [!WARNING]
>
> For Chinese, use the codes supported in the message editor.
>
> * Simplified Chinese uses `zh-CN`.
> * Traditional Chinese uses `zh-TW`.
> * Avoid `zh-Hans`, `zh-Hant`, and `zh-Hans-TW` for these messages.
>
> `zh-Hans` and `zh-Hant` are valid BCP 47 language tags. They do not directly match Notifly's current Chinese message codes.

### 4-3. Language selection examples

These examples assume that `$last_observed_locale` is not set.

| `$locale` | Available localized message | Message sent |
| - | - | - |
| `ko` | `ko` | Korean |
| `ko-KR` | `ko` | Korean |
| `en-US` | `en` | English |
| `zh-CN` | `zh-CN` | Simplified Chinese |
| `zh-TW` | `zh-TW` | Traditional Chinese |
| `zh-Hant` | `zh-TW` | Default message |
| `ja` | No Japanese message | Default message |
| No `$locale` or `$last_observed_locale` | Not applicable | Default message |

## 5. Check before sending

### Push notifications

* Make sure recipients can understand the default message on its own.
* Check that all added languages show a check mark.
* Review the Liquid variables, images, and links for each language.
* If you used auto-fill, review the wording and placement of variables.
* For promotional messages, check the advertising disclosures and opt-out instructions for each language.

### Popups

* Check that you selected the correct template for **Default** and every language you added.
* Check the copy, images, buttons, and links in each template.

For both push and popups, check that the language codes stored on user profiles match the languages you added.

### A/B test campaigns

You can use localized messages in an A/B test. Write push messages or select popup templates for each language within each test group. The control group receives no message.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.