API Intl.DisplayNames - JavaScript i18n

Introduction

Votre application a le code pays US, mais les utilisateurs voient le texte "United States". Vous avez le code de langue fr, mais le sélecteur de langue affiche "French". Vous avez le code de devise EUR, mais la page de paiement affiche "Euro".

Les navigateurs maintiennent des données de localisation étendues pour afficher leurs propres interfaces dans différentes langues. L'API Intl.DisplayNames expose ces données à JavaScript, convertissant des codes standardisés en noms lisibles par l'humain et localisés pour n'importe quelle langue.

Cela élimine le besoin de bibliothèques tierces ou de tables de correspondance personnalisées qui nécessitent maintenance et localisation. Le navigateur gère à la fois les données et les traductions.

Conversion des codes de région en noms de pays

Le cas d'utilisation le plus courant consiste à convertir les codes de pays ISO en noms de pays. Créez une instance DisplayNames avec une locale et un type, puis appelez la méthode of() avec un code de pays :

const regionNames = new Intl.DisplayNames(["en"], { type: "region" });

console.log(regionNames.of("US")); // "United States"
console.log(regionNames.of("GB")); // "United Kingdom"
console.log(regionNames.of("JP")); // "Japan"

Le premier paramètre accepte un tableau de codes de locale suivant la norme BCP 47. Le navigateur utilise la première locale prise en charge dans le tableau. L'option type spécifie quel type de code vous souhaitez convertir.

Les mêmes codes produisent des résultats différents lorsqu'ils sont localisés pour différentes langues :

const englishRegions = new Intl.DisplayNames(["en"], { type: "region" });
const japaneseRegions = new Intl.DisplayNames(["ja"], { type: "region" });
const spanishRegions = new Intl.DisplayNames(["es"], { type: "region" });

console.log(englishRegions.of("FR")); // "France"
console.log(japaneseRegions.of("FR")); // "フランス"
console.log(spanishRegions.of("FR")); // "Francia"

Ce modèle fonctionne pour créer des sélecteurs de pays, des affichages de localisation et tout élément d'interface qui convertit des codes de pays en noms lisibles.

Conversion des codes de langue en noms de langues

Les codes de langue utilisent le même modèle que les codes de région. Définissez type: "language" pour convertir les codes de langue en noms de langues :

const languageNames = new Intl.DisplayNames(["en"], { type: "language" });

console.log(languageNames.of("en")); // "English"
console.log(languageNames.of("es")); // "Spanish"
console.log(languageNames.of("zh")); // "Chinese"
console.log(languageNames.of("ar")); // "Arabic"

Les codes de langue peuvent inclure des sous-balises de région pour les variantes régionales :

const languageNames = new Intl.DisplayNames(["en"], { type: "language" });

console.log(languageNames.of("en-US")); // "American English"
console.log(languageNames.of("en-GB")); // "British English"
console.log(languageNames.of("fr-CA")); // "Canadian French"
console.log(languageNames.of("pt-BR")); // "Brazilian Portuguese"

Cela convertit les codes de langue en noms adaptés aux sélecteurs de langue, aux interfaces de traduction et aux sélecteurs de préférences linguistiques.

Affichage des noms de langues dans leur propre langue

Les sélecteurs de langue affichent souvent chaque langue dans son propre système d'écriture. Créez une instance DisplayNames distincte pour chaque langue cible :

const english = new Intl.DisplayNames(["en"], { type: "language" });
const french = new Intl.DisplayNames(["fr"], { type: "language" });
const japanese = new Intl.DisplayNames(["ja"], { type: "language" });
const arabic = new Intl.DisplayNames(["ar"], { type: "language" });

console.log(english.of("en")); // "English"
console.log(french.of("fr")); // "français"
console.log(japanese.of("ja")); // "日本語"
console.log(arabic.of("ar")); // "العربية"

Les utilisateurs reconnaissent leur langue plus rapidement lorsqu'elle est affichée dans son script natif.

Conversion des codes de devise en noms de devises

Les codes de devise suivent la norme ISO 4217. Définissez type: "currency" pour convertir les codes de devise à trois lettres en noms de devises :

const currencyNames = new Intl.DisplayNames(["en"], { type: "currency" });

console.log(currencyNames.of("USD")); // "US Dollar"
console.log(currencyNames.of("EUR")); // "Euro"
console.log(currencyNames.of("GBP")); // "British Pound"
console.log(currencyNames.of("JPY")); // "Japanese Yen"

