</> programmierung.net
Start · Sprachen · JavaScript · Referenz · Temporal.Duration.prototype.toLocaleString()

Temporal.Duration.prototype.toLocaleString()

Methode

Gibt eine sprachabhängige, gut lesbare Darstellung einer <code>Temporal.Duration</code> zurück, z. B. „1 Std., 46 Min. und 40 Sek.“.

seit JavaScript ES2026 (Temporal) – Firefox 139+, Chrome 144+; noc Kategorie: method-property

Signatur

Temporal.Duration.prototype.toLocaleString(locales, options)

Beschreibung

toLocaleString() wandelt eine Temporal.Duration in einen String um, der für Menschen gedacht ist und die Sprache und Konventionen einer bestimmten Locale berücksichtigt. Im Gegensatz zu toString(), das das maschinenlesbare ISO-8601-Format liefert (z. B. PT1H46M40S), erhältst du hier Texte wie „1 Stunde, 46 Minuten und 40 Sekunden“.

In Umgebungen mit Intl.DurationFormat leitet die Methode den Aufruf intern an diese API weiter: duration.toLocaleString(locales, options) entspricht dann new Intl.DurationFormat(locales, options).format(duration). Die Parameter locales und options haben also genau dieselbe Bedeutung wie beim Konstruktor von Intl.DurationFormat.

Die Methode eignet sich für Anzeigen in der Oberfläche: Laufzeiten von Videos, Restzeit eines Uploads, Dauer von Terminen oder Fahrzeiten. Für die Speicherung oder Übertragung solltest du dagegen immer toString() bzw. toJSON() verwenden, weil die Ausgabe von toLocaleString() je nach Engine und Version unterschiedlich ausfallen kann.

Parameter

Name Typ Default Beschreibung
$locales string | string[] | Intl.Locale | undefined Standard-Locale der Laufzeitumgebung BCP-47-Sprachcode (z. B. "de-DE", "en-US") oder eine Liste davon, nach Priorität geordnet.
$options object | undefined {} Formatierungsoptionen wie bei Intl.DurationFormat, u. a.:
  • style: "long", "short" (Standard), "narrow" oder "digital"
  • pro Einheit (years, months, weeks, days, hours, minutes, seconds, milliseconds, …): Stil der Einheit, z. B. "long", "numeric", "2-digit"
  • <einheit>Display: "auto" oder "always" – ob Null-Werte angezeigt werden
  • fractionalDigits: Anzahl der Nachkommastellen (0–9) bei Sekundenbruchteilen
  • numberingSystem: Zahlensystem, z. B. "arab"

Rückgabewert

Typ
string
Beschreibung
Eine sprachabhängige Darstellung der Dauer. Ohne Intl.DurationFormat-Unterstützung ist das Format implementierungsabhängig (häufig identisch mit toString()).

Beispiele

Grundlegende Formatierung in verschiedenen Sprachen

const dauer = Temporal.Duration.from({ hours: 1, minutes: 46, seconds: 40 });

console.log(dauer.toLocaleString("de-DE"));
console.log(dauer.toLocaleString("en-US"));
console.log(dauer.toString()); // zum Vergleich: ISO 8601
1 Std., 46 Min. und 40 Sek. 1 hr, 46 min, 40 sec PT1H46M40S

Stile: long, narrow und digital

const laufzeit = Temporal.Duration.from({ hours: 2, minutes: 5, seconds: 9 });

console.log(laufzeit.toLocaleString("de-DE", { style: "long" }));
console.log(laufzeit.toLocaleString("de-DE", { style: "narrow" }));
// Stoppuhr-Darstellung, z. B. für einen Videoplayer
console.log(laufzeit.toLocaleString("de-DE", { style: "digital" }));
2 Stunden, 5 Minuten und 9 Sekunden 2 Std. 5 Min. 9 Sek. 2:05:09

Restzeit anzeigen – vorher ausbalancieren

const start = Temporal.Now.instant();
const ende = start.add({ seconds: 5430 });

// until() liefert ggf. nur Sekunden – daher mit largestUnit ausbalancieren
const rest = start.until(ende, { largestUnit: "hour" });

console.log(`Noch ${rest.toLocaleString("de-DE", { style: "long" })}`);
Noch 1 Stunde, 30 Minuten und 30 Sekunden

Wiederholte Formatierung mit Intl.DurationFormat

// Bei vielen Werten lohnt sich ein wiederverwendbarer Formatierer
const fmt = new Intl.DurationFormat("de-DE", { style: "short" });

const etappen = [
  { minutes: 42 },
  { hours: 1, minutes: 5 },
  { hours: 3 }
].map((d) => Temporal.Duration.from(d));

etappen.forEach((d) => console.log(fmt.format(d)));
42 Min. 1 Std. und 5 Min. 3 Std.

// Wichtig · Fallstricke

  • Kein automatisches Ausbalancieren: Temporal.Duration.from({ minutes: 90 }).toLocaleString(\"de\") ergibt „90 Min.“ und nicht „1 Std. und 30 Min.“. Wenn nötig, vorher mit duration.round({ largestUnit: \"hour\" }) ausbalancieren. Bei Kalendereinheiten (Monate, Jahre) ist dafür eine relativeTo-Angabe nötig.
  • Ausgabe nicht parsen oder speichern: Der genaue Text (Trennzeichen, Abkürzungen, „und“) hängt von Engine und CLDR-Version ab und kann sich ändern. Für die Speicherung toString()/toJSON() verwenden.
  • Performance: Jeder Aufruf kann intern einen neuen Intl.DurationFormat-Formatierer erzeugen. In Schleifen oder Listen besser einen Formatierer einmal anlegen und format() nutzen.
  • Negative Dauern werden mit Vorzeichen formatiert (z. B. „-1 Std. und 30 Min.“); oft ist duration.abs() mit einem eigenen Text wie „vor …“ lesbarer.
  • Ungültige Locale-Angaben oder Optionswerte lösen einen RangeError aus.
  • Kompatibilität: Temporal ist erst in neueren Browsern verfügbar (Firefox 139+, Chrome 144+); Safari und ältere Umgebungen brauchen ein Polyfill wie @js-temporal/polyfill oder temporal-polyfill. Fehlt Intl.DurationFormat, ist die Ausgabe implementierungsabhängig.

Siehe auch

Temporal.Duration Temporal.Duration.prototype.toString() Temporal.Duration.prototype.toJSON() Temporal.Duration.prototype.round() Intl.DurationFormat Intl.DurationFormat.prototype.format() Temporal.Instant.prototype.until()
← Vorheriger Eintrag Temporal.Duration.prototype.toJSON()