Getting started
UpdatedYou can store your audience’s language preferences as an attribute, and then use that attribute to send people messages in their preferred language!
How it works
To localize messages:
- Set a language attribute for your audience.
- Create messages with language variants.
When you add or update people, you can set an attributeA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. containing their language preference. Then, when you set up messages, you can click Add language to add one or more languages. You’ll set up your Default message, and then add content for each language.
When you send your message, people whose language attribute matches one of your message’s languages will receive the appropriate localization. Everybody else receives the Default message.
attribute] --> B[Set up
multi-language message] B --> C[Send
message] C --> D{Does a person's language
attribute match a language variant?} D -->|no| H[Person gets
default message] D -->|yes, lang=es| E[Person gets
Spanish message] D -->|yes, lang=fr| F[Person gets
French message] D -->|yes, lang=de| G[Person gets
German message]
Multi-language support
Campaign/Message Type | SMS | Push | In-App | |
---|---|---|---|---|
Campaigns | ✅ | ✅ | ✅ | ✅ |
Broadcasts (Newsletters & API-triggered broadcasts) | ✅ | ✅ | ✅ | ✅ |
Transactional messages | ✅ | ✅ | ✅ |
1. Set your language attribute
Before you can send localized messages, you need to go to Workspace Settings > Language settings and tell us what attributeA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. stores your audience’s language preferences. This attribute must store values we support, meaning they’re either:
- A two-letter language code, like
en
for English - A four-letter language and region code, separated by a dash, like
en-US
for English speakers in the United States


Go to Set up your localization attribute for more info.
2. Set up a multi-language message
When you create a message with multiple languages, you should always begin by drafting your Default message. This is the message intended for anybody who doesn’t match another language and should represent your “template” for other languages. You can add language variants to any message channel (email, SMS, Whatsapp, push, and in-app), but note it’s not natively supported yet in our Design Studio editor.
Across any message channel, you can leverage AI to translate your default content into other languages. Keep in mind, AI can make mistakes, so you should still have a person review your translations.
If you plan to send email content to a translation vendor, you’ll want to first set up then export your Default message. Check out our best practices for help exporting email messages for your translation vendor and the quickest way to add your multi-language content.
- Drag a message into your workflow, then click it to view settings.
- Set a Name for your message, and click Add Content.
- Click Add language then check the languages you want. If “Customer.io AI” is enabled on your account, we auto-translate your default message with AI. If you don’t want this, clear Auto-translate with AI. Then click Add.
- Draft your Default message. This message should act as a “template” for your other languages. It will be the fallback if your customers do not have a language attribute.
- If you leveraged our AI to translate your message, review the translation. Otherwise, add your content for each language. Use the tabs at the top of the message to switch between languages.
- Save your changes.
Translate with AI
We auto-translate your default message with AI when you add a language variant. If you don’t want this, clear Auto-translate with AI. This is available across all of our message channels, but is not currently available in our Design Studio editor for emails. Remember to review your translations for accuracy; generative AI can make mistakes.


Not seeing this AI feature?
Make sure “Customer.io AI” is enabled in Privacy & Data settings. Reach out to an Account Admin if you can’t edit the toggle.
We auto-translate:
- Body text
- Subject lines
We do not auto-translate:
- Images
- Snippets
- Email layouts
- Liquid
If you want to personalize translated messages with liquid, use liquid conditionals to target people’s language preferences.
Regenerate translations with AI
If you made a change to your default message and want translations to reflect the updates, you’ll need to delete the translations then re-add the language variants.
Retry failed AI translations
If a translation fails, you can click Retry in the failure notification to try again.


Languages we won’t auto-translate
This feature can auto-translate most languages we support, but check out the exceptions in our locale list.
If you select a locale that is not officially supported by our LLM, you’ll see that we won’t translate it:


