Intl.DisplayNames API - JavaScript i18n

Einführung

Ihre Anwendung hat den Ländercode US, aber Benutzer sehen den Text "Vereinigte Staaten". Sie haben den Sprachcode fr, aber der Sprachumschalter zeigt "Französisch" an. Sie haben den Währungscode EUR, aber die Checkout-Seite zeigt "Euro".

Browser verwalten umfangreiche Lokalisierungsdaten, um ihre eigenen Oberflächen in verschiedenen Sprachen darzustellen. Die Intl.DisplayNames API stellt diese Daten für JavaScript bereit und konvertiert standardisierte Codes in lesbare Namen, die für jede Sprache lokalisiert sind.

Dies macht den Einsatz von Drittanbieter-Bibliotheken oder benutzerdefinierten Lookup-Tabellen überflüssig, die Wartung und Lokalisierung erfordern. Der Browser übernimmt sowohl die Daten als auch die Übersetzungen.

Konvertierung von Regionscodes in Ländernamen

Der häufigste Anwendungsfall ist die Konvertierung von ISO-Ländercodes in Ländernamen. Erstellen Sie eine DisplayNames Instanz mit einem Locale und 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 das erste unterstützte Locale aus dem Array. Die type Option gibt an, welche Art von Code Sie konvertieren 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 funktioniert für die Erstellung von Länderauswahlen, Standortanzeigen und allen Oberflächenelementen, die Ländercodes in lesbare Namen konvertieren.

Konvertierung von Sprachcodes in Sprachnamen

Sprachcodes verwenden dasselbe Muster wie Regionscodes. Setzen Sie type: "language", um Sprachcodes in Sprachnamen zu konvertieren:

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 konvertiert Sprachcodes in Namen, die für Sprachumschalter, Übersetzungsschnittstellen und Sprachpräferenz-Selektoren geeignet sind.

Anzeige von Sprachnamen in ihrer eigenen Sprache

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

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.

Konvertierung von Währungscodes in Währungsnamen

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

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ährungsselektoren in Checkout-Prozessen, Finanz-Dashboards und Währungsumrechnungsschnittstellen.

Konvertierung von Schriftcodes in Schriftnamen

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

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.

Konvertierung von Kalendercodes in Kalendernamen

Kalendersysteme variieren zwischen verschiedenen Kulturen. Setzen Sie type: "calendar", um Kalenderbezeichner in Kalendernamen zu konvertieren:

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 wird nützlich für Planungsanwendungen, Datumsauswahl mit Kalendersystemauswahl und internationalisierte Kalenderschnittstellen.

Konvertierung 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 zu konvertieren:

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 barrierefreier Datumsauswahl-Komponenten, Kalenderoberflächen und Zeitauswahl-Komponenten 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 Style long (Standard) erzeugt den vollständigen Namen. Die Styles short und narrow erzeugen abgekürzte Formen, sofern verfügbar, wobei nicht alle Codes kürzere Varianten besitzen.

Der Style 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 Beschriftungen in Formularen und detaillierten Oberflächen. Verwenden Sie short oder narrow für kompakte Anzeigen wie mobile Navigation oder platzbeschränkte UI-Elemente.

Umgang mit regionalen Sprachvarianten mit languageDisplay

Sprachcodes mit Regions-Subtags können als Dialekte oder als Standardsprachnamen mit regionalen Qualifizierern angezeigt werden. Die Option languageDisplay steuert dieses Verhalten und gilt nur, wenn 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 unter Verwendung ihrer 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 bekannte Namen haben, die Benutzer erkennen. Wählen Sie standard für konsistente Formatierung oder bei der Arbeit mit weniger gebräuchlichen Sprach-Regions-Kombinationen.

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

Die of()-Methode empfängt Codes, die möglicherweise keine entsprechenden Anzeigenamen haben. Die fallback-Option 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 code-Wert (Standard) gibt den Eingabecode zurück, wenn kein Anzeigename existiert. Der none-Wert gibt undefined für nicht zugeordnete Codes zurück.

Verwenden Sie code, wenn Sie immer einen String-Wert 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"

Erstellen 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 empfängt ein Locale-Prop, das die Anzeigesprache steuert. Eine Änderung des Locale-Props rendert das Dropdown mit übersetzten Ländernamen neu.

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

Jeder Button zeigt den Sprachnamen in seiner eigenen Schrift an. Benutzer erkennen ihre Sprache sofort, unabhängig von der aktuellen Interface-Sprache.

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="">Select currency</option>
      {currencies.map((code) => (
        <option key={code} value={code}>
          {code} - {currencyNames.of(code)}
        </option>
      ))}
    </select>
  );
}

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

Alle unterstützten Werte abrufen

Die Intl.supportedValuesOf()-Methode gibt Arrays aller unterstützten Werte für jeden Typ zurück. Dies eliminiert fest codierte 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 Selektoren, die automatisch alle unterstützten Werte einschließen:

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

Diese Komponente enthält jeden vom Browser unterstützten Regionscode, ohne eine fest codierte Liste zu pflegen.

Anforderungen an das Code-Format verstehen

Jeder Typ erwartet Codes in spezifischen Formaten. Falsche Formate führen zu Fallback-Verhalten anstelle von Anzeigenamen.

Regionscodes 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 Schrift-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"

Schriftcodes 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 Code-Vergleich ist nicht case-sensitiv, 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 gängigen 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 ab 2025 breite Unterstützung.

Prüfen Sie die Feature-Unterstützung zur Laufzeit, wenn nötig:

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 Lookup-Tabellen oder Drittanbieter-Bibliotheken zurück, wenn die API nicht verfügbar ist.

Performance-Optimierung 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 vor allem in häufig ausgeführten Code-Pfaden wichtig, die Hunderte oder Tausende von Codes konvertieren, wie z. B. beim Rendern großer Tabellen mit lokalisierten Daten.

Vergleich mit alternativen Ansätzen

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

Fest codierte Lookup-Tabellen erforderten Wartung und unterstützten nur vorher festgelegte Sprachen:

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

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

Dieser Ansatz funktioniert nicht mehr beim Hinzufügen neuer Sprachen, da jede Sprache eine separate Lookup-Tabelle benötigt.

Drittanbieter-Bibliotheken stellten Lokalisierungsdaten bereit, erhöhten aber 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 Kilobytes an Daten zum Bundle hinzu und erfordern Updates, wenn neue Länder hinzukommen oder sich Namen ändern.

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