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.

Contents

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 i18n option by providing the iso2 key (e.g. "us" for United States) — see below.

Localising user interface strings

Use the i18n 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/i18n entrypoint — import the one you need and pass it into the i18n option:

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

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

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

You can also override one or more country names in a similar way — set countryNameLocale to "fr" and pass the following as i18n:

{
  ...fr,
  // override country name (United States)
  us: "États-Unis",
}

Supported UI locales

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

  • Albanian (sq)
  • Arabic (ar)
  • 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)
  • Finnish (fi)
  • French (fr)
  • German (de)
  • Greek (el)
  • Hindi (hi)
  • Hungarian (hu)
  • Indonesian (id)
  • Italian (it)
  • Japanese (ja)
  • Kannada (kn)
  • Korean (ko)
  • Lithuanian (lt)
  • Marathi (mr)
  • Norwegian (no)
  • Persian (fa)
  • Polish (pl)
  • Portuguese (pt)
  • Romanian (ro)
  • Russian (ru)
  • Serbian (sr)
  • Slovak (sk)
  • Slovenian (sl)
  • Spanish (es)
  • Swedish (sv)
  • 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 i18n option — see the full list of translatable keys below.

Translatable keys

Here is the full set of UI strings the i18n 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 search input in the dropdown
  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.

Note

Format-as-you-type is automatically disabled when the user types non-ASCII digits, since caret positioning gets unreliable with RTL numeral sets.

Edit this page