Les noms de devises se localisent en fonction de la locale d'affichage :

const englishCurrency = new Intl.DisplayNames(["en"], { type: "currency" });
const germanCurrency = new Intl.DisplayNames(["de"], { type: "currency" });
const japaneseCurrency = new Intl.DisplayNames(["ja"], { type: "currency" });

console.log(englishCurrency.of("EUR")); // "Euro"
console.log(germanCurrency.of("EUR")); // "Euro"
console.log(japaneseCurrency.of("EUR")); // "ユーロ"

Ce modèle fonctionne pour les sélecteurs de devises dans les flux de paiement, les tableaux de bord financiers et les interfaces de conversion de devises.

Conversion des codes d'écriture en noms d'écriture

Les codes d'écriture utilisent la norme ISO 15924. Définissez type: "script" pour convertir les codes d'écriture à quatre lettres en noms d'écriture :

const scriptNames = new Intl.DisplayNames(["en"], { type: "script" });

console.log(scriptNames.of("Latn")); // "Latin"
console.log(scriptNames.of("Arab")); // "Arabic"
console.log(scriptNames.of("Cyrl")); // "Cyrillic"
console.log(scriptNames.of("Hans")); // "Simplified Chinese"
console.log(scriptNames.of("Hant")); // "Traditional Chinese"

Les noms d'écriture apparaissent moins fréquemment dans les interfaces utilisateur mais deviennent pertinents pour les systèmes de gestion de contenu multilingue et les interfaces de sélection de langue qui distinguent les systèmes d'écriture.

Conversion des codes de calendrier en noms de calendrier

Les systèmes de calendrier varient selon les cultures. Définissez type: "calendar" pour convertir les identifiants de calendrier en noms de calendrier :

const calendarNames = new Intl.DisplayNames(["en"], { type: "calendar" });

console.log(calendarNames.of("gregory")); // "Gregorian Calendar"
console.log(calendarNames.of("japanese")); // "Japanese Calendar"
console.log(calendarNames.of("buddhist")); // "Buddhist Calendar"
console.log(calendarNames.of("hebrew")); // "Hebrew Calendar"
console.log(calendarNames.of("islamic")); // "Islamic Calendar"
console.log(calendarNames.of("chinese")); // "Chinese Calendar"

Cela devient utile pour les applications de planification, les sélecteurs de date avec choix de système de calendrier et les interfaces de calendrier internationalisées.

Conversion des codes de champs de date et d'heure en noms de champs

Les interfaces de date et d'heure contiennent des champs étiquetés comme l'année, le mois et le jour. Définissez type: "dateTimeField" pour convertir les identifiants de champs en noms de champs localisés :

const dateFields = new Intl.DisplayNames(["en"], { type: "dateTimeField" });

console.log(dateFields.of("year")); // "year"
console.log(dateFields.of("month")); // "month"
console.log(dateFields.of("day")); // "day"
console.log(dateFields.of("hour")); // "hour"
console.log(dateFields.of("minute")); // "minute"
console.log(dateFields.of("weekday")); // "day of the week"
console.log(dateFields.of("dayPeriod")); // "AM/PM"
console.log(dateFields.of("timeZoneName")); // "time zone"

Ces noms de champs se localisent pour la langue d'affichage :

const englishFields = new Intl.DisplayNames(["en"], { type: "dateTimeField" });
const spanishFields = new Intl.DisplayNames(["es"], { type: "dateTimeField" });
const japaneseFields = new Intl.DisplayNames(["ja"], { type: "dateTimeField" });

console.log(englishFields.of("month")); // "month"
console.log(spanishFields.of("month")); // "mes"
console.log(japaneseFields.of("month")); // "月"

Les identifiants de champs valides incluent era, year, quarter, month, weekOfYear, weekday, day, dayPeriod, hour, minute, second, et timeZoneName.

Ce modèle permet de créer des sélecteurs de date accessibles, des interfaces de calendrier et des composants de sélection d'heure avec des étiquettes correctement localisées.

Contrôler la longueur d'affichage avec les options de style

L'option style contrôle le niveau de détail de l'affichage. Trois valeurs produisent différentes longueurs :

const longNames = new Intl.DisplayNames(["en"], {
  type: "region",
  style: "long",
});

const shortNames = new Intl.DisplayNames(["en"], {
  type: "region",
  style: "short",
});

