Localisation

intl-tel-input supports localisation of country names, UI strings, right-to-left layout, and alternative numerals. You can experiment with the different options in the Playground, or view the Right to left example.

Localising country names

Country names are generated using the native Intl.DisplayNames API, which supports hundreds of locales out of the box. Use the countryNameLocale option to specify the locale — a BCP 47 language tag, e.g. "fr" for French.

You can also override individual country names via the countryNameOverrides option, by passing an object keyed by iso2 code:

{
  us: "États-Unis",
}

Browser support caveat

Some browsers ship a reduced Intl.DisplayNames dataset that omits country names for certain locales, silently falling back to English. Most notably, Chrome on desktop does this for bs (Bosnian), hy (Armenian), is (Icelandic), mk (Macedonian), sq (Albanian) and uz (Uzbek).

You don’t need to handle this: for these locales we bundle the translated country names into their intl-tel-input/locale modules, so importing one for uiTranslations gives correctly translated country names in every browser. Note that when using one of these locales with uiTranslations, any separate countryNameLocale option value will be ignored, but you can still use countryNameOverrides to override them.

Localising user interface strings

Use the uiTranslations option to translate the user interface strings (e.g. the country search placeholder, no-results message, and various accessibility labels).

We provide translations for many locales in the intl-tel-input/locale entrypoint — import the one you need and pass it into the uiTranslations option:

import { fr } from "intl-tel-input/locale";

You can override one or more keys by spreading the provided translations — pass the following as uiTranslations:

{
  ...fr,
  // override UI translation (the country search placeholder)
  searchPlaceholder: "Rechercher",
}

Supported UI locales

We currently ship user interface translations for the following 54 locales:

• Albanian (sq)
• Arabic (ar)
• Armenian (hy)
• Bangla (bn)
• Bosnian (bs)
• Bulgarian (bg)
• Catalan (ca)
• Chinese (zh)
• Chinese (Hong Kong SAR China) (zh-hk)
• Croatian (hr)
• Czech (cs)
• Danish (da)
• Dutch (nl)
• English (en)
• Estonian (et)
• Filipino (fil)
• Finnish (fi)
• French (fr)
• German (de)
• Greek (el)
• Hebrew (he)
• Hindi (hi)
• Hungarian (hu)
• Icelandic (is)
• Indonesian (id)
• Italian (it)
• Japanese (ja)
• Kannada (kn)
• Korean (ko)
• Latvian (lv)
• Lithuanian (lt)
• Macedonian (mk)
• Malay (ms)
• Marathi (mr)
• Norwegian (no)
• Persian (fa)
• Polish (pl)
• Portuguese (pt)
• Romanian (ro)
• Russian (ru)
• Serbian (sr)
• Slovak (sk)
• Slovenian (sl)
• Spanish (es)
• Swahili (sw)
• Swedish (sv)
• Tamil (ta)
• Telugu (te)
• Thai (th)
• Turkish (tr)
• Ukrainian (uk)
• Urdu (ur)
• Uzbek (uz)
• Vietnamese (vi)

Don’t see your locale? It’s easy to contribute a new one yourself — see Adding a new translation.

Alternatively, you can specify your own translations inline by passing a custom object to the uiTranslations option — see the full list of translatable keys below.

Translatable keys

Here is the full set of UI strings the uiTranslations option accepts, shown with their default English values for reference:

{
  // Aria label for the selected country element, when there is a country selected
  selectedCountryAriaLabel: "Change country for phone number, currently selected ${countryName} (${dialCode})",
  // Aria label and title text for the selected country element, when no country is selected
  noCountrySelected: "Select country for phone number",
  // Aria label for the country list element
  countryListAriaLabel: "List of countries",
  // Placeholder for the country search input
  searchPlaceholder: "Search",
  // Aria label for the clear search button
  clearSearchAriaLabel: "Clear search",
  // Visible text for when the search produces no results
  searchEmptyState: "No results found",
  // Screen reader summary of search results
  searchSummaryAria(count) {
    if (count === 0) return "No results found";
    if (count === 1) return "1 result found";
    return `${count} results found`;
  },
}

Right-to-left (RTL) languages

On RTL sites (i.e. where dir="rtl" is set on the <html> element, or any other ancestor), the layout will automatically flow right-to-left.

Phone numbers and dial codes are still displayed left-to-right, as that’s the standard way to write telephone numbers.

See the Right to left example.

Alternative numerals

intl-tel-input supports alternative numerals for phone number input.

• Arabic-Indic digits: ٠ ١ ٢ ٣ ٤ ٥ ٦ ٧ ٨ ٩
• Persian / Extended Arabic-Indic digits: ۰ ۱ ۲ ۳ ۴ ۵ ۶ ۷ ۸ ۹

These are normalised internally to ASCII 0-9 for parsing/validation, and when the input value is updated it preserves the user’s numeral set.