Skip to content
Tutorials Center
My learning

Topics

Lesson 84 of 133 ยท Compression, CLI and Tooling

Intl, Dates and Formatting

Format numbers, currencies, dates, plurals, lists and relative times in Node.js with Intl, choose locales and time zones explicitly, sort text correctly and avoid common Date pitfalls.

Sooner or later every program has to show a number or a date to a human. The number 1234567.891 is written 1,234,567.891 in the United States, 1.234.567,891 in Germany and 12,34,567.891 in India. The same moment in time is "March 5, 2026" in one country and "5 March 2026" in another, and in Japanese it is written with different characters entirely. If you build these strings by hand with toFixed and string concatenation, your program works for exactly one audience.

JavaScript has a built-in solution called Intl, short for internationalization. It lives in the language itself, so it works the same in Node.js and in browsers, and it needs no npm package. This lesson covers the formatters you will use most, explains how locales and time zones are chosen, and ends with the traps in the older Date object. Because Intl output is plain strings, it is easy to test, which makes it a good match for the node:test runner.

What a locale is

A locale is a short tag that names a language and, optionally, a region: en-US (English as used in the United States), en-GB, de-DE, pt-BR, ja-JP. The tags follow the BCP 47 standard. Every Intl formatter takes a locale as its first argument and uses the data of the Unicode CLDR project to decide how numbers, dates and words look.

Node.js ships with the full ICU library (the code and data behind Intl), so all locales work out of the box. You can check the versions in process.versions, and ask which locales a formatter really supports.

Node.js Locales, ICU and supported values

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A hard rule for server code: never rely on the default locale or the default time zone. On your laptop the default may be en-US and your local zone; on a production server it is often en-US and UTC; inside a container it may be anything. Always pass the locale (and, for dates, the time zone) explicitly, usually taken from the user's profile or from the Accept-Language request header.

Numbers with Intl.NumberFormat

new Intl.NumberFormat(locale, options) creates a formatter, and its format method turns a number into a string. The same number changes shape with the locale:

Node.js One number, many locales

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Options turn the formatter into a tool for money, percentages, units and short numbers:

Node.js Currency, percent, units and compact numbers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Some details professionals care about:

  • Currency is not a locale. de-DE decides how the number looks, but the currency option decides which money it is. Never guess the currency from the locale; a German user can pay in dollars.
  • Rounding. The default rounding mode is "half expand": 2.5 becomes 3 and 3.5 becomes 4. (Check the last two lines above: both round up.) If you need banker's rounding or other rules, newer engines accept a roundingMode option, but for money the safest approach is to keep amounts in integer cents and format only at the edge.
  • Reuse the formatter. Creating a NumberFormat is much more expensive than calling format. Create it once at module level and reuse it, especially in loops that format thousands of values.
  • BigInt works too: format(12345678901234567890n) keeps every digit, where a plain number would lose precision.

Dates with Intl.DateTimeFormat

Dates are harder than numbers because they combine three questions: which calendar and language (the locale), which fields to show (date only? time? weekday?), and which time zone to show them in. A Date object is a single moment in time. The time zone only decides how you read it off the clock.

The easiest options are dateStyle and timeStyle, each of which takes full, long, medium or short. Always pass timeZone explicitly.

Node.js dateStyle, timeStyle and locales

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

You can also pick individual fields (year, month, day, weekday, hour, minute, and so on) when the styles are too coarse. Do not mix dateStyle or timeStyle with those individual fields; JavaScript throws a TypeError if you do.

Time zones

The same instant looks different on different clocks. Intl knows the time zone database, including daylight saving rules, so you give it an IANA zone name such as America/New_York or Asia/Tokyo.

Node.js One moment, five clocks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

When the editor ran this, its own default zone was UTC, which is also what most servers use. That is exactly why you should name the zone: code that "works on my machine" because the laptop is in the right zone breaks the day it is deployed.

For building custom formats, formatToParts returns the pieces as an array of { type, value } objects, which lets you reorder or style them yourself:

Node.js formatToParts: the pieces of a date

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

(For plain ISO dates you do not need Intl at all: moment.toISOString() gives 2026-03-05T14:30:00.000Z, which is the right format for storing and exchanging dates.)

Plurals, lists and relative time

Language is full of little rules that look trivial in English and are not elsewhere. Intl has a formatter for each.

Plural rules. English has two forms ("1 file", "2 files"), but Russian has three or four and Arabic has six. Intl.PluralRules tells you which category a number belongs to (zero, one, two, few, many, other), and you choose the right word for the category. With type: 'ordinal' it handles "1st, 2nd, 3rd, 4th".

