Multi-language messaging
Send messages in different languages with OneSignal.
You can send multi-language messages across all channels in OneSignal. Depending on the channel, there are different implementation methods available.
Set user's language
The language
property is set automatically by our Frontend SDKs based on the device's language setting when the user is first created.
You can set or update this property by passing in the ISO 639-1 language code to:
- our SDK's
setLanguage
method. - the
language
property on the Create user or Update user APIs. - the
language
property on our CSV Importer.
Self-managed language and content (API only)
If you store / manage the language of your users outside of OneSignal, you can create already-translated versions of messages and send them individually to each customer. You can send a translated message through the Create notification endpoint.
API custom_data
property
custom_data
propertyUsing Templates and the Create notification endpoint, you can pass in the user's language via the custom_data
parameter and reference it in the template via Liquid syntax. The below example shows how you can set up the template and pass the customer's custom_data
language and conditionally check for the language using liquid syntax.
{% if message.custom_data.language == "en" %}
Hello, {{ first_name }}!
{% elsif message.custom_data.language == "fr" %}
Bonjour {{ first_name }}!
{% else %}
Hi, {{ first_name }}!
{% endif %}
request.body = "{\"custom_data\":{\"language\":\"fr\"}"
Bonjour George!
Push
Send push notifications in different languages with the options below. Variable substitution using properties and tags is also available. See Message Personalization for details on variable substitution.
Dashboard sending
If you have a CSV of languages, you can also use Dynamic Content.
The OneSignal dashboard and API set "English" as the default language, but use any language you need in this field. Think of "English" as Default. For example, if you enter a Spanish message into the "Any/English" field, then all users will get the notification in Spanish.
To send a message in multiple languages, select Add Languages or Edit Language.
You must provide the translation for each message you want to include.
Note on RTL languages like Arabic and Hebrew
The dashboard uses a very standard HTML text area form field for this input.
Certain punctuation and special characters like
%
are handled in a unique way and may require RLM marks after these characters to fix any issues you may see.
There are two methods for language selection:
- Checkboxes: Best for sending in 1-3 languages. Select the languages you want to use in the push. Any languages you do not select will get the "Any/English" message.
- Import Language Content: Best for populating the editor with 2+ or many languages. Fill out the template provided with content for each language, copy and paste the content back into the "Add Languages" pop-up, preview content to double-check, insert content, and new tabs will appear in the editor with the designated content filled out.
Troubleshooting language uploader
Default language or English Required
When copying and pasting languages into the text field, English (which acts as default) must be included as a row in order to proceed.
Formatting Issue
If met with an error, ensure you've included the header properties as the first line (copy and paste from the template). Another common reason is if the contents are not formatted properly. Ensure there is a comma between each of the header properties ("language_code", "title", "subtitle", "message").
Unsupported Languages
While we support many languages, there are some we don't support yet. If the language code is not included in the pop-up and CSV template, then this language is not supported. We recommend using the next best language and sending us a product request to [email protected]
API
The API headings
and contents
properties both allow multiple language codes to be set. If a device is set to a language that is not present in the contents
property, then the content in en
will be used.
For example, if the receiving device's language is de
and you send the notification with only en
and fr
language codes for contents
and headings
, the notification the device receives will use the values of contents
and headings
in the en
language code.
// Devices with "de" language code will receive "en" for contents and headings
// because "de" is not specified
{
"contents": {"en": "English content", "fr": "French content"},
"headings": {"en": "English heading", "fr": "French heading"}
}
Note: Make sure that you are including the same set of language codes for each field.
If the language code set in contents
is not present in headings
, then the title ("heading") will not display.
For example, if the receiving device's language is de
and you send the notification with en
, ru
and de
for contents
, but send only en
for headings
, then the titles for that notification will not display for any device with a language code of de
and ru
.
// Devices with "de" & "ru" language code will not display headings
// because "de" & "ru" are not specified
{
"contents": {"en": "English content", "ru": "Russian content", "de": "German content"},
"headings": {"en": "English content"}
}
Email
To send multi-language Emails via the dashboard, you will need to choose one of the following approaches:
- If you have a CSV of languages, you can also use Dynamic Content
- Use Segments with Language and send messages to each segment, or
- Use property substitution with Liquid syntax to create conditional statements in a message
Right-to-Left Text Support in Email
Because text alignment is set in the email styling, sending right-to-left text and left-to-right messages using the same template may be challenging to accomplish, though not impossible.
You might want to either rely on the the recipient's computer to manage right-to-left text display, segment users who need to receive right-to-left messages, or conditionally change the styling through custom HTML & CSS.
Dashboard - Segment Audience
To send a language-specific Email to each language you need to support:
- Create a Segment for each language.
- Create an Email template for each language.
- Send your Email for each language by selecting the Segment and template for that language.
Dashboard - Conditionally Check Language with Liquid
Use Liquid Syntax to add conditional logic in the body of a message to render content in several languages. You can use the language code {{ user.language }}
, or set a Data Tag on the user to provide the language value.
When using an if/else
statement for multi-language messages, always include your default language last in the final else
statement.
For example, if you want to use English as your default language, use an if
statement to check if the user's language matches all defined languages before defaulting to English. This template example will render into three languages depending on the recipient's language code or Data Tag for {{ language }}
.
{% assign userLang = user.language %}
{% if userLang == 'es' %}
Hola {{ first_name }}!
{% elsif userLang == 'fr' %}
Bonjour {{ first_name }}!
{% else %}
Hello {{ first_name }}!
{% endif %}
API
When calling the Create notification API endpoint, you can specify custom_data
to use in Liquid syntax. You can use data added to the notification to show conditional multi-language content as demonstrated above in "Dashboard - Conditionally Check Language with Liquid".
Make sure to accurately reference the source of your data in your Liquid tags.
{% if message.custom_data.language == "fr" %}
Bonjour {{ name }}
{% elsif message.custom_data.language == "en" %}
Hola {{ name }}
{% else %}
Hello {{ name }}
{% endif %}
{
"app_id": "5eb5a37e-b458-11e3-ac11-000c2940e62c",
"template_id": "45d24a11-f739-4878-a15c-f32535547e90",
"include_email_tokens": ["[email protected]", "[email protected]"],
"custom_data": {
"language": "fr",
"cart_items": [
{"item_name": "sweater", "img_url": "https://.."},
{"item_name": "socks", "img_url": "https://.."}
]
}
}
Bonjour George
In-app messages
Send in-app messages in different languages using segments or tag variable substitution. If using tag variable substitution, you will need to set the language as a data tag. See Message Personalization for details on variable substitution.
Variable substitution using properties is coming soon. Reach out to [email protected] to submit a feature request.
Dashboard - Segment Audience
To send a language-specific In-App Message to each language you need to support:
- Create a Segment for each language.
- Create an In-App Message for each language.
- Send your In-App Message for each language by selecting the Segment for that language.
Tag Variable Substitution
In this example, we set the tag key language
to a specific language like german
, spanish
, french
and default to English with if-else statements Using Liquid Syntax.
{% assign lang = language%}
{% if lang == "english" %}
Good day {{first_name}}!
{%- elsif lang == 'german' -%}
Guten Tag {{first_name}}!
{%- elsif lang == 'spanish' -%}
Buenos Dias {{first_name}}!
{%- elsif lang == 'french' -%}
Bonjour {{first_name}}!
{% else %}
Hello {{first_name}}!
{% endif %}
language : german
first_name : Jon
Guten Tag Jon!
Supported Languages
Language_code
is a user property in the ISO 639-1 code 2-letter format. We support the following language codes:
Language | Language Code |
---|---|
English | en |
Arabic | ar |
Azerbaijani | az |
Bosnian | bs |
Catalan | ca |
Chinese (Simplified) | zh-Hans |
Chinese (Traditional) | zh-Hant |
Croatian | hr |
Czech | cs |
Danish | da |
Dutch | nl |
Estonian | et |
Finnish | fi |
French | fr |
Georgian | ka |
Bulgarian | bg |
German | de |
Greek | el |
Hindi | hi |
Hebrew | he |
Hungarian | hu |
Indonesian | id |
Italian | it |
Japanese | ja |
Korean | ko |
Latvian | lv |
Lithuanian | lt |
Malay | ms |
Norwegian | nb |
Persian | fa |
Polish | pl |
Portuguese | pt |
Punjabi | pa |
Romanian | ro |
Russian | ru |
Serbian | sr |
Slovak | sk |
Spanish | es |
Swedish | sv |
Thai | th |
Turkish | tr |
Ukrainian | uk |
Vietnamese | vi |
Updated about 3 hours ago