Intl.DisplayNames API - JavaScript i18n

Einführung

Ihre Anwendung hat den Ländercode US, aber Benutzer sehen den Text "United States". Sie haben den Sprachcode fr, aber der Sprachumschalter zeigt "French" an. Sie haben den Währungscode EUR, aber die Checkout-Seite zeigt "Euro" an.

Browser verwalten umfangreiche Lokalisierungsdaten, um ihre eigenen Benutzeroberflächen in verschiedenen Sprachen darzustellen. Die Intl.DisplayNames-API macht diese Daten für JavaScript zugänglich und wandelt standardisierte Codes in menschenlesbare Namen um, die für jede Sprache lokalisiert sind.

Dies macht Drittanbieter-Bibliotheken oder benutzerdefinierte Nachschlagetabellen überflüssig, die Wartung und Lokalisierung erfordern. Der Browser übernimmt sowohl die Daten als auch die Übersetzungen.

Umwandlung von Regionscodes in Ländernamen

Der häufigste Anwendungsfall ist die Umwandlung von ISO-Ländercodes in Ländernamen. Erstellen Sie eine DisplayNames-Instanz mit einer Locale und einem Typ, und rufen Sie dann die of()-Methode mit einem Ländercode auf:

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"

Der erste Parameter akzeptiert ein Array von Locale-Codes nach dem BCP 47-Standard. Der Browser verwendet die erste unterstützte Locale aus dem Array. Die Option type gibt an, welche Art von Code Sie umwandeln möchten.

Dieselben Codes erzeugen unterschiedliche Ausgaben, wenn sie für verschiedene Sprachen lokalisiert werden:

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"

Dieses Muster eignet sich für die Erstellung von Länderauswahlen, Standortanzeigen und alle Schnittstellenelemente, die Ländercodes in lesbare Namen umwandeln.

Umwandlung von Sprachcodes in Sprachnamen

Sprachcodes verwenden das gleiche Muster wie Regionscodes. Setzen Sie type: "language", um Sprachcodes in Sprachnamen umzuwandeln:

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"

Sprachcodes können Regions-Subtags für regionale Varianten enthalten:

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"

Dies wandelt Sprachcodes in Namen um, die für Sprachumschalter, Übersetzungsschnittstellen und Sprachpräferenzauswahlen geeignet sind.

Anzeigen von Sprachnamen in ihrer eigenen Sprache

Sprachumschalter zeigen oft jede Sprache in ihrem eigenen Schriftsystem an. Erstellen Sie eine separate DisplayNames-Instanz für jede Zielsprache:

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")); // "العربية"

Benutzer erkennen ihre Sprache schneller, wenn sie in ihrer nativen Schrift angezeigt wird.

Umwandlung von Währungscodes in Währungsnamen

Währungscodes folgen dem ISO 4217-Standard. Setzen Sie type: "currency", um dreistellige Währungscodes in Währungsnamen umzuwandeln:

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"

Währungsnamen werden basierend auf der Anzeigesprache lokalisiert:

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")); // "ユーロ"

Dieses Muster funktioniert für Währungsauswahlen in Checkout-Prozessen, Finanz-Dashboards und Währungsumrechnungsschnittstellen.

Umwandlung von Schriftcodes in Schriftnamen

Schriftcodes verwenden den ISO 15924-Standard. Setzen Sie type: "script", um vierstellige Schriftcodes in Schriftnamen umzuwandeln:

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"

Schriftnamen erscheinen seltener in Benutzeroberflächen, werden aber relevant für mehrsprachige Content-Management-Systeme und Sprachauswahlschnittstellen, die zwischen Schriftsystemen unterscheiden.

Umwandlung von Kalender-Codes in Kalendernamen

Kalendersysteme variieren je nach Kultur. Setzen Sie type: "calendar", um Kalenderbezeichner in Kalendernamen umzuwandeln:

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"

Dies ist nützlich für Terminplanungsanwendungen, Datumsauswahlen mit Kalendersystemauswahl und internationalisierte Kalenderschnittstellen.

Umwandlung von Datums- und Zeitfeldcodes in Feldnamen