Node.js PluralRules for words and ordinals

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Lists. "a, b, and c" in English, "a, b und c" in German: Intl.ListFormat joins items with the right words and punctuation. Relative time. Intl.RelativeTimeFormat produces "yesterday", "in 2 weeks" or "hace 3 meses". Display names turn codes into names: Intl.DisplayNames gives you "Japan" from JP.

Node.js ListFormat, RelativeTimeFormat and DisplayNames

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

RelativeTimeFormat does not look at the clock. You pass a number and a unit and it words the result. To say "3 hours ago" you compute the difference yourself, pick a sensible unit, then call format(-3, 'hour').

Sorting and comparing text with Collator

array.sort() compares text by UTF-16 code unit, which is rarely what people expect: all capitals come before lowercase letters, and accented letters land after "z". Intl.Collator compares the way dictionaries do in a given language.

Node.js Collator: sorting the way humans do

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that in Swedish "ร„" sorts after "Z", while in German it sorts next to "A". The right order depends on the language, which is the whole point. localeCompare on strings uses the same machinery, but constructing one Collator and reusing its compare is faster in a sort with many elements.

Date pitfalls

Intl handles display. The Date object itself has some well-known traps. Knowing them saves hours of debugging.

Node.js Date traps, with the real output

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Rules that keep you out of trouble:

  • Store and transmit UTC. Use toISOString() in JSON, databases and logs. Convert to a local view only when displaying.
  • Always give a time zone when parsing or formatting. A string like 2026-03-05T10:00:00 with no Z or offset is read in the machine's zone, which makes the result machine-dependent.
  • Never do date math by adding milliseconds for "one day" or "one month". Days are not always 24 hours across daylight saving changes, and months have different lengths.
  • Do not print new Date() in tests. Pass the date in, or use a fixed one, so the output is repeatable. See Mocking and Fake Timers.

What about Temporal?

JavaScript is getting a modern replacement for Date called Temporal, with separate types for dates, times, zoned date-times and durations, and no zero-based months. In Node.js 24 the Temporal global is not available (try typeof Temporal: it prints undefined), and it is not enabled by default in the LTS line, so do not build on it yet. Until it arrives, use Date with UTC methods and Intl, or a small library such as date-fns or Luxon if your app does serious calendar arithmetic. Check the current status in the Node.js release notes before relying on it.

Choosing the locale in a server

A typical HTTP server reads the Accept-Language header, picks the best supported locale, and passes it to the formatters. Match carefully: fall back from de-AT to de to your default.

Node.js Picking a locale from Accept-Language

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

A production version would validate the header, cap its length, and cache formatters per locale in a Map so each is created once.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why should server code pass the locale and time zone explicitly to Intl?

    Defaults come from the operating system or container. The same code could print different results on two machines, so name the locale and time zone you mean.
  2. 2. What does Intl.PluralRules('en').select(1) return?

    select returns a category name, not a word. In English 1 is 'one' and most other numbers are 'other'; other languages use more categories such as 'few' and 'many'.
  3. 3. Which line sorts ['file10', 'file2', 'file1'] into natural order?

    A Collator with numeric: true compares digit sequences as numbers, so file2 comes before file10. The default sort compares characters one by one.
  4. 4. What happens when you call setMonth(1) on a Date that is on January 31?

    Date does not clamp. February 31 rolls over into early March, so always check month-end cases when doing month arithmetic.
  5. 5. What is the best format for storing a timestamp in a database or a JSON file?

    ISO 8601 in UTC means the same moment everywhere. Localized or zone-less strings are ambiguous and machine-dependent.

Summary

  • Intl is built into JavaScript and Node.js ships full ICU data, so every locale works without extra packages.
  • Always pass the locale and, for dates, the timeZone explicitly; never trust machine defaults.
  • Intl.NumberFormat formats numbers, currencies, percentages, units and compact numbers; the currency is an option, not a property of the locale.
  • Intl.DateTimeFormat with dateStyle/timeStyle and timeZone shows one moment on any clock; formatToParts gives the pieces.
  • PluralRules, ListFormat, RelativeTimeFormat and DisplayNames handle the grammar of different languages; Collator sorts text the way each language expects.
  • Create formatters once and reuse them; they are expensive to construct.
  • Store dates as UTC ISO strings, beware month overflow and zone-less strings, and do not rely on Temporal in Node.js 24.

Next: V8, Memory and Garbage Collection