Skip to content
Locale Lab

Chapter 03·Common UI Defects·~8 min·

Number, Currency, Date, and Unit Formatting

The ECMAScript Intl APIs format numbers, currencies, dates, and units from CLDR locale tables. The value 1234567.89 formats as 1,234,567.89 in en-US, 1.234.567,89 in de-DE, 1'234'567.89 in de-CH, and 12,34,567.89 in en-IN.

Intl.NumberFormatIntl.DateTimeFormatIntl.RelativeTimeFormat

Overview

Every locale defines specific rules for decimal separators, digit grouping, currency placement, and date order. Hardcoding string templates locks an interface to one region. The ECMAScript `Intl` APIs format values directly from CLDR locale data.

Core rule

Format numbers, currencies, dates, and units with ECMAScript Intl APIs and CLDR locale data. Never construct formatted strings by manual concatenation.

Specification note: In en-IN, the number 1234567.8 formats as 12,34,567.8 with two-digit groups above the thousands place. In de-CH, the group separator is an apostrophe.

Failure mode

Hardcoding $1,234.56 or 12/31/2024 applies en-US formatting rules to every user. In de-DE, the same values format as 1.234,56 $ and 31.12.2024.

Decimal precision, group separators, and digit glyphs vary by locale. Japanese yen (JPY) uses 0 decimal places, while Bahraini dinar (BHD) uses 3. German uses a comma as the decimal separator, and Egyptian Arabic (ar-EG) uses Arabic-Indic digits. Displaying 1,234 to a German user changes a thousand-unit quantity into a decimal fraction near 1.2.

Stakeholder Teaching Aid & Novice Guide
Cross-functional alignment tool

Numbers, dates, times, and currencies follow regional conventions defined in CLDR. Hardcoding separators or currency symbols produces confusing and incorrect data.

Business stakes & user risk

Displaying $1,500 as 1.500 or mixing day/month date ordering (03/04/2026: March 4 or April 3?) leads to payment disputes, scheduling failures, and customer support tickets.

Rule of thumb

Never write custom string concatenation for numbers or dates. Always pass values to Intl.NumberFormat and Intl.DateTimeFormat.

The Novice Trap vs. Production Standard

Contrast the intuitive assumption with the architecture required for global releases.

Naive mental model

“Adding a dollar sign to the front of a number and calling .toFixed(2) handles currency formatting.”

Naive approach: Hardcoded currency and decimal

const displayPrice = "$" + price.toFixed(2); // Outputs: $1500.50

Defect:In Germany, standard format is '1.500,50 USD'. In France, '1 500,50 $US'. Japanese Yen with .toFixed(2) produces invalid fractions like '¥1500.00'.

Production standard

Currencies place symbols before or after numbers, use periods or commas for decimals, and some currencies (such as JPY and KRW) have no decimal units.

Production standard: Intl.NumberFormat

new Intl.NumberFormat(locale, { style: "currency", currency: "USD" }).format(price);

Benefit:Produces culturally accurate symbol placement, decimal separators, and fraction digit precision for all 200+ locales.

Cross-Functional Review Questions

Questions for product managers, designers, engineers, and testers to ask during sprint reviews.

For EngineeringQuestion #1

“Are all frontend and backend date, number, and currency displays generated via Intl APIs?”

What to look for: No instances of manual string slicing, .toFixed(), or custom date formatting regex in code reviews.
For ProductQuestion #2

“Do our checkout and invoice screens support zero-decimal currencies like JPY and KRW?”

What to look for: Payment processors configured to accept and format fractional and non-fractional currencies dynamically.
For DesignQuestion #3

“Does the UI accommodate varying currency symbol lengths and positions?”

What to look for: Layouts that account for trailing currency codes (e.g., '100,00 EUR') and multi-letter prefixes (e.g., 'CAD $').
For QAQuestion #4

“Are date formats verified in both day-first (en-GB, de-DE) and month-first (en-US) locales?”

What to look for: Test cases ensuring ambiguous dates like 03/04/2026 are clearly formatted with written month names.

Mechanism

Declarative options and CLDR patterns

Intl.DateTimeFormat and Intl.NumberFormat accept a BCP 47 locale tag and a declarative options bag rather than a rigid format pattern string. The runtime looks up the target locale in CLDR to resolve field order, separator characters, numbering system, and calendar.

A single options object formats as 4/21/26, 6:30 PM in en-US and 21.04.26, 18:30 in de-DE. In ar-EG, the formatter selects Arabic-Indic digits automatically. In th-TH, it formats the Buddhist Era year 2569.

