Formatting Numbers and Dates

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

Format

Turn a value into text for people to read, without changing the value itself.

Locale

A language and region setting, like en-IN, that decides how numbers and dates are written.

BCP 47 tag

The standard way to write a locale: a language code, then a region code, like hi-IN.

Intl

The built-in object that holds JavaScript's formatting and language tools.

Currency code

The three-letter ISO name of a currency, such as INR, USD or EUR.

Time zone

A region's clock rules, like Asia/Kolkata (UTC+5:30), including summer time changes.

UTC

Coordinated Universal Time: the world's reference clock, with no time zone offset.

Collation

The rules for putting words in alphabetical order in a given language.

No-break space

A space character that stops a line from breaking there. It looks like a space but isn't the normal one.

1. 1

   Add your own currency

   In the first example, add a line that shows n in Japanese yen with the ja-JP locale. Predict: how many decimals does yen get?

2. 2

   Change the clock

   In the second example, add a row for "America/New_York". In January New York is 5 hours behind UTC. Predict the time, then run it.

3. 3

   Try another language

   In the third example, make the relative-time formatter Hindi ("hi") and run it. How is "yesterday" written?

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

1. 1

   Formatting means turning a value into text for people to read. It's different from storing or calculating: keep the real number or date in your code and format it only when showing it. Formatting depends on the locale: a code naming a language and usually a region, written as a BCP 47 language tag such as "en-IN" (English, India), "en-US", "de-DE", "hi-IN" or "ja-JP". If you leave the locale out, the browser uses the user's own setting (navigator.language), which is usually what you want on a real site, but makes output differ from machine to machine.

2. 2

   **Intl.NumberFormat formats numbers. Create a formatter with a locale and options**, then call format(value). style chooses the kind: "decimal" (the default), "currency" (needs a currency code like "INR", "USD", "EUR"), "percent" (multiplies by 100: 0.256 shows as 26%) or "unit" (with unit: "kilometer-per-hour", "megabyte", "liter" and so on). Control decimals with minimumFractionDigits and maximumFractionDigits; show big numbers short with notation: "compact" (1.2M, or 12L for lakh in en-IN); and force a plus sign with signDisplay: "always". Indian grouping (12,34,567) comes automatically from en-IN.

3. 3

   **num.toLocaleString(locale, options)** is a shortcut that takes the same options: (1999.5).toLocaleString("en-IN", { style: "currency", currency: "INR" }). It's handy once, but it builds a new formatter on every call. In a loop or a big table, create one Intl.NumberFormat and reuse its format method: it can be many times faster.

4. 4

   **Intl.DateTimeFormat** formats a Date (Topic 4.6). The quick way is dateStyle and timeStyle, each "full", "long", "medium" or "short". For exact control, list the parts you want instead: weekday, year, month ("numeric", "2-digit", "short", "long"), day, hour, minute, second, timeZoneName. The two ways can't be mixed in one formatter (that throws a TypeError). **timeZone** decides which clock to show: "UTC", "Asia/Kolkata", "America/New_York". Without it, the user's own time zone is used. hourCycle: "h23" gives a 24-hour clock. date.toLocaleDateString(), toLocaleTimeString() and toLocaleString() are the shortcuts.

5. 5

   **More Intl helpers.** Intl.RelativeTimeFormat writes "3 days ago" or "in 2 hours", and with numeric: "auto" says "yesterday" and "tomorrow". Intl.ListFormat joins lists with the right word and commas ("tea, coffee, and juice"). Intl.PluralRules tells you which plural form a number needs ("one" or "other" in English; some languages have six forms), so you never write "1 items". Intl.Collator and str.localeCompare compare strings by a language's alphabet: they put é next to e, and with numeric: true sort item2 before item10.

6. 6

   Rules for reliable formatting. Format at the very end, and never parse formatted text back into numbers ("1.234" means one thousand in German but one point two in English). Don't compare formatted strings in tests unless you fix the locale and time zone, because the browser's locale data (called ICU and CLDR) is updated over time and has changed details like which space goes before "AM". Some locales use special spaces: French groups thousands with a narrow no-break space (U+202F), and German puts a no-break space (U+00A0) before €. They look like spaces but aren't " ".

• ↔

  Relying on the user's default locale and time zone shows each person their own format with zero code, but makes output differ between machines; fixing them makes output predictable but may not match what the visitor expects.

• ↔

  Intl is built in, fast once cached and covers hundreds of locales; date libraries add custom tokens like "DD/MM/YYYY" but add download size and can drift from the browser's locale data.

• I can format numbers, currencies, percentages and units with Intl.NumberFormat.

• I can format a date with dateStyle/timeStyle or chosen parts, in a named timeZone.

• I create formatters once and reuse them.

• I can write relative times, lists and plurals with Intl helpers.

• I can sort strings for people with Intl.Collator or localeCompare.

• I keep values unformatted until display and don't compare formatted strings in tests.