Intl.Locale.prototype.toString() — Methode · JavaScript-Referenz

Signatur

Intl.Locale.prototype.toString()

Beschreibung

toString() wandelt ein Intl.Locale-Objekt zurück in einen Locale-Identifier-String nach BCP 47, z. B. "de-DE" oder "en-Latn-US-u-ca-gregory-hc-h12". Der String enthält die Sprache, optional Schrift und Region, Varianten und alle gesetzten Unicode-Erweiterungsschlüssel (-u-…), zum Beispiel Kalender (ca), Stundenzyklus (hc), Zahlensystem (nu) oder Sortierung (co).

Der Rückgabewert ist kanonisiert: Groß-/Kleinschreibung wird normalisiert ("EN-us" → "en-US"), veraltete Subtags werden ersetzt und Erweiterungsschlüssel werden alphabetisch sortiert. Werte, die über das Options-Objekt des Konstruktors übergeben wurden, überschreiben gleichnamige Schlüssel aus dem Tag-String und erscheinen im Ergebnis.

Man braucht die Methode immer dann, wenn eine Locale serialisiert werden soll: zum Speichern einer Benutzereinstellung, zum Setzen des lang-Attributs, für URLs oder HTTP-Header wie Accept-Language. Da toString() auch implizit aufgerufen wird, funktionieren String(locale) und Template-Literale ebenfalls. Wer nur Sprache, Schrift und Region ohne Erweiterungen benötigt, greift stattdessen zu baseName.

Rückgabewert

Typ

string

Beschreibung

Der vollständige, kanonisierte Locale-Identifier inklusive aller Unicode-Erweiterungsschlüssel (-u-…).

Beispiele

Grundlegende Nutzung und Kanonisierung

const locale = new Intl.Locale("EN-latn-us");
console.log(locale.toString());

// Options werden als Unicode-Erweiterungen angehängt (alphabetisch sortiert)
const mitOptionen = new Intl.Locale("en-US", {
  hourCycle: "h12",
  calendar: "gregory"
});
console.log(mitOptionen.toString());

en-Latn-US en-US-u-ca-gregory-hc-h12

toString() vs. baseName

const locale = new Intl.Locale("de-DE-u-ca-buddhist", {
  calendar: "gregory", // überschreibt den Wert aus dem Tag
  numberingSystem: "latn"
});

console.log(locale.toString());
console.log(locale.baseName);

de-DE-u-ca-gregory-nu-latn de-DE

Maximierte Locale als lang-Attribut und in einer URL verwenden

const nutzerLocale = new Intl.Locale("zh").maximize();

// Impliziter toString()-Aufruf über Template-Literal
const url = `https://example.com/api/texte?locale=${encodeURIComponent(nutzerLocale)}`;
console.log(url);

// Im Browser: document.documentElement.lang = nutzerLocale.toString();
console.log(String(nutzerLocale));

https://example.com/api/texte?locale=zh-Hans-CN zh-Hans-CN

Locale speichern und wiederherstellen (JSON-Fallstrick)

const locale = new Intl.Locale("fr-CA", { hourCycle: "h23" });

// Falsch: Locale-Objekte haben keine eigenen aufzählbaren Eigenschaften
console.log(JSON.stringify({ locale }));

// Richtig: explizit serialisieren …
const json = JSON.stringify({ locale: locale.toString() });
console.log(json);

// … und wiederherstellen
const wiederhergestellt = new Intl.Locale(JSON.parse(json).locale);
console.log(wiederhergestellt.hourCycle);

{"locale":{}} {"locale":"fr-CA-u-hc-h23"} h23

// Wichtig · Fallstricke

JSON-Fallstrick: Intl.Locale besitzt keine toJSON()-Methode. JSON.stringify(locale) ergibt deshalb "{}". Vor dem Serialisieren immer toString() aufrufen.
Nicht identisch mit der Eingabe: Der Rückgabewert ist kanonisiert. Man darf also nicht erwarten, genau den String zurückzubekommen, der an den Konstruktor übergeben wurde (andere Groß-/Kleinschreibung, sortierte Erweiterungen, ersetzte Alias-Subtags). Vergleiche von Locales sollten deshalb immer auf kanonisierten Strings stattfinden.
Braucht man nur Sprache, Schrift und Region ohne -u--Erweiterungen, ist baseName die richtige Wahl.
maximize() und minimize() geben neue Intl.Locale-Objekte zurück, keine Strings. Für die Weitergabe an APIs, die Strings erwarten, ist toString() nötig. Die meisten Intl-Konstruktoren (z. B. Intl.DateTimeFormat) akzeptieren aber auch direkt Intl.Locale-Objekte.
Wird die Methode auf einem Objekt aufgerufen, das keine Intl.Locale-Instanz ist (z. B. per call()), wirft sie einen TypeError.
Kompatibilität: Verfügbar in Chrome 74+, Firefox 75+, Safari 14+, Edge 79+ und Node.js 12+ (mit vollständigen ICU-Daten).

Siehe auch

Intl.Locale Intl.Locale.prototype.baseName Intl.Locale.prototype.maximize() Intl.Locale.prototype.minimize() Intl.Locale.prototype.calendar