Chapter 05·The Intl Toolbox·~6 min·
List, Range, and Duration Formatting
List conjunctions, date intervals, numeric ranges, and durations follow locale-specific grammatical patterns. Intl.ListFormat, formatRange, selectRange, and Intl.DurationFormat apply CLDR rules without manual string concatenation.
Overview
Joining array items with a hardcoded comma and conjunction breaks in other languages. Conjunction words, spacing, and range punctuation depend on the target locale and sometimes on the phonetic start of the next word. `Intl.ListFormat`, `formatRange`, and `Intl.DurationFormat` apply these rules automatically.
Core rule
Format lists with Intl.ListFormat, format date and number intervals with formatRange, and select range plural categories with Intl.PluralRules.prototype.selectRange.
Specification note: Spanish formats Spain and Italy as España e Italia, changing y to e before an i sound, but formats Italia y España in reverse order.
Failure mode
Joining arrays with items.join(", ") or concatenating ranges with format(start) + " – " + format(end) hardcodes English punctuation across all locales. A comma join omits localized conjunctions and fails in Japanese, which separates items with the ideographic comma (、). Manual range concatenation repeats shared date fields, hardcodes dash spacing, and ignores range plural rules. For example, the range 0–1 takes the other category in English (0–1 items) but takes one in French (0–1 élément).
Joining lists with commas and 'and' fails in international contexts. Different languages use unique conjunctions, disjunctions, and punctuation symbols.
Business stakes & user risk
Hardcoded list formatting causes grammatical errors in Spanish ('e' instead of 'y' before 'i' sounds), Japanese (ideographic comma without spaces), and Arabic.
Rule of thumb
Format arrays of names, locations, or items using Intl.ListFormat instead of array.join(', ').
The Novice Trap vs. Production Standard
Contrast the intuitive assumption with the architecture required for global releases.
“All languages connect items using commas and the word 'and' before the last item.”
Naive approach: Array join with hardcoded conjunction
const text = items.slice(0, -1).join(", ") + " and " + items.slice(-1);Defect:In Spanish, 'Irene y Inés' is grammatically incorrect (must be 'Irene e Inés'). In Japanese, it introduces alien Latin commas and English words.
Spanish changes 'y' to 'e' depending on phonetics. Japanese uses ideographic commas without spaces. Arabic places 'و' before every item.
Production standard: Intl.ListFormat
new Intl.ListFormat(locale, { style: "long", type: "conjunction" }).format(items);Benefit:Automatically handles language-specific conjunction words, phonetic rules, and typographic punctuation marks.
Cross-Functional Review Questions
Questions for product managers, designers, engineers, and testers to ask during sprint reviews.
“Are dynamic lists of users, tags, or options formatted via Intl.ListFormat?”
“Do grouped badge and tag containers accommodate localized conjunction lengths?”
“Are disjunctions ('or') and unit lists ('5 ft, 10 in') formatted appropriately?”
“Are two-item and three-item list variations verified across Spanish and CJK locales?”
Mechanism
Locale-sensitive list patterns
Joining an array of strings with array.join(', ') hardcodes English punctuation and conjunction rules. Locales differ in list separators, conjunction words, and serial comma rules. Japanese separates items with the ideographic comma (、), Arabic repeats the conjunction و before every item after the first, and US English includes a serial comma before and (A, B, and C) whereas German omits it (A, B und C).
CLDR defines three list pattern types for each locale: conjunction (and-lists), disjunction (or-lists), and unit (measurements such as 5 ft, 7 in). Intl.ListFormat formats an array of strings using the active locale's pattern and width (long, short, or narrow).
Interactive demo
Guided exercises
- 1With the default items, compare the en-US and de-DE rows in the results grid. en-US long style includes the serial comma before the conjunction (“apples, oranges, pears, and bananas”), whereas de-DE omits the comma before und (“apples, oranges, pears und bananas”).
- 2Switch the Scenario to “Unit · 'A B C' (use for adjacent units, e.g. '1h 20m')” with Style “narrow”. Most locales join narrow units with spaces, German and Polish keep a conjunction, and Chinese and Japanese join units with no space.
- 3In the date-range section, keep the default Start date (2026-01-03) and End date (2026-01-05) and compare the en-US and ja-JP rows. Then move End date into March (2026-03-05). en-US collapses the shared month and year to “Jan 3 – 5, 2026”, whereas ja-JP repeats both full dates (`2026/01/03~2026/01/05`). Moving the end date to March causes en-US to print both month names.
- 4Set Range start to 0 and Range end to 1, then read the selectRange table. English resolves the 0–1 range to `other` even though `select(1)` is `one`. French resolves the 0–1 range to `one`.
- 5Set Range start and Range end both to 3, with Format as “Plain number”. When both endpoints format to the same string, `formatRange` outputs a single approximate value: `~3` in en-US, `≈3` in de-DE, and `約3` in ja-JP.
- 6In the durations section, change Hours, Minutes, and the Duration style select. Browsers that support `Intl.DurationFormat` format multi-unit durations using the locale's unit-list pattern.
Conjunction · 'A, B, and C' · style: long
Conjunction, long style: en-US keeps the Oxford comma and en-GB drops it. Chinese separates items with 、 and joins the last with 和; Arabic puts و before every item after the first.
Date ranges · formatRange
CLDR range patterns set which shared fields print once, per locale.
Number ranges · formatRange
CLDR data sets the range pattern, whether the currency symbol repeats, and the approximately sign used when both endpoints format the same (~3 in en-US, ≈3 in de-DE, 約3 in ja-JP).
Plural form of a range · selectRange
CLDR maps each pair of start and end categories to the category of the range, per language. The table uses the Range start and Range end values above.
| Locale | select(2) | select(4) | selectRange(2, 4) |
|---|---|---|---|
| en | other | other | other |
| fr | other | other | other |
| de | other | other | other |
| pl | few | few | few |
| ru | few | few | few |
| ar | two | few | few |
| ja | other | other | other |
For 0–1, English gives other and French one, although select(1) is one in both.
Durations · Intl.DurationFormat
Intl.DurationFormat formats a duration record (hours, minutes, and so on) per locale, in four styles. Some engines do not ship it yet.
Which API to use
- •
Intl.ListFormat: joining items with "and" / "or". Never writearr.join(", ")in user-facing strings. - •
DateTimeFormat.formatRange/NumberFormat.formatRange: two endpoints shown together (dates, prices, counts). - •
PluralRules.selectRange: the plural form for "2–4 items". - •
Intl.DurationFormat: "1 hr, 20 min". Not in every engine; feature-detect first. - • Relative time ("3 days ago"):
Intl.RelativeTimeFormat, covered in the Formatters chapter.
Implementation rules
- Format arrays with
Intl.ListFormat. Selecttype: "conjunction"for “and” lists,type: "disjunction"for “or” lists, andtype: "unit"for measurements. - Format date intervals with
DateTimeFormat.prototype.formatRange. The method collapses shared year or month fields and inserts locale-specific range punctuation, such as Jan 3 – 5, 2026 inen-USand 3.–5. Jan. 2026 inde-DE. - Format numeric intervals with
NumberFormat.prototype.formatRange. It positions currency symbols once per range and marks identical rounded endpoints with the locale's approximation sign (~3inen-US,≈3inde-DE). - Select range plural forms with
PluralRules.prototype.selectRange. Pass both start and end values so CLDR resolves the grammatical category for the full interval rather than a single endpoint. - Format compound durations with
Intl.DurationFormat. UseIntl.DurationFormatfor multi-unit time spans and provide a feature-detection fallback for older runtimes.
Operational context
Roles
Workflow stages
- ·Formatting lists, summaries, and activity feeds
- ·Rendering date, price, and quantity intervals
- ·Component library review
Production incident
In O'Connor v. Oakhurst Dairy (2017), the US First Circuit Court of Appeals ruled that a missing serial comma in a Maine overtime statute created a legal ambiguity in a list of exempted activities. The dairy settled the resulting dispute in 2018 for $5 million.