const narrowNames = new Intl.DisplayNames(["en"], {
  type: "region",
  style: "narrow",
});

console.log(longNames.of("US")); // "United States"
console.log(shortNames.of("US")); // "US"
console.log(narrowNames.of("US")); // "US"

Le style long (par défaut) produit le nom complet. Les styles short et narrow produisent des formes abrégées lorsqu'elles sont disponibles, bien que tous les codes n'aient pas de variantes plus courtes.

Le style devient plus pertinent avec les noms de langues :

const longLanguages = new Intl.DisplayNames(["en"], {
  type: "language",
  style: "long",
});

const shortLanguages = new Intl.DisplayNames(["en"], {
  type: "language",
  style: "short",
});

console.log(longLanguages.of("en-US")); // "American English"
console.log(shortLanguages.of("en-US")); // "US English"

Utilisez long pour les libellés complets dans les formulaires et les interfaces détaillées. Utilisez short ou narrow pour les affichages compacts comme la navigation mobile ou les éléments d'interface à espace limité.

Gestion des variantes régionales de langue avec languageDisplay

Les codes de langue avec des sous-balises régionales peuvent s'afficher comme des dialectes ou comme des noms de langue standard avec des qualificatifs régionaux. L'option languageDisplay contrôle ce comportement et s'applique uniquement avec type: "language" :

const dialectNames = new Intl.DisplayNames(["en"], {
  type: "language",
  languageDisplay: "dialect",
});

const standardNames = new Intl.DisplayNames(["en"], {
  type: "language",
  languageDisplay: "standard",
});

console.log(dialectNames.of("nl-BE")); // "Flemish"
console.log(standardNames.of("nl-BE")); // "Dutch (Belgium)"

console.log(dialectNames.of("en-AU")); // "Australian English"
console.log(standardNames.of("en-AU")); // "English (Australia)"

La valeur dialect (par défaut) affiche les variantes régionales en utilisant leurs noms communs. La valeur standard affiche toujours la langue de base avec un qualificatif régional entre parenthèses.

Choisissez dialect lorsque les variantes régionales ont des noms bien connus que les utilisateurs reconnaissent. Choisissez standard pour un formatage cohérent ou lorsque vous travaillez avec des combinaisons langue-région moins courantes.

Contrôler le comportement de repli pour les codes invalides

La méthode of() reçoit des codes qui pourraient ne pas avoir de noms d'affichage correspondants. L'option fallback détermine ce qui se passe :

const withCodeFallback = new Intl.DisplayNames(["en"], {
  type: "region",
  fallback: "code",
});

const withNoneFallback = new Intl.DisplayNames(["en"], {
  type: "region",
  fallback: "none",
});

console.log(withCodeFallback.of("ZZ")); // "ZZ"
console.log(withNoneFallback.of("ZZ")); // undefined

La valeur code (par défaut) renvoie le code d'entrée lorsqu'aucun nom d'affichage n'existe. La valeur none renvoie undefined pour les codes non mappés.

Utilisez code lorsque vous avez toujours besoin d'une valeur de chaîne pour l'affichage, même si elle se replie sur le code lui-même. Utilisez none lorsque vous devez détecter des codes invalides et les traiter explicitement :

const regionNames = new Intl.DisplayNames(["en"], {
  type: "region",
  fallback: "none",
});

function getRegionName(code) {
  const name = regionNames.of(code);
  if (name === undefined) {
    return "Unknown region";
  }
  return name;
}

console.log(getRegionName("US")); // "United States"
console.log(getRegionName("INVALID")); // "Unknown region"

Construire un composant de sélection de pays

L'API Intl.DisplayNames s'intègre directement dans les composants d'interface. Cet exemple construit un sélecteur de pays qui affiche les noms de pays dans la langue de l'utilisateur :

function CountrySelector({ locale, value, onChange }) {
  const regionNames = new Intl.DisplayNames([locale], { type: "region" });

  const countries = [
    "US",
    "GB",
    "CA",
    "AU",
    "FR",
    "DE",
    "JP",
    "CN",
    "BR",
    "IN",
  ];

  return (
    <select value={value} onChange={(e) => onChange(e.target.value)}>
      <option value="">Select a country</option>
      {countries.map((code) => (
        <option key={code} value={code}>
          {regionNames.of(code)}
        </option>
      ))}
    </select>
  );
}

Le composant reçoit une prop locale qui contrôle la langue d'affichage. Changer la prop locale réaffiche le menu déroulant avec les noms de pays traduits.

