Signatur
Beschreibung
toLocaleString() formatiert eine Temporal.PlainMonthDay-Instanz, also ein wiederkehrendes Datum ohne Jahr wie einen Geburtstag, Feiertag oder Jahrestag, passend zu einer Sprache und Region. Die Methode entspricht dem Aufruf new Intl.DateTimeFormat(locales, options).format(monthDay). Sie nimmt dieselben Argumente wie der Konstruktor von Intl.DateTimeFormat.
Es werden nur die Felder Monat und Tag ausgegeben. Ohne Optionen verwendet die Methode ein kurzes numerisches Format, zum Beispiel 24.12. für de-DE oder 12/24 für en-US. Mit month: "long" oder dateStyle lässt sich die Ausgabe anpassen. Felder wie Jahr, Wochentag oder Uhrzeit gibt es in einem PlainMonthDay nicht. Ein Wochentag lässt sich ohne Jahr ohnehin nicht bestimmen.
Wichtig: Der Kalender der Instanz muss genau zum Kalender passen, den der Formatierer verwendet. Ein PlainMonthDay im Standardkalender iso8601 passt nicht zum Kalender gregory, den die meisten Sprachen verwenden. Deshalb löst toLocaleString() hier einen RangeError aus. Für die Anzeige legt man die Instanz deshalb am besten gleich mit calendar: "gregory" (bzw. dem Kalender der Zielsprache) an. Alternativ wandelt man sie mit withCalendar() nicht um, sondern ergänzt über toPlainDate({ year }) ein Jahr.
Wer dieselben Einstellungen oft nutzt, etwa in Listen, legt am besten einmal eine Intl.DateTimeFormat-Instanz an und ruft deren format() auf. Das ist deutlich schneller als wiederholte Aufrufe von toLocaleString().
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. Über die Erweiterung -u-ca- lässt sich der Kalender festlegen, z. B. "ja-JP-u-ca-japanese". |
| $options | Intl.DateTimeFormatOptions | undefined | Formatierungsoptionen wie bei Intl.DateTimeFormat. Sinnvoll sind vor allem month ("numeric", "2-digit", "short", "long", "narrow"), day, dateStyle, calendar und numberingSystem. Enthalten die Optionen nur Felder, die es im PlainMonthDay nicht gibt (z. B. nur hour oder timeStyle), wird ein TypeError ausgelöst. |
Rückgabewert
"24.12." oder "24. Dezember".Beispiele
Einfache Formatierung mit gregorianischem Kalender
// Kalender explizit auf "gregory" setzen, sonst droht ein RangeError
const heiligabend = Temporal.PlainMonthDay.from({ month: 12, day: 24, calendar: "gregory" });
console.log(heiligabend.toLocaleString("de-DE"));
console.log(heiligabend.toLocaleString("en-US"));
console.log(heiligabend.toLocaleString("de-DE", { month: "long", day: "numeric" }));Geburtstagsliste mit wiederverwendetem Formatierer
const geburtstage = [
{ name: "Anna", tag: "2024-03-15[u-ca=gregory]" },
{ name: "Ben", tag: "2024-11-02[u-ca=gregory]" },
];
// Bei vielen Einträgen: Formatierer nur einmal erzeugen
const fmt = new Intl.DateTimeFormat("de-DE", { day: "numeric", month: "long" });
for (const { name, tag } of geburtstage) {
const md = Temporal.PlainMonthDay.from(tag);
console.log(`${name}: ${fmt.format(md)}`);
// gleichwertig: md.toLocaleString("de-DE", { day: "numeric", month: "long" })
}RangeError bei ISO-Kalender abfangen
const md = Temporal.PlainMonthDay.from("--08-01"); // Kalender: iso8601
try {
console.log(md.toLocaleString("de-DE"));
} catch (err) {
console.log(err.name); // Kalender passt nicht zu "gregory"
// Ausweg: für die Anzeige ein Jahr ergänzen
const datum = md.toPlainDate({ year: 2024 });
console.log(datum.toLocaleString("de-DE", { day: "numeric", month: "long" }));
}