Signatur
Beschreibung
Intl.DurationFormat ist Teil der ECMAScript-Internationalisierungs-API und ermöglicht die lokalisierte Darstellung von Zeitdauern – etwa „3 Stunden, 25 Minuten und 10 Sekunden" auf Deutsch oder „3 hr., 25 min., 10 sec." auf Englisch. Damit entfällt die Notwendigkeit, Einheiten und Trennzeichen manuell zu übersetzen oder Bibliotheken einzubinden.
Eine Dauer wird als einfaches Objekt mit numerischen Feldern wie years, months, weeks, days, hours, minutes, seconds, milliseconds, microseconds und nanoseconds übergeben. Felder, die nicht angegeben werden, werden ignoriert. Negative Werte werden unterstützt, um z. B. vergangene Zeiträume auszudrücken.
Über den Konstruktor lassen sich Locale und Optionen wie der style ("long", "short", "narrow", "digital") sowie granulare Einheitenstile und die gewünschte fractionalDigits-Präzision steuern. Die Methode format() gibt einen fertig lokalisierten String zurück, während formatToParts() die einzelnen Tokens als Array liefert – nützlich für benutzerdefiniertes Styling.
Wann verwenden? Immer dann, wenn Zeitdauern (Timer, Countdowns, Laufzeiten, Altersdifferenzen) für Endnutzer lesbar und sprachgerecht dargestellt werden sollen – ohne eigene Übersetzungstabellen pflegen zu müssen.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $locales | string | string[] | Systemsprache des Browsers/Laufzeit | Ein BCP-47-Sprach-Tag (z. B. "de", "en-US", "fr-FR") oder ein Array davon. Der beste verfügbare Locale wird automatisch ausgewählt. |
| $options | object | {} | Optionsobjekt zur Steuerung der Formatierung. Wichtige Felder:
|
Rückgabewert
Intl.DurationFormat-Instanz, die über format() und formatToParts() genutzt werden kann.Beispiele
Einfache Dauer auf Deutsch formatieren
const formatter = new Intl.DurationFormat("de", { style: "long" });
const dauer = {
hours: 3,
minutes: 25,
seconds: 10,
};
console.log(formatter.format(dauer));Digitaler Stil (Uhr-Format) auf Englisch
const clockFormatter = new Intl.DurationFormat("en", { style: "digital" });
console.log(clockFormatter.format({ hours: 1, minutes: 8, seconds: 5 }));formatToParts() für benutzerdefiniertes Rendering
const formatter = new Intl.DurationFormat("de", { style: "short" });
const parts = formatter.formatToParts({ minutes: 90, seconds: 45 });
console.log(parts);
// Nur die Werte ausgeben
const values = parts
.filter(p => p.type === "integer")
.map(p => p.value);
console.log(values);Mehrere Locales im Vergleich
const duration = { hours: 2, minutes: 30 };
for (const locale of ["de", "en-US", "fr", "ja", "ar"]) {
const f = new Intl.DurationFormat(locale, { style: "long" });
console.log(`${locale}: ${f.format(duration)}`);
}Unterstützte Locales prüfen (supportedLocalesOf)
const supported = Intl.DurationFormat.supportedLocalesOf(["de", "tlh", "en-US"]);
console.log(supported);// Wichtig · Fallstricke
Browser-Kompatibilität: Intl.DurationFormat ist Teil von ES2024 und seit 2024 in Chrome 129+, Edge 129+, Firefox 128+ und Safari 16.4+ verfügbar. In älteren Umgebungen (insbesondere Node.js < 22) ist die Klasse möglicherweise nicht vorhanden – eine Feature-Erkennung ist empfehlenswert:
if (typeof Intl.DurationFormat !== "undefined") { … }- Als Polyfill eignet sich das Paket @formatjs/intl-durationformat.
Negative Werte: Einzelne Felder dürfen negativ sein, jedoch müssen alle Felder dasselbe Vorzeichen haben – gemischte Vorzeichen werfen einen RangeError.
Kein Temporal.Duration-Objekt nötig: Die API akzeptiert einfache Objekte; eine direkte Integration mit der Temporal-Proposal-API ist jedoch geplant und wird zukünftig unterstützt.