Signatur
Beschreibung
toLocaleString() formatiert ein Temporal.PlainYearMonth für die Anzeige, also zum Beispiel „August 2021“, „8/2021“ oder „令和3年8月“. Das Ergebnis hängt vom Gebietsschema ab. Intern wird ein Intl.DateTimeFormat mit denselben Argumenten erzeugt und darauf format(this) aufgerufen.
Wenn du keine Optionen angibst, werden nur Jahr und Monat formatiert (year und month, jeweils numerisch). Mit den Optionen von Intl.DateTimeFormat steuerst du die Darstellung, zum Beispiel month: "long" für den ausgeschriebenen Monatsnamen oder dateStyle. Erlaubt sind nur Felder, die ein Jahres-Monat auch hat.
Wichtig: Der Kalender des PlainYearMonth muss genau zum Kalender des Gebietsschemas passen. Ein Wert im Standardkalender iso8601 passt also nicht zum gregorianischen Kalender (gregory) von "de-DE". In diesem Fall wird ein RangeError ausgelöst. Lege den Jahres-Monat deshalb mit calendar: "gregory" an oder wandle ihn vor dem Formatieren mit withCalendar() um.
Die Methode ist für die Anzeige in der Oberfläche gedacht. Zum Speichern oder Übertragen solltest du toString() oder toJSON() verwenden. Diese liefern das stabile ISO-Format ("2021-08").
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $locales | string | string[] | Intl.Locale | undefined | Standard-Gebietsschema der Laufzeitumgebung | BCP-47-Sprachkennung(en) wie "de-DE" oder ["de-AT", "de"]. Erweiterungen wie -u-ca-japanese legen den Kalender fest. Dieser muss zum Kalender des Objekts passen. |
| $options | object | undefined | { year: "numeric", month: "numeric" } | Optionen wie bei Intl.DateTimeFormat, z. B. year, month, era, dateStyle oder calendar. Uhrzeit-Optionen (hour, minute, timeStyle …) sowie day und weekday sind nicht erlaubt und lösen einen TypeError aus. |
Rückgabewert
"August 2021".Beispiele
Monat ausgeschrieben auf Deutsch und Englisch
// Kalender "gregory" passt zu de-DE und en-US
const ym = Temporal.PlainYearMonth.from({ year: 2021, month: 8, calendar: "gregory" });
console.log(ym.toLocaleString("de-DE", { year: "numeric", month: "long" }));
console.log(ym.toLocaleString("en-US", { year: "numeric", month: "long" }));
console.log(ym.toLocaleString("en-US"));Fehler beim ISO-Kalender vermeiden
const ym = Temporal.PlainYearMonth.from("2024-03"); // Kalender iso8601
try {
ym.toLocaleString("de-DE");
} catch (err) {
console.log(err.constructor.name);
}
// Lösung: vorher in den gregorianischen Kalender umwandeln
const anzeige = ym.withCalendar("gregory")
.toLocaleString("de-DE", { month: "long", year: "numeric" });
console.log(anzeige);Abrechnungszeiträume in einer Liste anzeigen
const start = Temporal.PlainYearMonth.from({ year: 2024, month: 11, calendar: "gregory" });
const zeitraeume = Array.from({ length: 3 }, (_, i) =>
start.add({ months: i }).toLocaleString("de-DE", { month: "short", year: "numeric" })
);
console.log(zeitraeume.join(" | "));Japanischer Kalender mit Ära
const ym = Temporal.PlainYearMonth.from({ year: 2021, month: 8, calendar: "japanese" });
console.log(ym.toLocaleString("ja-JP-u-ca-japanese", { era: "long", year: "numeric", month: "long" }));// Wichtig · Fallstricke
- Kalender muss passen: Anders als bei
PlainDatewird beim Formatieren vonPlainYearMonth(undPlainMonthDay) nicht automatisch umgerechnet. Wenn der Kalender vom Kalender des Gebietsschemas abweicht, kommt es zu einemRangeError. Das gilt auch füriso8601im Vergleich zugregory. Abhilfe schafftwithCalendar(). - Nicht erlaubte Optionen:
day,weekday, Uhrzeit-Felder undtimeStylelösen einenTypeErroraus. - Performance: Bei jedem Aufruf wird intern ein neues
Intl.DateTimeFormaterzeugt. Wenn du viele Werte formatierst, lege lieber einmalnew Intl.DateTimeFormat(...)an und rufe dessenformat()wiederholt auf. - Ausgabe nicht auswerten: Das Ergebnis kann sich zwischen Browsern und ICU-Versionen unterscheiden, zum Beispiel bei Abkürzungen oder Leerzeichen. Werte die Zeichenkette deshalb nicht maschinell aus. Für Daten verwendest du
toString(). - Kompatibilität: Temporal ist noch nicht in allen Browsern verfügbar (Safari fehlt bisher). Für ältere Umgebungen gibt es das Polyfill
@js-temporal/polyfill.