Languages and Localization

You can store your audience’s language preferences as an attribute, and then use that attribute to send people messages in their preferred language!

Multi-language message support

This is a new feature. At the moment, language settings only affect newsletters, but we’re actively working to add localizationA process of setting up messages with two or more languages, and using your workspace’s Language Settings to make sure that people in your audience receive messages in their preferred language. support to campaigns and other kinds of messages.

Campaign/message typeemailSMSPush
Campaigns
Newsletters
Broadcasts
Transactional
Messages

How it works

When you add or update people, you can set an attributeA key-value pair that you associate with a person—like their name, the date they were created in your workspace, etc. Use attributes to target people and personalize messages. containing their language preference. Then, when you set up messages, you can click 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.

graph LR A[Add language
attribute] --> B[Set up
multi-language message] B --> C[Send
message] C --> D{Does a person's language
attribute match a message?} 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]

Set your language attribute

Before you can send localized messages, you need to tell us which attributeA key-value pair that you associate with a person—like their name, the date they were created in your workspace, etc. Use attributes to target people and personalize messages. stores your audience’s language preferences. You also need to make sure that the attribute is populated with values we support; languages are formatted as a two letter language code with an optional two-letter region code—like en for English or en-US for English speakers in the United States. We’ll use this setting to match your translated messages to members of your audience. If you’re new to Customer.io, you can set an attribute that doesn’t exist yet and add it to your audience later.

Your language attribute can be any attribute in your workspace. The values for this attribute must be simple strings (not nested within an object), and formatted as either:

  • two letter language codes (defined by ISO-3166), like es or en representing Spanish and English respectively.
  • four-letter IETF language-region codes separated by a dash, like es-mx representing Spanish language speakers in Mexico.

To set your workspace’s language attribute:

  1. Go to Settings > Workspace Settings.
  2. Find Language Settings and click Get Started.
  3. Enter the name of the attribute representing your audience’s language.
Set your localization settings
Set your localization settings

Set up a multi-language Newsletter

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.

If you plan to send email contents to a translation vendor, you’ll want to set up and export your Default message first, and then add languages when you receive them. Check out our best practices for help exporting email messages for your translation vendor and the quickest way to add your multi-language content.

  1. Go to Broadcasts, select Newsletter, enter a Name for your newsletter, and then click Create Broadcast.
  2. Select who you want to send your newsletter to, a segmentA segment is a group of people in your audience that you want to target with campaigns, messages, etc. You can join groups of people manually, or by attribues and event data. of people or everyone in your workspace, and then click Save & Next.
  3. In the Content step, select the channel you want to send your message to, and then click to add Content.
  4. Click , select the languages you want to add, and click Add variations.
    Add languages to your newsletter
    Add languages to your newsletter
  5. Draft your Default message. This message should act as a “template” for your other languages.
  6. Add your content for your languages. Use the tabs at the top of the message to switch between languages.
    A newsletter with multiple languages
    A newsletter with multiple languages
  7. When you’re done, click Save & Next and finish setting up your newsletter.

Delete a language from your Newsletter

When composing your newsletter, you can remove languages that you add by mistake. Go to the tab for the language you want to remove and click .

Removing a language means that people bearing the language code in their localization attribute will receive the default message.

Remove a language from your content
Remove a language from your content

Multi-language newsletters with A/B tests

You can set up multi-language newsletters with A/B test variants. When you do this, you’ll create your newsletter tests as you normally would, and then add languages for each variant in the test.

Best practices

Before you export emails to send them to a translation vendor, switch to the Custom HTML editor

You might create your email with our drag and drop editor or in rich text. However, before you export, you should switch to the Custom HTML editor and export the full HTML for your message. When you receive your translations, it’ll be much easier to paste your full, custom HTML message content back into editor rather than pasting text into individual blocks in the drag-and-drop editor or reformatting your rich text for each language.

 Make sure your translation vendor handles raw HTML

While we suggest you export custom HTML, make sure that your translation team can translate from raw HTML before you switch editors. Remember, when you switch editor types, you won’t be able to switch back.

Use if statements in liquid to prevent failures.

When working with an audience across locales, it’s highly possible that members of your audience don’t have uniform attributes. Use if statements to set fallbacks for people who don’t have an attribute you want to reference.

