Signatur
Beschreibung
toLocaleString() wandelt einen Temporal.ZonedDateTime in eine Zeichenkette für Menschen um, die der Sprache und den regionalen Gepflogenheiten entspricht. Intern wird dafür Intl.DateTimeFormat genutzt. Die Parameter locales und options funktionieren daher genauso wie beim Konstruktor Intl.DateTimeFormat().
Ohne Optionen gibt die Methode Datum, Uhrzeit (mit Sekunden) und einen kurzen Zeitzonennamen aus, zum Beispiel "15.7.2024, 14:30:00 MESZ". Die Zeitzone kommt immer aus dem Objekt selbst, also aus timeZoneId. Sie lässt sich nicht über die Option timeZone überschreiben. Wenn du eine andere Zeitzone anzeigen willst, rechnest du vorher mit withTimeZone() um.
Nutze die Methode für die Anzeige in Oberflächen, E-Mails oder Protokollen, die Menschen lesen. Für Datenaustausch, Speicherung oder Vergleiche ist sie ungeeignet, weil sich die Ausgabe je nach Browser, ICU-Version und Sprache unterscheidet. Dafür gibt es toString() bzw. toJSON() im stabilen ISO-8601/RFC-9557-Format.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $locales | string | string[] | Intl.Locale | undefined | undefined (Standardsprache der Laufzeitumgebung) | BCP-47-Sprachkennung wie "de-DE" oder eine Liste davon in Reihenfolge der Priorität. Gleiche Bedeutung wie bei Intl.DateTimeFormat(). |
| $options | Intl.DateTimeFormatOptions | undefined | undefined | Formatierungsoptionen wie dateStyle, timeStyle, weekday, hour12, timeZoneName usw. Die Option timeZone ist nicht erlaubt, weil die Zeitzone aus dem Objekt kommt. |
Rückgabewert
Beispiele
Standardausgabe in verschiedenen Sprachen
const termin = Temporal.ZonedDateTime.from("2024-07-15T14:30:00[Europe/Berlin]");
console.log(termin.toLocaleString("de-DE"));
console.log(termin.toLocaleString("en-US"));Lange Darstellung mit dateStyle und timeStyle
const termin = Temporal.ZonedDateTime.from("2024-07-15T14:30:00[Europe/Berlin]");
const text = termin.toLocaleString("de-DE", {
dateStyle: "full",
timeStyle: "short",
});
console.log(`Ihr Termin: ${text}`);Termin in der Ortszeit des Teilnehmers anzeigen
const termin = Temporal.ZonedDateTime.from("2024-07-15T14:30:00[Europe/Berlin]");
// Nicht über die Option timeZone, sondern vorher umrechnen
const tokio = termin.withTimeZone("Asia/Tokyo");
console.log(tokio.toLocaleString("de-DE", {
hour: "2-digit",
minute: "2-digit",
timeZoneName: "long",
}));
try {
termin.toLocaleString("de-DE", { timeZone: "Asia/Tokyo" });
} catch (err) {
console.log(err.name);
}Viele Werte effizient formatieren
const termine = [
"2024-07-15T09:00:00[Europe/Berlin]",
"2024-07-16T13:15:00[Europe/Berlin]",
].map((s) => Temporal.ZonedDateTime.from(s));
// Einen Formatter einmal erzeugen und wiederverwenden
const fmt = new Intl.DateTimeFormat("de-DE", {
dateStyle: "medium",
timeStyle: "short",
timeZone: "Europe/Berlin",
});
for (const t of termine) {
console.log(fmt.format(t.toInstant()));
}// Wichtig · Fallstricke
- Option
timeZoneist verboten: Wenn du sie übergibst, wirft die Methode einenTypeError. Rechne stattdessen vorher mitwithTimeZone()um. - Kalender muss passen: Hat das Objekt einen anderen Kalender als
iso8601und passt dieser nicht zum Kalender der Sprache bzw. der Optioncalendar, wirft die Methode einenRangeError. Intl.DateTimeFormat.prototype.format()nimmt keineZonedDateTime-Objekte an (es gibt einenTypeError). Wenn du viele Werte formatierst, erzeugst du jeder Aufruf vontoLocaleString()einen neuen Formatter. Schneller ist es, einen Formatter mit passendertimeZoneeinmal anzulegen undzdt.toInstant()zu formatieren.- Ausgabe ist nicht stabil: Das genaue Format (Leerzeichen, schmale geschützte Leerzeichen vor „PM“, Namen der Zeitzonen) hängt von Browser und ICU-Version ab. Vergleiche die Ausgabe nicht in Tests oder Programmlogik und lies sie nicht wieder ein.
- Kompatibilität: Temporal ist erst in neueren Browsern verfügbar (Firefox 139+, Chrome/Edge 144+). Safari und ältere Node.js-Versionen brauchen einen Polyfill wie
@js-temporal/polyfill. OhneIntl-Unterstützung fällt die Methode auf eine von der Implementierung festgelegte Ausgabe zurück.