Translating your strings is half of localization. The other half is every number, price, date, and list your app prints. The JavaScript Intl API handles all of it with zero dependencies, using the same Unicode CLDR data that powers Android, iOS, and ICU. This guide covers the formatters you will actually use, the output they produce in real locales, and the bugs that show up when you skip them.
Most apps start with something like `$${price.toFixed(2)}` and `${d.getMonth() + 1}/${d.getDate()}/${d.getFullYear()}`. Both are correct for exactly one country. Here is the same number, 1234567.891, formatted for a handful of locales by Intl.NumberFormat:
| Locale | Output | What changed |
|---|---|---|
en-US |
1,234,567.891 | Comma groups, period decimal |
de-DE |
1.234.567,891 | Separators swapped |
fr-FR |
1 234 567,891 | Narrow no-break space (U+202F) groups |
de-CH |
1'234'567.891 | Apostrophe groups |
en-IN |
12,34,567.891 | Lakh grouping: 3 digits, then 2 |
ar-EG |
١٬٢٣٤٬٥٦٧٫٨٩١ | Arabic-Indic digits by default |
A German user reading 1,234 sees "one point two three four", not "one thousand two hundred thirty-four." That is not a cosmetic issue on an invoice. None of these rules belong in your codebase. They live in the Unicode CLDR, and every modern browser and Node.js release ships it.
const nf = new Intl.NumberFormat("de-DE");
nf.format(1234567.891); // "1.234.567,891"
// Percentages take a ratio, not a percentage
new Intl.NumberFormat("en", { style: "percent", maximumFractionDigits: 1 }).format(0.256);
// "25.6%"
new Intl.NumberFormat("de", { style: "percent" }).format(0.25);
// "25 %" (German puts a space before the sign)
// Units, localized and pluralized for you
new Intl.NumberFormat("de", {
style: "unit",
unit: "kilometer-per-hour",
unitDisplay: "long",
}).format(50);
// "50 Kilometer pro Stunde"
// Signs for deltas and changelogs
new Intl.NumberFormat("en-US", { signDisplay: "exceptZero" }).format(5);
// "+5"Shortening large numbers is a classic place where English assumptions leak. Thousands and millions are not universal units: Japanese groups by ten-thousands (万) and Hindi by lakhs.
const compact = (locale) =>
new Intl.NumberFormat(locale, { notation: "compact" }).format(1234567);
compact("en"); // "1.2M"
compact("de"); // "1,2 Mio."
compact("ja"); // "123万"
compact("hi"); // "12 लाख"Currency formatting has three independent inputs, and mixing them up is the most common pricing-page bug:
EUR): what the money actually is. This comes from your data, never from the user's locale.fr-FR): how to write it, meaning symbol position, separators, and spacing.const price = (locale, currency, amount) =>
new Intl.NumberFormat(locale, { style: "currency", currency }).format(amount);
price("en-US", "EUR", 1234.5); // "EUR 1,234.50"
price("de-DE", "EUR", 1234.5); // "1.234,50 EUR "
price("fr-FR", "EUR", 1234.5); // "1 234,50 EUR "
price("ja-JP", "JPY", 1234.5); // "￥1,235" (yen has no minor unit)
price("en-CA", "USD", 5); // "US$5.00" (disambiguated from CAD)
Notice the last line. A Canadian reading "$5.00" assumes Canadian dollars, so the formatter adds the "US" prefix automatically. Hardcoding a $ throws that context away.
Japanese yen and Korean won have zero decimal places. Kuwaiti dinar and Bahraini dinar have three. If you store money as integer minor units (which you should), ask the formatter how many digits the currency uses instead of dividing by 100:
function fromMinorUnits(amountMinor, currency, locale) {
const nf = new Intl.NumberFormat(locale, { style: "currency", currency });
const digits = nf.resolvedOptions().maximumFractionDigits; // JPY: 0, USD: 2, KWD: 3
return nf.format(amountMinor / 10 ** digits);
}
fromMinorUnits(1999, "USD", "en-US"); // "$19.99"
fromMinorUnits(1999, "JPY", "ja-JP"); // "￥1,999"
fromMinorUnits(1999, "KWD", "en-US"); // "KWD 1.999"Ranges also have a dedicated API, which avoids repeating the symbol awkwardly in some locales:
new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).formatRange(10, 20);
// "$10.00 - $20.00"
03/04/2026 is March 4th in the United States and April 3rd in most of the rest of the world. Never build date strings by hand. Use dateStyle and timeStyle to get the conventional format for each locale:
const d = new Date(Date.UTC(2026, 2, 4, 15, 30));
const fmt = (locale) =>
new Intl.DateTimeFormat(locale, {
dateStyle: "medium",
timeStyle: "short",
timeZone: "UTC",
}).format(d);
fmt("en-US"); // "Mar 4, 2026, 3:30 PM"
fmt("en-GB"); // "4 Mar 2026, 15:30"
fmt("de-DE"); // "04.03.2026, 15:30"
fmt("fr-FR"); // "4 mars 2026, 15:30"
fmt("ja-JP"); // "2026/03/04 15:30"The locale also decides the 12-hour versus 24-hour clock, the order of day and month, and whether month names are capitalized. You get all of it for free.
Locale controls how a moment is written. Time zone controls which wall-clock time it maps to. A user in India with their browser set to en-US still lives in Asia/Kolkata. Store timestamps in UTC, and pass the user's zone explicitly when you render:
new Intl.DateTimeFormat("en-US", {
dateStyle: "full",
timeStyle: "long",
timeZone: "Asia/Kolkata",
}).format(d);
// "Wednesday, March 4, 2026 at 9:00:00 PM GMT+5:30"
// The same instant is already the next day in New Zealand
new Intl.DateTimeFormat("en-US", { dateStyle: "full", timeZone: "Pacific/Auckland" }).format(d);
// "Thursday, March 5, 2026"
The user's zone in the browser is Intl.DateTimeFormat().resolvedOptions().timeZone. Save it on their profile so emails and server-rendered pages use it too.
Some locales default to a calendar other than the Gregorian one. Thai, for example, uses the Buddhist era:
new Intl.DateTimeFormat("th-TH", { year: "numeric" }).format(new Date(2026, 5, 1));
// "พ.ศ. 2569"
If your product needs a specific calendar or digit style regardless of the locale default, override it with a Unicode extension on the locale tag, for example ar-EG-u-nu-latn for Latin digits or en-US-u-hc-h23 for a 24-hour clock. We explain the full tag syntax in our guide to locale codes and BCP 47.
const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
rtf.format(-1, "day"); // "yesterday"
rtf.format(0, "day"); // "today"
rtf.format(2, "week"); // "in 2 weeks"
new Intl.RelativeTimeFormat("es", { numeric: "auto" }).format(-1, "day");
// "ayer"
Without numeric: "auto" you get the more robotic "1 day ago." RelativeTimeFormat handles plural agreement in every language, but it does not pick the unit for you. A small helper does:
const UNITS = [
["year", 31536000], ["month", 2592000], ["week", 604800],
["day", 86400], ["hour", 3600], ["minute", 60], ["second", 1],
];
export function timeAgo(date, locale, now = Date.now()) {
const seconds = Math.round((date.getTime() - now) / 1000);
const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
for (const [unit, size] of UNITS) {
if (Math.abs(seconds) >= size || unit === "second") {
return rtf.format(Math.round(seconds / size), unit);
}
}
}
Joining items with ", " and " and " is grammar, and grammar is locale-specific. Even British and American English disagree about the Oxford comma:
const people = ["Alice", "Bob", "Chen"];
new Intl.ListFormat("en").format(people); // "Alice, Bob, and Chen"
new Intl.ListFormat("en-GB").format(people); // "Alice, Bob and Chen"
new Intl.ListFormat("de").format(people); // "Alice, Bob und Chen"
new Intl.ListFormat("en", { type: "disjunction" }).format(["A", "B", "C"]);
// "A, B, or C"
Intl.DisplayNames replaces the hand-maintained country and language dropdown lists that every project eventually copies from a gist:
new Intl.DisplayNames(["en"], { type: "region" }).of("DE"); // "Germany"
new Intl.DisplayNames(["de"], { type: "region" }).of("DE"); // "Deutschland"
new Intl.DisplayNames(["en"], { type: "language" }).of("pt-BR"); // "Brazilian Portuguese"
new Intl.DisplayNames(["ja"], { type: "currency" }).of("EUR"); // "ユーロ"
For a language switcher, show each language in its own name (new Intl.DisplayNames([code], { type: "language" }).of(code)), so a Japanese speaker who lands on your English site can still find "日本語."
date.toLocaleDateString() with no arguments uses the runtime's default locale and time zone. On your server that might be en-US and UTC. In the browser it is the user's settings. The two renders disagree and React logs a hydration error, or worse, silently shows the wrong date. Always pass the locale and time zone explicitly, from the same source on server and client.
French and some other locales use non-breaking and narrow non-breaking spaces (U+00A0 and U+202F), not regular spaces. A test asserting "1 234,50 EUR " typed with a normal space bar fails. CLDR data also changes between releases, so exact-string snapshots break on Node upgrades. Use formatToParts() to assert on structure instead:
new Intl.NumberFormat("fr-FR").formatToParts(1234.5);
// [
// { type: "integer", value: "1" },
// { type: "group", value: " " }, // U+202F
// { type: "integer", value: "234" },
// { type: "decimal", value: "," },
// { type: "fraction", value: "5" }
// ]
Intl formats but does not parse. parseFloat("1.234,50") returns 1.234. For inputs, use <input type="number"> where it fits, or read the locale's separators from formatToParts() and normalize before parsing.
Constructing an Intl formatter is far more expensive than calling .format() on one. In a table with thousands of cells, create the formatter once per locale and options combination and reuse it:
const cache = new Map();
export function getNumberFormat(locale, options = {}) {
const key = locale + JSON.stringify(options);
if (!cache.has(key)) cache.set(key, new Intl.NumberFormat(locale, options));
return cache.get(key);
}
A user with their browser set to de-DE may be a US customer paying in dollars. The locale says how to display money. Your billing data says which money it is. Keep them separate.
| You need to show | Use |
|---|---|
| Numbers, percentages, units | Intl.NumberFormat |
| Prices | Intl.NumberFormat with style: "currency" |
| Dates and times | Intl.DateTimeFormat with dateStyle/timeStyle and timeZone |
| "3 days ago", "tomorrow" | Intl.RelativeTimeFormat |
| "A, B, and C" | Intl.ListFormat |
| Country, language, currency names | Intl.DisplayNames |
| Plural categories | Intl.PluralRules, or ICU messages (see our ICU MessageFormat guide) |
| Sorting and comparing text | Intl.Collator (see our Unicode strings guide) |
Every API above is supported in all evergreen browsers and current Node.js releases. The MDN Intl reference lists every option.
No. The built-in Intl API covers number, currency, date, time, relative time, list, and plural formatting for every locale in Unicode CLDR, with no bundle cost. Libraries are still useful for date arithmetic and parsing, which Intl does not do.
Use new Intl.NumberFormat(locale, { style: "currency", currency }), where the currency code comes from your data and the locale comes from the user. The formatter handles symbol placement, separators, and the right number of decimal places for each currency.
Calling toLocaleDateString() or Intl.DateTimeFormat without an explicit locale and time zone uses the runtime defaults, which differ between your server and the user's browser. Pass both explicitly, from the same source, during server and client rendering.
The locale controls how a date is written: order, separators, month names, and 12- or 24-hour clock. The time zone controls which local time a moment maps to. They are independent, so a user can prefer English formatting while living in India.
Yes, as long as you create each formatter once and reuse it. Construction is the expensive step; calling format() on a cached formatter is cheap.
Never concatenate a currency symbol, never build a date string by hand, and never assume a thousands separator. Pass a locale and, for dates, a time zone to the matching Intl formatter, cache it, and let CLDR handle the rules for every market you sell into.
Formatting is the code side of localization. The strings around those numbers still need translating and keeping in sync as your product changes. Babelize handles that part inside your Git workflow, so new copy ships in every language alongside the code that uses it.
--- - [All articles](https://www.babelize.co/blogs)