In this example, both locales for Turkmen (tk) and Uzbek (uz) are selected, as indicated by the bubbles below the locale list. We will auto-translate Uzbek, but not Turkmen. After you click Add, new tabs appear for both languages. However, only Uzbek will show a translation. Turkmen would show a copy of the default message and still need to be translated by another service or vendor. Here are some tips for working with a translation vendor.
How to work with a translation vendor
Export email to HTML for vendors
When you set up a message with multiple languages, you may need to send content to a translation vendor. To simplify this process, we suggest that you draft, test, and finalize your Default message first.
We recommend you export emails to HTML before you send them to a translation vendor:
- If you created your email with the drag and drop editor, click Actions > Export to HTML.
- If you created your email with the rich text editor, click HTML underneath the email header to copy/paste the source code.
- If you used the code editor, you can copy your email out to a separate file.
Make sure your translation vendor handles raw HTML
While we suggest you export custom HTML, make sure that your translation team can translate raw HTML before you export your email or switch editors. Remember, when you switch editor types, you cannot switch back.
Add translations for email from vendors
To add a translation to your message:
- Click Add language.
- Select one or more languages to add.
- If you see the option, clear Auto-translate with AI.
- Then paste in the translation:
- If you exported your HTML originally, copy/paste the translated HTML back to the rich text (click HTML first) or code editors. If you used the rich text editor, you may need to reformat text after pasting.
- If you didn’t export your HTML, or you used the drag and drop editor, paste localized text back into the blocks of your message.
message] -.->F{Test message} A -.-> |Convert without testing| C[Convert to
Custom HTML] C --> D[Export and
send to translator] D -->|Get translations
back| E[Add languages] E --> G[Send message] F-.-> |Tests pass|C F-.-> |Tests fail|A
Use liquid conditionals to personalize translations
You might use liquidA syntax that supports variables, letting you personalize messages for your audience. For example, if you want to reference a person’s first name, you might use the variable {{customer.first_name}}
. to personalize your message for your audience. Liquid doesn’t account for translations; we use the values stored on people’s profiles. Therefore, you’ll want to store values in native languages or use a set of static values.
If using static values, request your vendor translate these, too. Then you can use if
statements to set specific, translated values depending on your audience’s language attribute.
{% if customer.language == 'fr' %}
Bonjour
{% elsif customer.language == 'es' %}
Hola
{% else %}
Hello // Default value
{% endif %}
Right-to-left text formatting
When editing emails or in-app messages, you can expand Advanced options for paragraphs and other elements that contain text and use the Text Direction setting to control for right-to-left or left-to-right text.


Mixing LTR and RTL text
When creating messages that mix right-to-left (RTL) languages like Arabic with left-to-right (LTR) languages like English in our email and in-app message editors, you may need to control the text direction to ensure proper display.
You can control text direction inline using Unicode directional formatting characters:
- RLE (Right-to-Left Embedding):
‫
- Place before Arabic text to embed it in a right-to-left context - PDF (Pop Directional Formatting):
‬
- Place after Arabic text to return to the previous directional context
Welcome to Customer.io! ‫مرحبا بك في كستمر.آي.أو‬ Let's get started.
Delete a language
When composing your message, you can remove languages that you add by mistake.
- Click the tab for the language you want to remove.
- Click .
- Confirm the action.
Removing a language means that people bearing the language code in their localization attribute will receive the default message.


Multi-language metrics
When you send a message with multiple languages, we show metrics for each language. These metrics can help you make sure that your messages perform well in all of your audience’s languages.


