Multi-language Messaging
You can send multi-language messages across most channels in OneSignal. The best way to send a multi-language message varies based on the channel:
Channel | Sending Method |
---|---|
Push | Dashboard using Segments, Dashboard using language_code , Google Sheets Extension, API Create Notification |
Dashboard using Segments, Dashboard using Data Tags, API Create Notification using Data Tags | |
In-App Messages | Dashboard using Segments |
SMS | Dashboard using Segments, Google Sheets Extension, API Create Notification |
Set User's Language
The ways to define a user's language include:
- Set the user's preferred language using one of our SDKs
- Specify
language_code
in an API request - Use Data Tags, or
custom_data
, to indicate the user's language preference
SDK setLanguage Method
The OneSignal SDK will automatically detect the language of the device or browser settings when it is initialized. You can also manually update the language for a user.
Set the language for the user using an ISO 639-1 language code.
OneSignal.getUser().setLanguage("en");
OneSignal.User.setLanguage("en")
[OneSignal.User setLanguage:@"en"]
OneSignal.User.setLanguage("en")
Update User API
Update the User's language with the Update user endpoint using an ISO 639-1 language code.
request.body = "{\"properties\":{\"language\":\"fr\"}"
Data Tags
Instead of using the language code for a user, you can use Data Tags to store a language value. Using Liquid Syntax you can add conditional statements that check for properties like a Data Tags to show content conditionally.
This option is available if you're not able to use the user's language_code
or would prefer to use a country or region to define the language. However, we still recommend using the official User language_code
for multi-language and localized messages if possible.
{% if language_code = "en" %}
english content
{% elsif language_code == "fr" %}
french content
{% else %}
abc content
{% endif %}
language_code: "xyz"
abc content
When sending a message template through the Create notification endpoint, you can use the custom_data
parameter that can be referenced via Liquid syntax like a Data Tag. You can pass through the customer's 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\":{\"country\":\"fr\"}"
Bonjour George!
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. See also: Internal Database, DMP, & CRM
Push
Dashboard Sending
The OneSignal dashboard and API makes "English" 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.
OneSignal will show how many subscribers have each language.
Select the languages you want to use in the push. Any languages you do not select will get the "Any/English" message.
You must provide the translation for each message you want to include.
Google Sheets Extension
Google Sheets Extension allows you to store message templates as a spreadsheet to send the message directly from the Google sheet.
Follow the steps outlined in Google Sheets Extension to compose and send your message.
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
, fr
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 fr
.
// Devices with "de" & "fr" language code will not display headings
// because "de" & "fr" are not specified
{
"contents": {"en": "English content", "fr": "French 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:
- Use segments with Language or Data Tags filters and send messages to each segment, or
- Use Data Tags 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
language_code
is not supported in email contentWe're working to add support for using a user's
language_code
in Liquid syntax in email content in the future. Until then, you will have to use Data Tags as a substitute.
Use Liquid Syntax to add conditional logic in the body of a message to render content in several languages. Use a Data Tag on the user like {{ language }}
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 Data Tag for {{ language }}
.
{% if language == "fr" %}
Bonjour {{ name }}
{% elsif language == "es" %}
Hola {{ name }}
{% else %}
Hello {{ 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 notifcation 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
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.
Supported Languages
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 4 days ago