Création d'un composant de sélecteur de langue

Les sélecteurs de langue affichent chaque langue dans son propre système d'écriture. Créez une instance DisplayNames pour chaque langue :

function LanguageSwitcher({ currentLocale, onLocaleChange }) {
  const languages = [
    { code: "en", name: "English" },
    { code: "es", name: "Español" },
    { code: "fr", name: "Français" },
    { code: "de", name: "Deutsch" },
    { code: "ja", name: "日本語" },
    { code: "zh", name: "中文" },
  ];

  return (
    <div>
      {languages.map((lang) => {
        const displayNames = new Intl.DisplayNames([lang.code], {
          type: "language",
        });
        const nativeName = displayNames.of(lang.code);

        return (
          <button
            key={lang.code}
            onClick={() => onLocaleChange(lang.code)}
            className={currentLocale === lang.code ? "active" : ""}
          >
            {nativeName}
          </button>
        );
      })}
    </div>
  );
}

Chaque bouton affiche le nom de la langue dans son propre script. Les utilisateurs reconnaissent immédiatement leur langue, quelle que soit la langue actuelle de l'interface.

Création d'un composant de sélecteur de devise

Les sélecteurs de devise bénéficient des noms de devises localisés. Cet exemple crée un sélecteur de devise qui s'adapte à la langue d'affichage :

function CurrencySelector({ locale, value, onChange }) {
  const currencyNames = new Intl.DisplayNames([locale], { type: "currency" });

  const currencies = ["USD", "EUR", "GBP", "JPY", "CNY", "CAD", "AUD"];

  return (
    <select value={value} onChange={(e) => onChange(e.target.value)}>
      <option value="">Sélectionner une devise</option>
      {currencies.map((code) => (
        <option key={code} value={code}>
          {code} - {currencyNames.of(code)}
        </option>
      ))}
    </select>
  );
}

Le menu déroulant affiche à la fois le code de la devise et le nom localisé de la devise. Les utilisateurs dans différentes régions voient les noms des devises dans leur propre langue.

Obtention de toutes les valeurs prises en charge

La méthode Intl.supportedValuesOf() renvoie des tableaux de toutes les valeurs prises en charge pour chaque type. Cela élimine les listes codées en dur de codes :

const regions = Intl.supportedValuesOf("region");
console.log(regions); // ["AD", "AE", "AF", "AG", "AI", ...]

const languages = Intl.supportedValuesOf("language");
console.log(languages); // ["aa", "ab", "ae", "af", "ak", ...]

const currencies = Intl.supportedValuesOf("currency");
console.log(currencies); // ["AED", "AFN", "ALL", "AMD", ...]

const calendars = Intl.supportedValuesOf("calendar");
console.log(calendars); // ["buddhist", "chinese", "coptic", ...]

Créez des sélecteurs dynamiques qui incluent automatiquement toutes les valeurs prises en charge :

function UniversalCountrySelector({ locale, value, onChange }) {
  const regionNames = new Intl.DisplayNames([locale], { type: "region" });
  const allRegions = Intl.supportedValuesOf("region");

  return (
    <select value={value} onChange={(e) => onChange(e.target.value)}>
      <option value="">Sélectionner un pays</option>
      {allRegions.map((code) => (
        <option key={code} value={code}>
          {regionNames.of(code)}
        </option>
      ))}
    </select>
  );
}

Ce composant inclut tous les codes de région pris en charge par le navigateur sans avoir à maintenir une liste codée en dur.

Comprendre les exigences de format de code

Chaque type attend des codes dans des formats spécifiques. Les formats incorrects produisent un comportement de repli plutôt que des noms d'affichage.

Les codes de région suivent la norme ISO 3166-1 alpha-2 (deux lettres) ou UN M.49 (trois chiffres) :

const regionNames = new Intl.DisplayNames(["en"], { type: "region" });

console.log(regionNames.of("US")); // "United States" (ISO 3166-1)
console.log(regionNames.of("001")); // "world" (UN M.49)
console.log(regionNames.of("150")); // "Europe" (UN M.49)

Les codes de langue suivent BCP 47, qui combine les codes de langue ISO 639 avec des sous-balises optionnelles de région et de script :

const languageNames = new Intl.DisplayNames(["en"], { type: "language" });