Supported languages and locales
You must format the values of your language attribute as two-letter language codes with an optional two-letter region
code separated by a dash, like en
or en-US
.
Language attribute values are not case sensitive, but language-region codes must be separated by a dash. For example,
both es-MX
and es-mx
represent Spanish formatted for speakers in Mexico.
These codes come from the ISO-3166-1 (alpha 2) and IETF standards respectively. If you’re looking for a language or locale that we don’t support, let us know!
Any code with an asterisk (*) is not officially supported by our auto-translate feature. You’ll have to use another service to get an accurate translation.
Code | Language/Locale |
af | Afrikaans |
af-ZA | Afrikaans (South Africa) |
am-ET | Amharic (Ethiopia) |
ar | Arabic |
ar-AE | Arabic (U.A.E.) |
ar-BH | Arabic (Bahrain) |
ar-DZ | Arabic (Algeria) |
ar-EG | Arabic (Egypt) |
ar-IQ | Arabic (Iraq) |
ar-JO | Arabic (Jordan) |
ar-KW | Arabic (Kuwait) |
ar-LB | Arabic (Lebanon) |
ar-LY | Arabic (Libya) |
ar-MA | Arabic (Morocco) |
ar-OM | Arabic (Oman) |
ar-QA | Arabic (Qatar) |
ar-SA | Arabic (Saudi Arabia) |
ar-SY | Arabic (Syria) |
ar-TN | Arabic (Tunisia) |
ar-YE | Arabic (Yemen) |
arn-CL* | Mapudungun (Chile) |
as-IN | Assamese (India) |
az | Azeri |
az-Cyrl-AZ | Azeri (Cyrillic) (Azerbaijan) |
az-Latn-AZ | Azeri (Latin) (Azerbaijan) |
ba-RU* | Bashkir (Russia) |
be | Belarusian |
be-BY | Belarusian (Belarus) |
bg | Bulgarian |
bg-BG | Bulgarian (Bulgaria) |
bn-BD | Bengali (Bangladesh) |
bn-IN | Bengali (India) |
bo-CN* | Tibetan (Peoples Republic of China) |
bi* | Bislama |
br-FR* | Breton (France) |
bs-Cyrl-BA | Bosnian (Cyrillic) (Bosnia and Herzegovina) |
bs-Latn-BA | Bosnian (Latin) (Bosnia and Herzegovina) |
ca | Catalan |
ca-ES | Catalan (Catalan) |
co-FR | Corsican (France) |
cs | Czech |
cs-CZ | Czech (Czech Republic) |
cy-GB | Welsh (United Kingdom) |
da | Danish |
da-DK | Danish (Denmark) |
de | German |
de-AT | German (Austria) |
de-CH | German (Switzerland) |
de-DE | German (Germany) |
de-LI | German (Liechtenstein) |
de-LU | German (Luxembourg) |
dsb-DE* | Lower Sorbian (Germany) |
dv | Divehi |
dv-MV | Divehi (Maldives) |
el | Greek |
el-GR | Greek (Greece) |
en | English |
en-029 | English (Caribbean) |
en-AT | English (Austria) |
en-AU | English (Australia) |
en-BE | English (Belgium) |
en-BZ | English (Belize) |
en-CA | English (Canada) |
en-DE | English (Germany) |
en-ES | English (Spain) |
en-FR | English (France) |
en-GB | English (United Kingdom) |
en-IE | English (Ireland) |
en-IN | English (India) |
en-JM | English (Jamaica) |
en-LU | English (Luxembourg) |
en-MY | English (Malaysia) |
en-NL | English (Netherlands) |
en-NZ | English (New Zealand) |
en-PH | English (Republic of the Philippines) |
en-SG | English (Singapore) |
en-TT | English (Trinidad and Tobago) |
en-US | English (United States) |
en-ZA | English (South Africa) |
en-ZW | English (Zimbabwe) |
es | Spanish |
es-AR | Spanish (Argentina) |
es-BO | Spanish (Bolivia) |
es-CL | Spanish (Chile) |
es-CO | Spanish (Colombia) |
es-CR | Spanish (Costa Rica) |
es-DO | Spanish (Dominican Republic) |
es-EC | Spanish (Ecuador) |
es-ES | Spanish (Spain) |
es-GT | Spanish (Guatemala) |
es-HN | Spanish (Honduras) |
es-LA | Spanish (Latin America) |
es-MX | Spanish (Mexico) |
es-NI | Spanish (Nicaragua) |
es-PA | Spanish (Panama) |
es-PE | Spanish (Peru) |
es-PR | Spanish (Puerto Rico) |
es-PY | Spanish (Paraguay) |
es-SV | Spanish (El Salvador) |
es-US | Spanish (United States) |
es-UY | Spanish (Uruguay) |
es-VE | Spanish (Venezuela) |
et | Estonian |
et-EE | Estonian (Estonia) |
eu | Basque |
eu-ES | Basque (Basque) |
fa | Persian |
fa-IR | Persian (Iran) |
fi | Finnish |
fi-FI | Finnish (Finland) |
fil-PH | Filipino (Philippines) |
fo* | Faroese |
fo-FO* | Faroese (Faroe Islands) |
fr | French |
fr-BE | French (Belgium) |
fr-CA | French (Canada) |
fr-CH | French (Switzerland) |
fr-FR | French (France) |
fr-LU | French (Luxembourg) |
fr-MC | French (Principality of Monaco) |
fy-NL | Frisian (Netherlands) |
ga-IE | Irish (Ireland) |
gd-GB | Scottish Gaelic (United Kingdom) |
gl | Galician |
gl-ES | Galician (Galician) |
gsw-FR* | Alsatian (France) |
gu | Gujarati |
gu-IN | Gujarati (India) |
ha-Latn-NG | Hausa (Latin) (Nigeria) |
he* | Hebrew |
he-IL* | Hebrew (Israel) |
hi | Hindi |
hi-IN | Hindi (India) |
hr | Croatian |
hr-BA | Croatian (Latin) (Bosnia and Herzegovina) |
hr-HR | Croatian (Croatia) |
hsb-DE* | Upper Sorbian (Germany) |
hu | Hungarian |
hu-HU | Hungarian (Hungary) |
hy | Armenian |
hy-AM | Armenian (Armenia) |
id | Indonesian |
id-ID | Indonesian (Indonesia) |
ig-NG | Igbo (Nigeria) |
ii-CN* | Yi (Peoples Republic of China) |
is | Icelandic |
is-IS | Icelandic (Iceland) |
it | Italian |
it-CH | Italian (Switzerland) |
it-IT | Italian (Italy) |
iu-Cans-CA* | Inuktitut (Syllabics) (Canada) |
iu-Latn-CA* | Inuktitut (Latin) (Canada) |
ja | Japanese |
ja-JP | Japanese (Japan) |
ka | Georgian |
ka-GE | Georgian (Georgia) |
kk | Kazakh |
kk-KZ | Kazakh (Kazakhstan) |
kl-GL* | Greenlandic (Greenland) |
km-KH | Khmer (Cambodia) |
kn | Kannada |
kn-IN | Kannada (India) |
ko | Korean |
ko-KR | Korean (Korea) |
kok* | Konkani |
kok-IN* | Konkani (India) |
ky | Kyrgyz |
ky-KG | Kyrgyz (Kyrgyzstan) |
la | Latin |
lb-LU | Luxembourgish (Luxembourg) |
lo-LA | Lao (Lao P.D.R.) |
lt | Lithuanian |
lt-LT | Lithuanian (Lithuania) |
lv | Latvian |
lv-LV | Latvian (Latvia) |
mi-NZ | Maori (New Zealand) |
mk | Macedonian |
mk-MK | Macedonian (Former Yugoslav Republic of Macedonia) |
ml-IN | Malayalam (India) |
mn | Mongolian |
mn-MN | Mongolian (Cyrillic) (Mongolia) |
mn-Mong-CN | Mongolian (Traditional Mongolian) (Peoples Republic of China) |
moh-CA* | Mohawk (Canada) |
mr | Marathi |
mr-IN | Marathi (India) |
ms | Malay |
ms-BN | Malay (Brunei Darussalam) |
ms-MY | Malay (Malaysia) |
mt-MT | Maltese (Malta) |
nb* | Norwegian (Bokmål) |
nb-NO* | Norwegian, Bokmål (Norway) |
ne-NP | Nepali (Nepal) |
nl | Dutch |
nl-BE | Dutch (Belgium) |
nl-NL | Dutch (Netherlands) |
nn-NO* | Norwegian, Nynorsk (Norway) |
no | Norwegian |
nso-ZA* | Sesotho sa Leboa (South Africa) |
oc-FR* | Occitan (France) |
or-IN | Oriya (India) |
pa | Punjabi |
pa-IN | Punjabi (India) |
pl | Polish |
pl-PL | Polish (Poland) |
prs-AF* | Dari (Afghanistan) |
ps-AF | Pashto (Afghanistan) |
pt | Portuguese |
pt-BR | Portuguese (Brazil) |
pt-PT | Portuguese (Portugal) |
qut-GT* | Kiche (Guatemala) |
quz-BO* | Quechua (Bolivia) |
quz-EC* | Quechua (Ecuador) |
quz-PE* | Quechua (Peru) |
rm-CH* | Romansh (Switzerland) |
ro | Romanian |
ro-RO | Romanian (Romania) |
ru | Russian |
ru-RU | Russian (Russia) |
rw-RW* | Kinyarwanda (Rwanda) |
sa* | Sanskrit |
sa-IN* | Sanskrit (India) |
sah-RU* | Yakut (Russia) |
se* | Sami (Northern) |
se-FI* | Sami (Northern) (Finland) |
se-NO* | Sami (Northern) (Norway) |
se-SE* | Sami (Northern) (Sweden) |
si-LK | Sinhala (Sri Lanka) |
sk | Slovak |
sk-SK | Slovak (Slovakia) |
sl | Slovenian |
sl-SI | Slovenian (Slovenia) |
sm | Samoan |
sma-NO* | Sami (Southern) (Norway) |
sma-SE* | Sami (Southern) (Sweden) |
smj-NO* | Sami (Lule) (Norway) |
smj-SE* | Sami (Lule) (Sweden) |
smn-FI* | Sami (Inari) (Finland) |
sms-FI* | Sami (Skolt) (Finland) |
so | Somali |
so-DJ | Somali (Djibouti) |
so-ET | Somali (Ethiopia) |
so-KE | Somali (Kenya) |
so-SO | Somali (Somalia) |
sq | Albanian |
sq-AL | Albanian (Albania) |
sr | Serbian |
sr-Cyrl-BA | Serbian (Cyrillic) (Bosnia and Herzegovina) |
sr-Cyrl-CS | Serbian (Cyrillic) (Serbia and Montenegro (Former)) |
sr-Cyrl-ME | Serbian (Cyrillic) (Montenegro) |
sr-Cyrl-RS | Serbian (Cyrillic) (Serbia) |
sr-Latn-BA | Serbian (Latin) (Bosnia and Herzegovina) |
sr-Latn-CS | Serbian (Latin) (Serbia and Montenegro (Former)) |
sr-Latn-ME | Serbian (Latin) (Montenegro) |
sr-Latn-RS | Serbian (Latin) (Serbia) |
sv | Swedish |
sv-FI | Swedish (Finland) |
sv-SE | Swedish (Sweden) |
sw | Kiswahili |
sw-KE | Kiswahili (Kenya) |
syr* | Syriac |
syr-SY* | Syriac (Syria) |
ta | Tamil |
ta-IN | Tamil (India) |
te | Telugu |
te-IN | Telugu (India) |
tg-Cyrl-TJ | Tajik (Cyrillic) (Tajikistan) |
th | Thai |
to* | Tonga (Tonga Islands) |
th-TH | Thai (Thailand) |
tk-TM* | Turkmen (Turkmenistan) |
tn-ZA* | Setswana (South Africa) |
tr | Turkish |
tr-TR | Turkish (Turkey) |
tt* | Tatar |
tt-RU* | Tatar (Russia) |
tzm-Latn-DZ* | Tamazight (Latin) (Algeria) |
ug-CN | Uyghur (Peoples Republic of China) |
uk | Ukrainian |
uk-UA | Ukrainian (Ukraine) |
ur | Urdu |
ur-PK | Urdu (Islamic Republic of Pakistan) |
uz | Uzbek |
uz-Cyrl-UZ | Uzbek (Cyrillic) (Uzbekistan) |
uz-Latn-UZ | Uzbek (Latin) (Uzbekistan) |
vi | Vietnamese |
vi-VN | Vietnamese (Vietnam) |
wo-SN* | Wolof (Senegal) |
xh-ZA | isiXhosa (South Africa) |
yo-NG | Yoruba (Nigeria) |
zh | Chinese |
zh-CHS | Chinese (Simplified) |
zh-Hans | Chinese (Simplified) |
zh-CHT | Chinese (Traditional) |
zh-Hant | Chinese (Traditional) |
zh-CN | Chinese (Peoples Republic of China) |
zh-HK | Chinese (Hong Kong S.A.R.) |
zh-MO | Chinese (Macao S.A.R.) |
zh-SG | Chinese (Singapore) |
zh-TW | Chinese (Taiwan) |
zu-ZA | isiZulu (South Africa) |