Datums- und Zeitschnittstellen enthalten beschriftete Felder wie Jahr, Monat und Tag. Setzen Sie type: "dateTimeField", um Feldbezeichner in lokalisierte Feldnamen umzuwandeln:

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"

Diese Feldnamen werden für die Anzeigesprache lokalisiert:

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")); // "月"

Gültige Feldbezeichner umfassen era, year, quarter, month, weekOfYear, weekday, day, dayPeriod, hour, minute, second und timeZoneName.

Dieses Muster unterstützt die Erstellung von barrierefreien Datumsauswahlen, Kalenderschnittstellen und Zeitauswahlkomponenten mit korrekt lokalisierten Beschriftungen.

Steuerung der Anzeigelänge mit Style-Optionen

Die Option style steuert, wie ausführlich die Ausgabe erscheint. Drei Werte erzeugen unterschiedliche Längen:

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"

Der Stil long (Standard) erzeugt den vollständigen Namen. Die Stile short und narrow erzeugen abgekürzte Formen, wenn verfügbar, obwohl nicht alle Codes kürzere Varianten haben.

Der Stil wird bei Sprachnamen relevanter:

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"

Verwenden Sie long für vollständige Bezeichnungen in Formularen und detaillierten Benutzeroberflächen. Verwenden Sie short oder narrow für kompakte Anzeigen wie mobile Navigation oder UI-Elemente mit begrenztem Platz.

Umgang mit regionalen Sprachvarianten mit languageDisplay

Sprachcodes mit regionalen Subtags können als Dialekte oder als Standardsprachnamen mit regionalen Qualifizierern angezeigt werden. Die Option languageDisplay steuert dieses Verhalten und gilt nur bei 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)"

Der Wert dialect (Standard) zeigt regionale Varianten mit ihren gebräuchlichen Namen an. Der Wert standard zeigt immer die Basissprache mit einem regionalen Qualifizierer in Klammern an.

Wählen Sie dialect, wenn regionale Varianten allgemein bekannte Namen haben, die Benutzer erkennen. Wählen Sie standard für eine einheitliche Formatierung oder bei weniger gebräuchlichen Sprach-Region-Kombinationen.

Steuerung des Fallback-Verhaltens für ungültige Codes

Die Methode of() erhält Codes, die möglicherweise keine entsprechenden Anzeigenamen haben. Die Option fallback bestimmt, was passiert:

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

Der Wert code (Standard) gibt den Eingabecode zurück, wenn kein Anzeigename existiert. Der Wert none gibt undefined für nicht zugeordnete Codes zurück.

Verwenden Sie code, wenn Sie immer einen Zeichenkettenwert für die Anzeige benötigen, auch wenn dieser auf den Code selbst zurückfällt. Verwenden Sie none, wenn Sie ungültige Codes erkennen und explizit behandeln müssen:

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"

Erstellung einer Länderauswahl-Komponente

Die Intl.DisplayNames API lässt sich direkt in Interface-Komponenten integrieren. Dieses Beispiel erstellt eine Länderauswahl, die Ländernamen in der Sprache des Benutzers anzeigt:

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>
  );
}

Die Komponente erhält eine locale-Prop, die die Anzeigesprache steuert. Durch Ändern der locale-Prop wird das Dropdown-Menü mit übersetzten Ländernamen neu gerendert.

Erstellen einer Sprachumschalter-Komponente

Sprachumschalter zeigen jede Sprache in ihrem eigenen Schriftsystem an. Erstellen Sie eine DisplayNames-Instanz für jede Sprache:

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>
  );
}

Jede Schaltfläche zeigt den Sprachnamen in ihrer eigenen Schrift an. Benutzer erkennen ihre Sprache sofort, unabhängig von der aktuellen Schnittstellensprache.

Erstellen einer Währungsauswahl-Komponente

Währungsauswahlen profitieren von lokalisierten Währungsnamen. Dieses Beispiel erstellt eine Währungsauswahl, die sich an die Anzeigesprache anpasst:

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="">Währung auswählen</option>
      {currencies.map((code) => (
        <option key={code} value={code}>
          {code} - {currencyNames.of(code)}
        </option>
      ))}
    </select>
  );
}