Number formatting resolves group sizes (1,234,567 in en-US vs 12,34,567 in en-IN), decimal markers, ISO 4217 currency minor units (0 for JPY, 2 for EUR, 3 for BHD), and compact powers (1.2M in English vs 123.5万 in Japanese). When custom typography requires separate styling for currency symbols or decimals, formatToParts() returns an ordered array of typed tokens.

Interactive demo

Guided exercises

  1. 1
    In the money section, switch the currency from USD to JPY while keeping the same numeric amount. The formatter removes the decimal fraction and rounds to an integer because CLDR defines 0 minor units for Japanese yen (and 3 minor units for Bahraini dinar).
  2. 2
    Set the locale to ar-EG and inspect all formatted outputs. The output uses Arabic-Indic digits (١٢٣…) and Arabic thousands and decimal separators (٬ and ٫) because `arab` is the default CLDR numbering system for `ar-EG`.
  3. 3
    Set the calendar dropdown to “Buddhist (Thai)”. The formatted year changes from 2026 to 2569, reflecting the 543-year offset of the Thai Buddhist calendar.
  4. 4
    In the four-locale hero, compare en-US and en-IN for the same numeric value. en-US groups by thousands (1,234,567), whereas en-IN groups by two-digit lakhs and crores above the thousands place (12,34,567).
  5. 5
    In the locale matrix (Date & time mode), set Date style to none, Time style to short, and then set Hour cycle to h23. At default settings, en-US renders a 12-hour clock (6:30 PM) while de-DE and ja-JP render a 24-hour clock (18:30). Setting `hourCycle: 'h23'` overrides the locale default across all rows.
  6. 6
    Switch the locale matrix to Currency mode and step Symbol display through symbol, code, and name. The formatter switches between the localized currency sign, the ISO 4217 code (JPY), and the inflected currency name (“Japanische Yen” in de-DE).

Tag passed to Intl: en-US

One amount, four locales

en-US

$1,234,567.89

US (baseline)

en-IN

$12,34,567.89

Indian grouping

de-CH

$ 1'234'567.89

Swiss apostrophe

ar-EG

‏١٬٢٣٤٬٥٦٧٫٨٩ US$

Arabic-Indic digits

Locale matrix · one option set, eleven locales

The options say what to show; each locale's CLDR data sets how it is written.

LocaleOutputWhat moved
en-USApr 21, 2026, 6:30 PMmonth first, 12-hour
en-GB21 Apr 2026, 18:30day first, 24-hour
de-DE21.04.2026, 18:30dots group, comma decimal
fr-FR21 avr. 2026, 18:30narrow no-break spaces
pt-BR21 de abr. de 2026, 18:30
ru-RU21 апр. 2026 г., 18:30
hi-IN21 अप्रैल 2026, 6:30 pmlakh/crore grouping
th-TH21 เม.ย. 2569 18:30Buddhist calendar by default
ja-JP2026/04/21 18:30year first
zh-CN2026年4月21日 18:30year first
ar-EG٢١‏/٠٤‏/٢٠٢٦، ٦:٣٠ مArabic-Indic digits, RTL

Same instant in every row, in UTC. th-TH prints the Buddhist-era year, 543 ahead of the Gregorian (2569 for 2026), because Buddhist is its default calendar.

Numbers & currency

StyleOutputCode
Decimal1,234,567.89NumberFormat()
Currency$1,234,567.89NumberFormat({ style: 'currency', currency: 'USD' })
Compact1.2MNumberFormat({ notation: 'compact', maximumFractionDigits: 1 })
Percent (0.7321)73.21%NumberFormat({ style: 'percent' })

Minor units (ISO 4217)

Most currencies have 2 decimal places; JPY, KRW, VND, and CLP have 0, and BHD, KWD, OMR, and JOD have 3. Payment code that converts to minor units by multiplying by 100 charges 100× too much in JPY and 10× too little in BHD.

USD · 2 digits
1234567.89 → 123456789
JPY · 0 digits
1234567.89 → 1234568
BHD · 3 digits
1234567.89 → 1234567890

new Intl.NumberFormat(locale, {style:'currency',currency}).resolvedOptions().minimumFractionDigits returns the digit count for any currency.

Units

StyleOutputCode
Unit (long)42.5 kilometersNumberFormat({ style: 'unit', unitDisplay: 'long' })
Unit (narrow)42.5kmNumberFormat({ style: 'unit', unitDisplay: 'narrow' })