{% if customer.first_name %}
    {{customer.first_name | capitalize}}
{% else %}
    Hey buddy
{{ end }}

Make sure attribute values that you reference with liquid are translated, or use if statements to set specific values.

You might use liquid to personalize your message for members of your audience. However, if your liquid values don’t reflect the languages your audience expects, members of your audience could see words they don’t recognize in their message.

If your attribute values aren’t translated, you could use an and operator to set hard-coded values for members of your audience whose attributes don’t reflect their language preference.

{% customer. and customer.language == ‘en’ %} {{customer.}} {% else %} Hard-coded value for people who either don’t have the attribute or have a different language attribute {% end %}

Exporting and importing multi-language emails

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 and test your Default message first. When you’re ready to send your message to translators, you may want to switch to the Custom HTML editor first.

The Custom HTML editor makes it easier to copy and export your email content. And, when you receive your languages back from your translator(s), it custom HTML is much easier to add back into your newsletter. Using the Custom HTML editor, you won’t need to paste individual lines into the drag-and-drop editor or reformat your languages in the rich text editor.

 Make sure that your translator handles HTML

While switching to the custom HTML editor makes it easier to export and import your languages, you should check with your translation vendor first to make sure that they can translate custom HTML while ignoring classes and other liquid.

flowchart LR A[Create Default
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

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.

An example newsletter with metrics in multiple languages
An example newsletter with metrics in multiple languages

Supported languages and locales

Your language attribute’s values must be formatted as a two letter language code with an optional two-letter region code separated by a dash. For example, you might use en for English or en-US for English speakers in the United States.

Language attributes are not case sensitive, but language-region codes must be separated by a dash. For example, both es-MX and es-mx both represent Spanish formatted for speakers in Mexico.

These codes come from the ISO-3166-1 and IETF standards respectively. If you’re looking for a language or locale that we don’t support, let us know!

Language/LocaleCode
Afrikaansaf
Afrikaans (South Africa)af-ZA
Amharic (Ethiopia)am-ET
Arabicar
Arabic (U.A.E.)ar-AE
Arabic (Bahrain)ar-BH
Arabic (Algeria)ar-DZ
Arabic (Egypt)ar-EG
Arabic (Iraq)ar-IQ
Arabic (Jordan)ar-JO
Arabic (Kuwait)ar-KW
Arabic (Lebanon)ar-LB
Arabic (Libya)ar-LY
Arabic (Morocco)ar-MA
Arabic (Oman)ar-OM
Arabic (Qatar)ar-QA
Arabic (Saudi Arabia)ar-SA
Arabic (Syria)ar-SY
Arabic (Tunisia)ar-TN
Arabic (Yemen)ar-YE
Mapudungun (Chile)arn-CL
Assamese (India)as-IN
Azeriaz
Azeri (Cyrillic) (Azerbaijan)az-Cyrl-AZ
Azeri (Latin) (Azerbaijan)az-Latn-AZ
Bashkir (Russia)ba-RU
Belarusianbe
Belarusian (Belarus)be-BY
Bulgarianbg
Bulgarian (Bulgaria)bg-BG
Bengali (Bangladesh)bn-BD
Bengali (India)bn-IN
Tibetan (People's Republic of China)bo-CN
Breton (France)br-FR
Bosnian (Cyrillic) (Bosnia and Herzegovina)bs-Cyrl-BA
Bosnian (Latin) (Bosnia and Herzegovina)bs-Latn-BA
Catalanca
Catalan (Catalan)ca-ES
Corsican (France)co-FR
Czechcs
Czech (Czech Republic)cs-CZ
Welsh (United Kingdom)cy-GB
Danishda
Danish (Denmark)da-DK
Germande
German (Austria)de-AT
German (Switzerland)de-CH
German (Germany)de-DE
German (Liechtenstein)de-LI
German (Luxembourg)de-LU
Lower Sorbian (Germany)dsb-DE
Divehidv
Divehi (Maldives)dv-MV
Greekel
Greek (Greece)el-GR
Englishen
English (Caribbean)en-029
English (Australia)en-AU
English (Belize)en-BZ
English (Canada)en-CA
English (United Kingdom)en-GB
English (Ireland)en-IE
English (India)en-IN
English (Jamaica)en-JM
English (Malaysia)en-MY
English (New Zealand)en-NZ
English (Republic of the Philippines)en-PH
English (Singapore)en-SG
English (Trinidad and Tobago)en-TT
English (United States)en-US
English (South Africa)en-ZA
English (Zimbabwe)en-ZW
Spanishes
Spanish (Argentina)es-AR
Spanish (Bolivia)es-BO
Spanish (Chile)es-CL
Spanish (Colombia)es-CO
Spanish (Costa Rica)es-CR
Spanish (Dominican Republic)es-DO
Spanish (Ecuador)es-EC
Spanish (Spain)es-ES
Spanish (Guatemala)es-GT
Spanish (Honduras)es-HN
Spanish (Mexico)es-MX
Spanish (Nicaragua)es-NI
Spanish (Panama)es-PA
Spanish (Peru)es-PE
Spanish (Puerto Rico)es-PR
Spanish (Paraguay)es-PY
Spanish (El Salvador)es-SV
Spanish (United States)es-US
Spanish (Uruguay)es-UY
Spanish (Venezuela)es-VE
Estonianet
Estonian (Estonia)et-EE
Basqueeu
Basque (Basque)eu-ES
Persianfa
Persian (Iran)fa-IR
Finnishfi
Finnish (Finland)fi-FI
Filipino (Philippines)fil-PH
Faroesefo
Faroese (Faroe Islands)fo-FO
Frenchfr
French (Belgium)fr-BE
French (Canada)fr-CA
French (Switzerland)fr-CH
French (France)fr-FR
French (Luxembourg)fr-LU
French (Principality of Monaco)fr-MC
Frisian (Netherlands)fy-NL
Irish (Ireland)ga-IE
Scottish Gaelic (United Kingdom)gd-GB
Galiciangl
Galician (Galician)gl-ES
Alsatian (France)gsw-FR
Gujaratigu
Gujarati (India)gu-IN
Hausa (Latin) (Nigeria)ha-Latn-NG
Hebrewhe
Hebrew (Israel)he-IL
Hindihi
Hindi (India)hi-IN
Croatianhr
Croatian (Latin) (Bosnia and Herzegovina)hr-BA
Croatian (Croatia)hr-HR
Upper Sorbian (Germany)hsb-DE
Hungarianhu
Hungarian (Hungary)hu-HU
Armenianhy
Armenian (Armenia)hy-AM
Indonesianid
Indonesian (Indonesia)id-ID
Igbo (Nigeria)ig-NG
Yi (People's Republic of China)ii-CN
Icelandicis
Icelandic (Iceland)is-IS
Italianit
Italian (Switzerland)it-CH
Italian (Italy)it-IT
Inuktitut (Syllabics) (Canada)iu-Cans-CA
Inuktitut (Latin) (Canada)iu-Latn-CA
Japaneseja
Japanese (Japan)ja-JP
Georgianka
Georgian (Georgia)ka-GE
Kazakhkk
Kazakh (Kazakhstan)kk-KZ
Greenlandic (Greenland)kl-GL
Khmer (Cambodia)km-KH
Kannadakn
Kannada (India)kn-IN
Koreanko
Korean (Korea)ko-KR
Konkanikok
Konkani (India)kok-IN
Kyrgyzky
Kyrgyz (Kyrgyzstan)ky-KG
Latinla
Luxembourgish (Luxembourg)lb-LU
Lao (Lao P.D.R.)lo-LA
Lithuanianlt
Lithuanian (Lithuania)lt-LT
Latvianlv
Latvian (Latvia)lv-LV
Maori (New Zealand)mi-NZ
Macedonianmk
Macedonian (Former Yugoslav Republic of Macedonia)mk-MK
Malayalam (India)ml-IN
Mongolianmn
Mongolian (Cyrillic) (Mongolia)mn-MN
Mongolian (Traditional Mongolian) (People's Republic of China)mn-Mong-CN
Mohawk (Canada)moh-CA
Marathimr
Marathi (India)mr-IN
Malayms
Malay (Brunei Darussalam)ms-BN
Malay (Malaysia)ms-MY
Maltese (Malta)mt-MT
"Norwegian, Bokmål (Norway)"nb-NO
Nepali (Nepal)ne-NP
Dutchnl
Dutch (Belgium)nl-BE
Dutch (Netherlands)nl-NL
"Norwegian, Nynorsk (Norway)"nn-NO
Norwegianno
Sesotho sa Leboa (South Africa)nso-ZA
Occitan (France)oc-FR
Oriya (India)or-IN
Punjabipa
Punjabi (India)pa-IN
Polishpl
Polish (Poland)pl-PL
Dari (Afghanistan)prs-AF
Pashto (Afghanistan)ps-AF
Portuguesept
Portuguese (Brazil)pt-BR
Portuguese (Portugal)pt-PT
K'iche (Guatemala)qut-GT
Quechua (Bolivia)quz-BO
Quechua (Ecuador)quz-EC
Quechua (Peru)quz-PE
Romansh (Switzerland)rm-CH
Romanianro
Romanian (Romania)ro-RO
Russianru
Russian (Russia)ru-RU
Kinyarwanda (Rwanda)rw-RW
Sanskritsa
Sanskrit (India)sa-IN
Yakut (Russia)sah-RU
Sami (Northern) (Finland)se-FI
Sami (Northern) (Norway)se-NO
Sami (Northern) (Sweden)se-SE
Sinhala (Sri Lanka)si-LK
Slovaksk
Slovak (Slovakia)sk-SK
Sloveniansl
Slovenian (Slovenia)sl-SI
Sami (Southern) (Norway)sma-NO
Sami (Southern) (Sweden)sma-SE
Sami (Lule) (Norway)smj-NO
Sami (Lule) (Sweden)smj-SE
Sami (Inari) (Finland)smn-FI
Sami (Skolt) (Finland)sms-FI
Albaniansq
Albanian (Albania)sq-AL
Serbiansr
Serbian (Cyrillic) (Bosnia and Herzegovina)sr-Cyrl-BA
Serbian (Cyrillic) (Serbia and Montenegro (Former))sr-Cyrl-CS
Serbian (Cyrillic) (Montenegro)sr-Cyrl-ME
Serbian (Cyrillic) (Serbia)sr-Cyrl-RS
Serbian (Latin) (Bosnia and Herzegovina)sr-Latn-BA
Serbian (Latin) (Serbia and Montenegro (Former))sr-Latn-CS
Serbian (Latin) (Montenegro)sr-Latn-ME
Serbian (Latin) (Serbia)sr-Latn-RS
Swedishsv
Swedish (Finland)sv-FI
Swedish (Sweden)sv-SE
Kiswahilisw
Kiswahili (Kenya)sw-KE
Syriacsyr
Syriac (Syria)syr-SY
Tamilta
Tamil (India)ta-IN
Telugute
Telugu (India)te-IN
Tajik (Cyrillic) (Tajikistan)tg-Cyrl-TJ
Thaith
Thai (Thailand)th-TH
Turkmen (Turkmenistan)tk-TM
Setswana (South Africa)tn-ZA
Turkishtr
Turkish (Turkey)tr-TR
Tatartt
Tatar (Russia)tt-RU
Tamazight (Latin) (Algeria)tzm-Latn-DZ
Uyghur (People's Republic of China)ug-CN
Ukrainianuk
Ukrainian (Ukraine)uk-UA
Urduur
Urdu (Islamic Republic of Pakistan)ur-PK
Uzbekuz
Uzbek (Cyrillic) (Uzbekistan)uz-Cyrl-UZ
Uzbek (Latin) (Uzbekistan)uz-Latn-UZ
Vietnamesevi
Vietnamese (Vietnam)vi-VN
Wolof (Senegal)wo-SN
isiXhosa (South Africa)xh-ZA
Yoruba (Nigeria)yo-NG
Chinese (Simplified)zh-Hans
Chinese (Traditional)zh-Hant
Chinese (People's Republic of China)zh-CN
Chinese (Hong Kong S.A.R.)zh-HK
Chinese (Macao S.A.R.)zh-MO
Chinese (Singapore)zh-SG
Chinese (Taiwan)zh-TW
isiZulu (South Africa)zu-ZA
Copied to clipboard!