Das Dropdown-Menü zeigt sowohl den Währungscode als auch den lokalisierten Währungsnamen an. Benutzer in verschiedenen Regionen sehen Währungsnamen in ihrer eigenen Sprache.

Abrufen aller unterstützten Werte

Die Methode Intl.supportedValuesOf() gibt Arrays aller unterstützten Werte für jeden Typ zurück. Dies eliminiert hartcodierte Listen von 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", ...]

Erstellen Sie dynamische Auswahlfelder, die automatisch alle unterstützten Werte enthalten:

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="">Land auswählen</option>
      {allRegions.map((code) => (
        <option key={code} value={code}>
          {regionNames.of(code)}
        </option>
      ))}
    </select>
  );
}

Diese Komponente enthält jeden vom Browser unterstützten Regionscode, ohne eine hartcodierte Liste pflegen zu müssen.

Verständnis der Anforderungen an das Codeformat

Jeder Typ erwartet Codes in bestimmten Formaten. Falsche Formate führen zu einem Fallback-Verhalten anstatt zur Anzeige von Namen.

Ländercodes folgen ISO 3166-1 alpha-2 (zwei Buchstaben) oder UN M.49 (drei Ziffern):

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)

Sprachcodes folgen BCP 47, das ISO 639-Sprachcodes mit optionalen Regions- und Skript-Subtags kombiniert:

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)"

Währungscodes folgen ISO 4217 (drei Buchstaben):

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

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

Skriptcodes folgen ISO 15924 (vier Buchstaben, großgeschrieben):

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

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

Der Codevergleich ist unabhängig von der Groß- und Kleinschreibung, aber die Einhaltung der Standardgroßschreibung verbessert die Lesbarkeit:

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"

Browser-Unterstützung und Kompatibilität

Die Intl.DisplayNames-API wurde 2021 in allen wichtigen Browsern verfügbar. Moderne Anwendungen können sie ohne Polyfills verwenden.

Die Basis-API mit den Typen language, region, script und currency hat universelle Unterstützung. Die Typen calendar und dateTimeField erschienen in späteren Browser-Versionen, haben aber seit 2025 eine breite Unterstützung.

Überprüfen Sie bei Bedarf die Feature-Unterstützung zur Laufzeit:

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");
}

Für Anwendungen, die ältere Browser unterstützen, greifen Sie auf statische Nachschlagetabellen oder Drittanbieter-Bibliotheken zurück, wenn die API nicht verfügbar ist.

Leistungsoptimierung durch Caching

Das Erstellen von DisplayNames-Instanzen verursacht minimalen Overhead, aber Anwendungen, die viele Codes konvertieren, sollten Instanzen wiederverwenden:

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"

Der Cache speichert Instanzen, die nach Locale und Typ indiziert sind. Nachfolgende Aufrufe verwenden bestehende Instanzen wieder, anstatt neue zu erstellen.

Dieses Muster ist besonders wichtig in häufig ausgeführten Code-Pfaden, die Hunderte oder Tausende von Codes konvertieren, wie beim Rendern großer Tabellen mit lokalisierten Daten.

Vergleich mit alternativen Ansätzen

Vor der Intl.DisplayNames-API verwendeten Anwendungen verschiedene Ansätze, um Codes in Namen zu konvertieren.

Hartcodierte Nachschlagetabellen erforderten Wartung und unterstützten nur vorbestimmte Sprachen:

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

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

Dieser Ansatz funktioniert nicht mehr, wenn neue Sprachen hinzugefügt werden, da jede Sprache eine separate Nachschlagetabelle benötigt.

Drittanbieter-Bibliotheken stellten Lokalisierungsdaten bereit, erhöhten jedoch die Bundle-Größe:

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"

Bibliotheken fügen dem Bundle Kilobytes an Daten hinzu und erfordern Updates, wenn neue Länder erscheinen oder sich Namen ändern.

Die Intl.DisplayNames-API beseitigt beide Probleme. Der Browser verwaltet die Daten, hält sie aktuell und eliminiert Bedenken bezüglich der Bundle-Größe. Die Daten unterstützen alle Sprachen, die der Browser unterstützt, ohne zusätzliche Downloads.