Dates & times

StyleOutputCode
short4/21/26{ dateStyle: 'short' }
mediumApr 21, 2026{ dateStyle: 'medium' }
longApril 21, 2026{ dateStyle: 'long' }
full + timeTuesday, April 21, 2026 at 6:30:00 PM UTC{ dateStyle: 'full', timeStyle: 'long' }

Relative time

StyleOutputCode
auto3 days agoRelativeTimeFormat({ numeric: 'auto' })

List formatting

StyleOutputCode
Conjunctionapples, oranges, and pearsListFormat({ type: 'conjunction' })
Disjunctionapples, oranges, or pearsListFormat({ type: 'disjunction' })

Display names

StyleOutputCode
Country 'DE'GermanyDisplayNames({ type: 'region' })
Language 'zh-Hant'Traditional ChineseDisplayNames({ type: 'language' })
Currency 'JPY'Japanese YenDisplayNames({ type: 'currency' })

Segmenter (graphemes & words)

Input

"👩‍👩‍👧‍👦 こんにちは"

Graphemes (7)

👩‍👩‍👧‍👦 こんにちは

Words from "Hello, 世界! How are 你?"

Hello世界Howare你

ICU segments the Chinese with a dictionary: 世界 is one word.

The same amount, formatted for every supported locale

en-US$1,234,567.89
en-GBUS$1,234,567.89
en-IN$12,34,567.89
de-DE1.234.567,89 $
de-CH$ 1'234'567.89
fr-FR1 234 567,89 $US
fr-CA1 234 567,89 $ US
es-ES1.234.567,89 US$
pt-BRUS$ 1.234.567,89
it-IT1.234.567,89 USD
nl-NLUS$ 1.234.567,89
ru-RU1 234 567,89 $
pl-PL1 234 567,89 USD
zh-CNUS$1,234,567.89
zh-TWUS$1,234,567.89
ja-JP$1,234,567.89
ko-KRUS$1,234,567.89
th-THUS$1,234,567.89
hi-IN$12,34,567.89
ar-SA‏١٬٢٣٤٬٥٦٧٫٨٩ US$
ar-EG‏١٬٢٣٤٬٥٦٧٫٨٩ US$
he-IL‏1,234,567.89 ‏$
fa-IR‎$۱٬۲۳۴٬۵۶۷٫۸۹
ur-PK$1,234,567.89

First day of the week & weekend

The first day of the week and the weekend days are locale data (Intl.Locale.weekInfo). A calendar grid hardcoded to a Sunday start and a Saturday–Sunday weekend is wrong in Germany (Monday start) and Saudi Arabia (Friday–Saturday weekend).

startSun
Mon
Tue
Wed
Thu
Fri
Sat

The week starts on Sun. The weekend is Sat + Sun. (The US starts Sunday, most of Europe Monday, much of the Middle East Saturday.)

Measurement systems

Intl formats the unit it is given. It does not convert values or choose a measurement system; application code maps the locale to a system, converts, then formats.

5 km=3.1 mi

The current locale en-US maps to US customary.

Implementation rules

  • Use built-in Intl formatters. Call Intl.NumberFormat, Intl.DateTimeFormat, and Intl.RelativeTimeFormat with the negotiated user locale. These APIs apply CLDR grouping sizes, currency minor units, numbering systems, and date field ordering.
  • Pass ISO 4217 currency codes to Intl.NumberFormat. Configure { style: "currency", currency: "JPY" } and let CLDR set the decimal precision and symbol placement. Do not call .toFixed(2) or concatenate currency symbols.
  • Use formatToParts() for custom typography. When a design styles currency symbols or decimal fractions separately, iterate over the token array from formatToParts(). Never split formatted strings with regular expressions.
  • Format relative times with Intl.RelativeTimeFormat. Replace manual timestamp arithmetic and hardcoded English labels with locale-aware relative time formatting.

Operational context

Roles

EngineeringDesignProduct

Workflow stages

  • ·Building checkout, billing, or analytics views
  • ·Supporting multiple currencies and numbering systems
  • ·Component library API design

Production incident

CLDR specifies `U+202F` (Narrow No-Break Space) as the thousands group separator in French (`1 234,56`). Unit tests that assert against a standard ASCII space (`U+0020`) fail even when the visual output is identical.

MDN: Intl.NumberFormat ↗

Terms in this chapter

Further reading

Related chapters