BigInt.prototype.toLocaleString() — Methode · JavaScript-Referenz

Signatur

BigInt.prototype.toLocaleString(locales, options)

Beschreibung

toLocaleString() wandelt einen BigInt-Wert in einen String um, der den Formatierungsregeln einer Sprache oder Region entspricht. Das betrifft vor allem Tausendertrennzeichen (1.000.000 auf Deutsch, 1,000,000 auf Englisch), die Gruppierung der Ziffern (z. B. im indischen System) sowie Währungs-, Prozent- oder Kompaktdarstellungen.

In Umgebungen mit Intl-Unterstützung (alle modernen Browser und Node.js) gibt die Methode die Arbeit einfach an Intl.NumberFormat weiter. Der Aufruf big.toLocaleString(locales, options) liefert also dasselbe wie new Intl.NumberFormat(locales, options).format(big). Alle Optionen von Intl.NumberFormat gelten deshalb auch hier.

Der große Vorteil gegenüber Number(big).toLocaleString(): Der Wert wird ohne Genauigkeitsverlust formatiert. Das ist wichtig bei sehr großen Ganzzahlen wie Kontoständen in der kleinsten Währungseinheit, Datenbank-IDs, Blockchain-Beträgen oder kryptografischen Werten, die über Number.MAX_SAFE_INTEGER hinausgehen.

Verwende die Methode für einzelne, gelegentliche Ausgaben. Wenn du viele Werte formatieren musst, erzeuge besser einmal ein Intl.NumberFormat-Objekt und nutze es mehrfach.

Parameter

Name	Typ	Default	Beschreibung
$locales	string \| string[] \| Intl.Locale \| undefined	undefined (Standard-Locale der Laufzeitumgebung)	BCP-47-Sprach-Tag wie `"de-DE"` oder `"en-IN"` oder ein Array solcher Tags, das der Reihe nach geprüft wird. Erweiterungen wie `"de-DE-u-nu-arab"` sind möglich.
$options	Intl.NumberFormatOptions \| undefined	undefined	Formatierungsoptionen von `Intl.NumberFormat`, z. B. `style` (`"decimal"`, `"currency"`, `"percent"`, `"unit"`), `currency`, `notation` (`"compact"`, `"scientific"`, `"engineering"`), `useGrouping` oder `minimumIntegerDigits`.

Rückgabewert

Typ

string

Beschreibung

Der formatierte String, der den BigInt-Wert nach den Regeln der gewählten Locale und Optionen darstellt.

Beispiele

Tausendertrennzeichen je nach Region

const einwohnerGesamt = 123456789123456789n;

console.log(einwohnerGesamt.toLocaleString('de-DE'));
console.log(einwohnerGesamt.toLocaleString('en-US'));
console.log(einwohnerGesamt.toLocaleString('en-IN')); // indisches Gruppierungssystem
console.log(einwohnerGesamt.toLocaleString('de-CH'));

123.456.789.123.456.789 123,456,789,123,456,789 1,23,45,67,89,12,34,56,789 123’456’789’123’456’789

Exakte Formatierung im Vergleich zu Number

const riesig = 2n ** 64n + 1n;

// Mit BigInt: exakt
console.log(riesig.toLocaleString('de-DE'));

// Nach Umwandlung in Number: die letzte Ziffer geht verloren
console.log(Number(riesig).toLocaleString('de-DE'));

18.446.744.073.709.551.617 18.446.744.073.709.551.616

Währung und Kompaktdarstellung

// Betrag in Cent speichern, als ganze Euro anzeigen
const budgetEuro = 987654321987n;

console.log(budgetEuro.toLocaleString('de-DE', {
  style: 'currency',
  currency: 'EUR',
  maximumFractionDigits: 0
}));

console.log(1234567n.toLocaleString('de-DE', { notation: 'compact' }));
console.log(1234567n.toLocaleString('en-US', { notation: 'compact' }));

987.654.321.987 € 1,2 Mio. 1.2M

Viele Werte effizient formatieren

// Formatierer einmal erzeugen und wiederverwenden
const fmt = new Intl.NumberFormat('de-DE');

const kontostaende = [10n ** 18n, 42n, -7500000n];
const ausgabe = kontostaende.map((wert) => fmt.format(wert));

console.log(ausgabe);

[ '1.000.000.000.000.000.000', '42', '-7.500.000' ]

// Wichtig · Fallstricke

Performance: Bei jedem Aufruf mit locales/options muss intern ein neuer Formatierer erzeugt werden. In Schleifen oder bei großen Tabellen ist ein wiederverwendetes Intl.NumberFormat-Objekt deutlich schneller.
Ungültige Argumente: Ein fehlerhaftes Sprach-Tag (z. B. \"de_DE\") oder eine ungültige Option (z. B. style: 'currency' ohne currency) löst einen RangeError bzw. TypeError aus.
Keine festen Ausgaben erwarten: Das Ergebnis hängt von den CLDR-Daten der Laufzeitumgebung ab und kann sich zwischen Browsern und Versionen unterscheiden, z. B. durch geschützte Leerzeichen (U+00A0, U+202F) vor dem Währungssymbol. Vergleiche in Tests also nicht mit fest eingetragenen Strings. Zum Speichern oder Übertragen verwendest du toString().
Gruppierung bei kleinen Zahlen: Einige Locales (etwa \"es\" oder \"pl\") setzen bei vierstelligen Zahlen kein Tausendertrennzeichen (1234 statt 1.234).
Nachkommastellen: BigInts sind immer ganzzahlig. Optionen wie minimumFractionDigits fügen nur Nullen an und rechnen keine Werte um.
Ohne Intl (sehr alte oder abgespeckte Laufzeitumgebungen) werden die Argumente ignoriert, und das Ergebnis hängt von der Implementierung ab.

Siehe auch

BigInt.prototype.toString() BigInt.prototype.valueOf() BigInt.asIntN() BigInt.asUintN() Object.prototype.toLocaleString()