new Intl.DisplayNames() — Methode · JavaScript-Referenz

Signatur

new Intl.DisplayNames(locales, options)

Beschreibung

Der Konstruktor Intl.DisplayNames() erzeugt einen Formatierer, mit dem sich standardisierte Codes wie "de", "US", "Latn" oder "EUR" in menschenlesbare, lokalisierte Namen umwandeln lassen, z. B. "Deutsch", "Vereinigte Staaten", "Lateinisch" oder "Euro". Die Übersetzung selbst übernimmt die Methode of() der erzeugten Instanz.

Typische Anwendungsfälle sind Sprachauswahl-Menüs, Länderlisten in Formularen, Währungsanzeigen in Shops oder die Beschriftung von Datumsfeldern ("year", "month") in der Sprache des Nutzers, ohne eigene Übersetzungstabellen pflegen zu müssen. Die Daten stammen aus dem CLDR-Bestand der jeweiligen JavaScript-Engine.

Wichtig: Die Option type ist Pflicht. Ohne sie wirft der Konstruktor einen TypeError. Außerdem muss der Konstruktor mit new aufgerufen werden, ein Aufruf als normale Funktion ist ebenfalls ein TypeError.

Parameter

Name	Typ	Default	Beschreibung
$locales Pflicht	string \| string[] \| Intl.Locale \| undefined		BCP-47-Sprachkennung(en) für die Ausgabesprache, z. B. `"de-DE"` oder `["de", "en"]`. Bei `undefined` wird die Standard-Locale der Laufzeitumgebung verwendet.
$options Pflicht	object		Konfigurationsobjekt. Muss mindestens `type` enthalten.
$options.type Pflicht	"language" \| "region" \| "script" \| "currency" \| "calendar" \| "dateTimeField"		Art der Codes, die übersetzt werden sollen. Pflichtangabe.
$options.style	"long" \| "short" \| "narrow"	"long"	Länge des Anzeigenamens, z. B. `"Vereinigte Staaten"` vs. `"USA"`.
$options.fallback	"code" \| "none"	"code"	Verhalten bei unbekannten, aber gültigen Codes: `"code"` gibt den Code selbst zurück, `"none"` liefert `undefined`.
$options.languageDisplay	"dialect" \| "standard"	"dialect"	Nur bei `type: "language"`: `"dialect"` liefert z. B. `"Britisches Englisch"`, `"standard"` dagegen `"Englisch (Vereinigtes Königreich)"`.
$options.localeMatcher	"lookup" \| "best fit"	"best fit"	Algorithmus zur Auswahl der passenden Locale.

Rückgabewert

Typ

Intl.DisplayNames

Beschreibung

Eine neue Intl.DisplayNames-Instanz mit den Methoden of(code) und resolvedOptions().

Beispiele

Regionen und Sprachen auf Deutsch anzeigen

const regionen = new Intl.DisplayNames(['de'], { type: 'region' });
const sprachen = new Intl.DisplayNames(['de'], { type: 'language' });

console.log(regionen.of('US'));
console.log(regionen.of('CH'));
console.log(sprachen.of('fr'));
console.log(sprachen.of('en-GB'));

Vereinigte Staaten Schweiz Französisch Britisches Englisch

Sprachauswahl-Menü in der jeweiligen Eigensprache

const codes = ['de', 'en', 'fr', 'ja'];

const optionen = codes.map((code) => {
  // Jede Sprache in ihrer eigenen Sprache benennen
  const namen = new Intl.DisplayNames([code], { type: 'language' });
  return { code, label: namen.of(code) };
});

console.log(optionen);

[ { code: 'de', label: 'Deutsch' }, { code: 'en', label: 'English' }, { code: 'fr', label: 'français' }, { code: 'ja', label: '日本語' } ]

Währungen, Datumsfelder und fallback: 'none'

const waehrung = new Intl.DisplayNames('de', { type: 'currency' });
console.log(waehrung.of('EUR'));
console.log(waehrung.of('JPY'));

const felder = new Intl.DisplayNames('de', { type: 'dateTimeField' });
console.log(felder.of('month'));

const streng = new Intl.DisplayNames('de', { type: 'region', fallback: 'none' });
console.log(streng.of('XX')); // gültig geformt, aber unbekannt

Euro Japanischer Yen Monat undefined

Fehlende type-Option abfangen

try {
  new Intl.DisplayNames('de');
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Pflichtoption type: Fehlt sie, wirft der Konstruktor einen TypeError. Ein Aufruf ohne new wirft ebenfalls einen TypeError.
Ungültige Codes: of() wirft einen RangeError, wenn der Code syntaktisch nicht zum type passt (z. B. regionen.of('Deutschland')). fallback greift nur bei gültig geformten, aber unbekannten Codes.
Ergebnisse unterscheiden sich je nach Engine: Die Namen kommen aus den CLDR-Daten von Browser bzw. Node.js und können sich zwischen Versionen leicht unterscheiden. In Tests also nicht auf exakte Zeichenketten verlassen.
Kompatibilität: Seit Chrome 81, Firefox 86, Safari 14.1 und Node.js 14 verfügbar. type: 'calendar' und 'dateTimeField' sowie languageDisplay kamen später dazu (etwa Chrome 98, Firefox 91, Safari 15.4). Node.js-Builds mit small-icu liefern nur englische Daten.
Leistung: Das Erzeugen einer Instanz ist relativ aufwendig. Deshalb Instanzen wiederverwenden und nicht in Schleifen für dieselbe Locale neu anlegen.

Siehe auch

Intl.DisplayNames Intl.DisplayNames.prototype.of() Intl.DisplayNames.prototype.resolvedOptions() Intl.Locale Intl.NumberFormat Intl.DateTimeFormat new AsyncDisposableStack()