Intl.DisplayNames — Klasse · JavaScript-Referenz

Signatur

new Intl.DisplayNames(locales, options)

Beschreibung

Intl.DisplayNames ist Teil der ECMAScript-Internationalisierungs-API (Intl) und stellt eine standardisierte Möglichkeit bereit, menschenlesbare Namen für Sprachcodes (BCP 47), Ländercodes (ISO 3166-1 alpha-2), Schriftsystemcodes (ISO 15924) und Währungscodes (ISO 4217) in einer gewünschten Sprache anzuzeigen. Die zugrunde liegenden Übersetzungsdaten stammen aus dem Unicode Common Locale Data Repository (CLDR) und werden vom JavaScript-Laufzeitsystem bereitgestellt – es sind keine externen Bibliotheken erforderlich.

Die Klasse wird instanziiert mit einer Ziel-Locale (z. B. "de" für Deutsch) und einem Optionsobjekt, das den type der gewünschten Anzeigenamen festlegt. Anschließend kann die Methode of(code) wiederholt aufgerufen werden, um beliebige Codes in ihre lokalisierten Namen zu übersetzen. Das ist deutlich effizienter als das wiederholte Erstellen neuer Instanzen.

Typische Anwendungsfälle sind etwa Länder-Dropdown-Menüs, Sprachauswahl-Listen in Benutzeroberflächen, die Darstellung von Währungsnamen in Finanzanwendungen oder die Anzeige von Schriftsystemnamen in mehrsprachigen Texteditoren. Intl.DisplayNames ersetzt fragile, selbst gepflegte Lookup-Tabellen durch eine robuste, browserintegrierte Lösung.

Wichtig: Der übergebene Code muss dem für den jeweiligen type gültigen Format entsprechen (z. B. "DE" für die Region Deutschland, "de" für die Sprache Deutsch). Bei ungültigen Codes wird je nach fallback-Option entweder der Code selbst zurückgegeben oder ein RangeError ausgelöst.

Parameter

Name	Typ	Default	Beschreibung
$locales Pflicht	string \| string[]	—	Ein BCP-47-Sprach-Tag (z. B. `"de"`, `"en-US"`) oder ein Array davon, das die gewünschte Ausgabesprache der Anzeigenamen angibt. Das Laufzeitsystem wählt die beste verfügbare Locale aus.
$options Pflicht	object	—	Konfigurationsobjekt mit folgenden Eigenschaften: `type` (erforderlich): Art der Anzeigenamen. Mögliche Werte: `"language"`, `"region"`, `"script"`, `"currency"`, `"calendar"`, `"dateTimeField"`. `style` (optional): Länge des Anzeigenamens. Mögliche Werte: `"long"` (Standard), `"short"`, `"narrow"`. `languageDisplay` (optional, nur bei type=language): `"dialect"` (Standard) oder `"standard"` — steuert, ob Dialekt- oder Standardbezeichnungen bevorzugt werden. `fallback` (optional): Verhalten bei unbekannten Codes: `"code"` (Standard, gibt den Code zurück) oder `"none"` (gibt `undefined` zurück).

Rückgabewert

Typ

Intl.DisplayNames

Beschreibung

Eine neue Intl.DisplayNames-Instanz, die mit der Methode of(code) lokalisierte Anzeigenamen für Codes erzeugt.

Beispiele

Ländernamen auf Deutsch ausgeben

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

console.log(regionNames.of("DE")); // Deutschland
console.log(regionNames.of("US")); // Vereinigte Staaten
console.log(regionNames.of("JP")); // Japan
console.log(regionNames.of("FR")); // Frankreich

Deutschland Vereinigte Staaten Japan Frankreich

Sprachennamen in mehreren Ausgabesprachen

const languages = ["en", "de", "zh", "ar", "ja"];
const outputLocales = ["de", "en", "fr"];

for (const outputLocale of outputLocales) {
  const displayNames = new Intl.DisplayNames(outputLocale, { type: "language" });
  console.log(`-- Ausgabe auf: ${outputLocale} --`);
  for (const lang of languages) {
    console.log(`  ${lang} → ${displayNames.of(lang)}`);
  }
}

-- Ausgabe auf: de -- en → Englisch de → Deutsch zh → Chinesisch ar → Arabisch ja → Japanisch -- Ausgabe auf: en -- en → English de → German zh → Chinese ar → Arabic ja → Japanese -- Ausgabe auf: fr -- en → anglais de → allemand zh → chinois ar → arabe ja → japonais

Währungsnamen mit verschiedenen Styles

const styles = ["long", "short", "narrow"];

for (const style of styles) {
  const currencyNames = new Intl.DisplayNames("de", { type: "currency", style });
  console.log(`[${style}] USD → ${currencyNames.of("USD")}`);
  console.log(`[${style}] EUR → ${currencyNames.of("EUR")}`);
}

[long] USD → US-Dollar [long] EUR → Euro [short] USD → USD [short] EUR → EUR [narrow] USD → USD [narrow] EUR → EUR

Fallback-Verhalten bei unbekannten Codes

const withCodeFallback = new Intl.DisplayNames("de", { type: "region", fallback: "code" });
const withNoneFallback = new Intl.DisplayNames("de", { type: "region", fallback: "none" });

console.log(withCodeFallback.of("XYZ")); // unbekannter Code → Code wird zurückgegeben
console.log(withNoneFallback.of("XYZ")); // unbekannter Code → undefined

XYZ undefined

// Wichtig · Fallstricke

Browser-Kompatibilität: Intl.DisplayNames wird von allen modernen Browsern (Chrome 81+, Firefox 86+, Safari 14.1+, Edge 81+) sowie Node.js ab Version 12 unterstützt. In älteren Umgebungen ist ein Polyfill (z. B. über @formatjs/intl-displaynames) notwendig.

Groß-/Kleinschreibung: Regionscodes müssen in Großbuchstaben übergeben werden ("DE"), Sprachcodes in Kleinbuchstaben ("de"). Skript-Codes folgen dem ISO-15924-Format mit erstem Großbuchstaben ("Latn").
Ungültige Codes: Bei syntaktisch falschen Codes (nicht nur unbekannten) wirft of() unabhängig vom fallback-Wert einen RangeError.
Instanz-Wiederverwendung: Für Performance-kritische Anwendungen sollte eine Intl.DisplayNames-Instanz erzeugt und wiederverwendet werden, anstatt für jeden Code eine neue Instanz zu erstellen.
Verfügbare Locales: Welche Locales tatsächlich verfügbar sind, hängt von der JavaScript-Laufzeitumgebung ab. Mit Intl.DisplayNames.supportedLocalesOf(locales) lässt sich prüfen, welche Locales ohne Fallback unterstützt werden.

Siehe auch

Intl Intl.Locale Intl.ListFormat Intl.DisplayNames.prototype.of() Intl.DisplayNames.supportedLocalesOf() Intl.DisplayNames.prototype.resolvedOptions()