API Intl.DisplayNames - JavaScript i18n

Introduction

Votre application possède le code pays US, mais les utilisateurs voient le texte « États-Unis ». Vous avez le code langue fr, mais le sélecteur de langue affiche « Français ». Vous avez le code 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 les codes standardisés en noms lisibles 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.

Convertir les codes de région en noms de pays

Le cas d'usage le plus courant consiste à convertir les codes 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 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 du tableau. L'option type spécifie le type de code que 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 les codes pays en noms lisibles.

Convertir les codes de langue en noms de langue

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 langue :

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.

Afficher les noms de langue 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 écriture native.

Convertir les codes de devise en noms de devise

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

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 devise 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 devise dans les flux de paiement, les tableaux de bord financiers et les interfaces de conversion de devises.

Convertir les 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.

Convertir les 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 sélection de système de calendrier et les interfaces de calendrier internationalisées.

Convertir les codes de champ de date et d'heure en noms de champ

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 champ en noms de champ 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 selon 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 libellés correctement localisés.

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

L'option style contrôle le niveau de détail de la sortie. 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 avec contraintes d'espace.

Gérer les variantes linguistiques régionales 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 lorsque 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 courants. 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ôle du comportement de repli pour les codes invalides

La méthode of() reçoit des codes qui peuvent 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 revient au code lui-même. Utilisez none lorsque vous devez détecter les codes invalides et les gérer 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"

Création d'un composant de sélection de pays

L'API Intl.DisplayNames s'intègre directement dans les composants d'interface. Cet exemple crée 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. Modifier la prop locale réaffiche le menu déroulant avec les noms de pays traduits.

Création d'un composant de sélection 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élection de devise

Les sélecteurs de devise bénéficient de 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="">Select currency</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 devise et le nom de devise localisé. Les utilisateurs de différentes régions voient les noms de devises dans leur propre langue.

Obtenir 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 de codes codées en dur :

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="">Select a country</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 maintenir de 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 la norme BCP 47, qui combine les codes de langue ISO 639 avec des sous-balises de région et de script optionnelles :

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, en majuscules) :

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

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

La comparaison de 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"

Prise en charge et compatibilité des navigateurs

L'API Intl.DisplayNames est devenue disponible dans 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'une prise en charge universelle. Les types calendar et dateTimeField sont apparus dans des versions ultérieures des navigateurs mais bénéficient d'une large prise en charge depuis 2025.

Vérifiez la prise en charge des fonctionnalités au moment de 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 des navigateurs plus anciens, utilisez des tables de correspondance statiques ou des bibliothèques tierces lorsque l'API n'est pas disponible.

Optimiser les performances avec la mise en cache

La création d'instances DisplayNames a un coût 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 critiques qui convertissent des centaines ou des milliers de codes, comme le rendu de grandes tables 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 une 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 échoue 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 les noms changent.

L'API Intl.DisplayNames élimine ces deux problèmes. Le navigateur maintient les données, les gardant à jour et éliminant les préoccupations liées à la taille du bundle. Les données prennent en charge toutes les langues que le navigateur prend en charge sans téléchargements supplémentaires.