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

Number.prototype.toLocaleString()

Methode

Gibt eine sprach- und regionsabhängig formatierte Darstellung einer Zahl als String zurück, z. B. mit Tausendertrennzeichen, Währung oder Einheit.

seit JavaScript ES3; locales/options-Unterstützung ab ES Intl API Kategorie: method-property

Signatur

Number.prototype.toLocaleString(locales, options)

Beschreibung

toLocaleString() wandelt eine Zahl in einen String um, der den Formatierungsregeln einer bestimmten Sprache bzw. Region folgt. Dazu gehören Dezimal- und Tausendertrennzeichen (1.234,5 im Deutschen, 1,234.5 im Englischen), Ziffernsysteme (z. B. arabisch-indische Ziffern) sowie Währungs-, Prozent- und Einheitenformate.

In Umgebungen mit Unterstützung der Intl-API (alle modernen Browser und Node.js) leitet die Methode ihre Argumente direkt an Intl.NumberFormat weiter. Der Aufruf zahl.toLocaleString(locales, options) entspricht also new Intl.NumberFormat(locales, options).format(zahl). Damit stehen alle Optionen von Intl.NumberFormat zur Verfügung, etwa style, currency, unit, minimumFractionDigits, maximumFractionDigits oder notation.

Die Methode eignet sich für die Anzeige von Zahlen in Benutzeroberflächen – etwa Preise, Statistiken oder Messwerte. Für maschinenlesbare Ausgaben (JSON, CSV, APIs) ist sie ungeeignet, da das Ergebnis je nach Umgebung variiert. Wird kein Locale angegeben, verwendet die Laufzeitumgebung ihr Standard-Locale (Browser- bzw. Systemsprache).

Parameter

Name Typ Default Beschreibung
$locales string | string[] | Intl.Locale | undefined undefined (Standard-Locale der Umgebung) BCP-47-Sprach-Tag wie "de-DE", "en-US" oder "de-CH", bzw. ein Array davon als Priorisierungsliste. Unicode-Erweiterungen wie "ar-EG-u-nu-latn" (Ziffernsystem) sind möglich.
$options object {} Formatierungsoptionen wie bei Intl.NumberFormat, z. B. style ("decimal", "currency", "percent", "unit"), currency, currencyDisplay, unit, unitDisplay, minimumFractionDigits, maximumFractionDigits, maximumSignificantDigits, useGrouping, notation ("compact", "scientific", "engineering") und signDisplay.

Rückgabewert

Typ
string
Beschreibung
Die gemäß Locale und Optionen formatierte Zahl als String. Bei NaN bzw. Infinity wird die lokalisierte Darstellung zurückgegeben (z. B. "NaN", "∞").

Beispiele

Tausendertrennzeichen je nach Sprache

const einwohner = 83155031.5;

console.log(einwohner.toLocaleString('de-DE'));
console.log(einwohner.toLocaleString('en-US'));
console.log(einwohner.toLocaleString('de-CH'));
console.log(einwohner.toLocaleString('hi-IN'));
83.155.031,5 83,155,031.5 83’155’031.5 8,31,55,031.5

Preise als Währung formatieren

const preis = 1299.9;

const formatPreis = (betrag, locale = 'de-DE', currency = 'EUR') =>
  betrag.toLocaleString(locale, { style: 'currency', currency });

console.log(formatPreis(preis));
console.log(formatPreis(preis, 'en-US', 'USD'));
console.log(formatPreis(preis, 'ja-JP', 'JPY'));
1.299,90 € $1,299.90 ￥1,300

Prozent, Nachkommastellen und kompakte Schreibweise

const quote = 0.4567;
console.log(quote.toLocaleString('de-DE', { style: 'percent', maximumFractionDigits: 1 }));

const wert = 3.5;
console.log(wert.toLocaleString('de-DE', { minimumFractionDigits: 2 }));

const aufrufe = 1520000;
console.log(aufrufe.toLocaleString('de-DE', { notation: 'compact' }));
console.log(aufrufe.toLocaleString('en-US', { notation: 'compact' }));
45,7 % 3,50 1,5 Mio. 1.5M

Einheiten und Performance mit Intl.NumberFormat

const tempo = 120;
console.log(tempo.toLocaleString('de-DE', { style: 'unit', unit: 'kilometer-per-hour' }));

// Bei vielen Werten besser einen Formatter wiederverwenden
const fmt = new Intl.NumberFormat('de-DE', { style: 'unit', unit: 'megabyte', unitDisplay: 'short' });
const groessen = [12.5, 740, 1024];
console.log(groessen.map((g) => fmt.format(g)));
120 km/h [ '12,5 MB', '740 MB', '1.024 MB' ]

// Wichtig · Fallstricke

  • Nicht für Datenaustausch verwenden: Das Ergebnis hängt von Locale, Browser und ICU-Version ab. Tests sollten nicht auf exakte Strings prüfen – manche Engines verwenden z. B. geschützte Leerzeichen (U+00A0, U+202F) vor dem €-Zeichen oder dem Prozentzeichen.
  • Kein Zurückparsen: parseFloat(\"1.234,5\") ergibt 1.234. Formatierte Strings lassen sich nicht zuverlässig zurück in Zahlen umwandeln.
  • Performance: Jeder Aufruf erzeugt intern ein neues Intl.NumberFormat-Objekt. Beim Formatieren vieler Werte (Tabellen, Listen) einen Formatter einmal anlegen und format() wiederverwenden.
  • Fehler: Ein ungültiges Locale-Tag löst einen RangeError aus, ebenso style: \"currency\" ohne currency-Option (TypeError) oder ungültige Werte für Nachkommastellen (RangeError, Bereich 0–100).
  • Syntax-Falle: Bei Zahlenliteralen ist 1000.toLocaleString() ein Syntaxfehler; stattdessen (1000).toLocaleString() oder 1000..toLocaleString() schreiben.
  • Rundung: Standardmäßig werden höchstens 3 Nachkommastellen angezeigt (bei Währungen die übliche Anzahl, z. B. 2 für EUR, 0 für JPY).
  • Kompatibilität: Die Optionen style: \"unit\", notation und signDisplay sind seit ca. 2020 in allen modernen Browsern verfügbar. In Node.js vor Version 13 fehlten ohne full-icu die meisten Locales. Für große Ganzzahlen gibt es BigInt.prototype.toLocaleString().

Siehe auch

Intl.NumberFormat Number.prototype.toFixed() Number.prototype.toString() Number.prototype.toPrecision() Date.prototype.toLocaleString() BigInt.prototype.toLocaleString()
← Vorheriger Eintrag Number.prototype.toFixed()