To localize SMS messages, pick the language from a stored preference on the contact, render a translated template, and check the segment count for that language before you send. Scripts that aren't in the GSM-7 set, such as Arabic, Chinese or Cyrillic, send as Unicode, which holds 70 characters per segment instead of 160.

We make Ready, so the examples use the Ready request shape. The i18n design applies to any provider.

Choose the language from the contact

Don't guess the language from the phone number. An area code or country code tells you where a number was issued, not what the person reads. Store a locale on the contact (es-US, pt-BR), set it from their sign-up form or account setting, and fall back to your default.

def pick_locale(contact, supported=("en", "es", "fr")):
    lang = (contact.locale or "en").split("-")[0]
    return lang if lang in supported else "en"

Keep the language of the message with the message record, so support can see what was sent.

Translate whole sentences

Concatenating fragments breaks word order in other languages. Use whole-sentence templates with named variables, and ICU message syntax where you need plurals:

import IntlMessageFormat from 'intl-messageformat';

const msg = new IntlMessageFormat(
  '{count, plural, one {You have # appointment tomorrow.} other {You have # appointments tomorrow.}}', 'en');
msg.format({ count: 2 });

Plural rules differ by language, and some languages have more than two forms, so don't write if count == 1. Our post on template engines covers strict rendering for the variables.

Count segments per language

This is where cost surprises come from. A message in English that fits in one 160-character segment can need two in Spanish with accented characters, if any character falls outside GSM-7. Some accented letters (é, è, ù, ñ, ü) are in the GSM-7 set, but á, í, ó, ú and lowercase ç are not. Check each translation by encoding it, not by eye.

LanguageTypical encodingCharacters in one segment
EnglishGSM-7160
Spanish, French, PortugueseGSM-7 or Unicode, depending on the letters160 or 70
Russian, Arabic, Hebrew, GreekUnicode70
Chinese, Japanese, KoreanUnicode70

Multipart messages cut each segment to 153 characters (GSM-7) or 67 (Unicode). Each segment is billed. A 120-character Russian text is two segments, while the same text in English is one. Budget for it, and see the GSM-7 and Unicode guide for how to detect the encoding.

What stays in English

The compliance wording doesn't move. Ready adds "Reply STOP to opt out" and the business name to the first text to each contact, and carriers look for the standard keywords, so tell contacts about STOP in a way that still includes the keyword itself. If you translate the surrounding sentence, keep STOP, HELP and START as written. Opt-out handling matches the keyword and a set of clear English phrases, so don't count on a translated opt-out phrase being understood. Odd wording no list catches still needs a person to read replies. The reply keyword post covers what happens when someone replies with something else.

Test every language

Write a test that renders every template in every supported locale with sample data and fails if any rendering exceeds its segment budget or leaves a placeholder. It's the cheapest thing you can add, and it catches the translator who added a long phrase.

FAQ

Can one message include two languages?

Yes, but it costs segments quickly. If you have to, put the contact's language first, and decide whether the second language is worth a second segment.

Should I send in the language of the number's country?

No. Send in the language the contact chose. Fall back to your default only when you have nothing.

Do right-to-left languages work?

Yes, as Unicode text. Test on real phones, because mixed text and numbers can display in an unexpected order.

The short version

Language from the contact, whole-sentence templates, a segment check per locale and STOP kept as written. The messages API docs cover the send itself.

Cost and registration

A segment on the Standard rate is $0.0075 plus a $0.0045 carrier fee, passed through at cost, excluding optional screening. An account can send up to 500 texts a month before it registers for 10DLC, and most approvals take 2 to 7 days. See pricing for the full list.