console.log(languageNames.of("en")); // "English"
console.log(languageNames.of("en-US")); // "American English"
console.log(languageNames.of("zh-Hans")); // "Simplified Chinese"
console.log(languageNames.of("zh-Hans-CN")); // "Simplified Chinese (China)"

Les codes de devise suivent la norme ISO 4217 (trois lettres) :

const currencyNames = new Intl.DisplayNames(["en"], { type: "currency" });

console.log(currencyNames.of("USD")); // "US Dollar"
console.log(currencyNames.of("EUR")); // "Euro"

Les codes de script suivent la norme ISO 15924 (quatre lettres, avec majuscule) :

const scriptNames = new Intl.DisplayNames(["en"], { type: "script" });

console.log(scriptNames.of("Latn")); // "Latin"
console.log(scriptNames.of("Arab")); // "Arabic"

La comparaison des codes est insensible à la casse, mais suivre la capitalisation standard améliore la lisibilité :

const regionNames = new Intl.DisplayNames(["en"], { type: "region" });

console.log(regionNames.of("US")); // "United States"
console.log(regionNames.of("us")); // "United States"
console.log(regionNames.of("Us")); // "United States"

Support et compatibilité des navigateurs

L'API Intl.DisplayNames est devenue disponible sur tous les principaux navigateurs en 2021. Les applications modernes peuvent l'utiliser sans polyfills.

L'API de base avec les types language, region, script et currency bénéficie d'un support universel. Les types calendar et dateTimeField sont apparus dans des versions ultérieures des navigateurs mais disposent d'un large support depuis 2025.

Vérifiez la prise en charge des fonctionnalités à l'exécution si nécessaire :

if (typeof Intl.DisplayNames !== "undefined") {
  const regionNames = new Intl.DisplayNames(["en"], { type: "region" });
  console.log(regionNames.of("US"));
} else {
  console.log("Intl.DisplayNames not supported");
}

Pour les applications prenant en charge les navigateurs plus anciens, repliez-vous sur des tables de consultation statiques ou des bibliothèques tierces lorsque l'API n'est pas disponible.

Optimisation des performances avec la mise en cache

La création d'instances DisplayNames a un impact minimal, mais les applications qui convertissent de nombreux codes devraient réutiliser les instances :

const cache = new Map();

function getDisplayNames(locale, type) {
  const key = `${locale}-${type}`;

  if (!cache.has(key)) {
    cache.set(key, new Intl.DisplayNames([locale], { type }));
  }

  return cache.get(key);
}

function getCountryName(locale, code) {
  const displayNames = getDisplayNames(locale, "region");
  return displayNames.of(code);
}

console.log(getCountryName("en", "US")); // "United States"
console.log(getCountryName("en", "FR")); // "France"
console.log(getCountryName("es", "US")); // "Estados Unidos"

Le cache stocke les instances indexées par locale et type. Les appels suivants réutilisent les instances existantes plutôt que d'en créer de nouvelles.

Ce modèle est particulièrement important dans les chemins de code fréquemment utilisés qui convertissent des centaines ou des milliers de codes, comme lors du rendu de grands tableaux de données localisées.

Comparaison avec les approches alternatives

Avant l'API Intl.DisplayNames, les applications utilisaient plusieurs approches pour convertir les codes en noms.

Les tables de correspondance codées en dur nécessitaient de la maintenance et ne prenaient en charge que des langues prédéterminées :

const countryNames = {
  US: "United States",
  GB: "United Kingdom",
  FR: "France",
};

function getCountryName(code) {
  return countryNames[code] || code;
}

Cette approche ne fonctionne plus lors de l'ajout de nouvelles langues car chaque langue nécessite une table de correspondance distincte.

Les bibliothèques tierces fournissaient des données de localisation mais augmentaient la taille du bundle :

import countries from "i18n-iso-countries";
import countriesEN from "i18n-iso-countries/langs/en.json";
import countriesES from "i18n-iso-countries/langs/es.json";

countries.registerLocale(countriesEN);
countries.registerLocale(countriesES);

console.log(countries.getName("US", "en")); // "United States"
console.log(countries.getName("US", "es")); // "Estados Unidos"

Les bibliothèques ajoutent des kilooctets de données au bundle et nécessitent des mises à jour lorsque de nouveaux pays apparaissent ou que des noms changent.

L'API Intl.DisplayNames élimine ces deux problèmes. Le navigateur maintient les données à jour et élimine les problèmes de taille de bundle. Les données prennent en charge toutes les langues supportées par le navigateur sans téléchargements supplémentaires.