Chapter 08·The Intl Toolbox·~8 min·
Calendars, Eras, and the Week
Non-Gregorian calendar systems, imperial eras, and regional week conventions govern date display across markets. Runtimes store dates in ISO 8601 and convert to local calendars and week metadata at display time.
Overview
The Gregorian calendar is the default for data interchange, but many regions display civil and religious dates in other calendar systems. Era names, month counts, and first-day-of-week rules come from CLDR locale data. `Intl.DateTimeFormat` and `Intl.Locale` expose these rules without external libraries.
Core rule
Store dates as ISO 8601, format them through the locale's resolved calendar system, read week metadata from Intl.Locale, and never run arithmetic on formatted years.
Specification note: In the Thai locale (th-TH), October 2026 formats with the Buddhist Era year 2569, which equals the Gregorian year plus 543.
Failure mode
Date handling fails when code treats the Gregorian year, a single era, and a Sunday or Monday week start as universal constants. The Thai locale (th-TH) defaults to the Thai Buddhist calendar, where new Intl.DateTimeFormat("th-TH", { year: "numeric" }) formats 2026 as พ.ศ. 2569. Parsing that output string as a Gregorian year shifts the date by 543 years.
Official Japanese forms count years within the current imperial era, which resets when a new emperor accedes. Week boundaries also vary by territory. In Saudi Arabia and Israel, the workweek begins on Sunday and the weekend falls on Friday and Saturday.
Billions of people use non-Gregorian calendars for legal, financial, or religious purposes. Hardcoding Gregorian assumptions excludes key global markets.
Business stakes & user risk
In Thailand, official government and banking documents require the Buddhist Era (year 2569 in 2026). Displaying 2026 can invalidate legal documents.
Rule of thumb
Store dates internally as epoch timestamps. Format dates for display using Intl.DateTimeFormat with locale calendar extensions.
The Novice Trap vs. Production Standard
Contrast the intuitive assumption with the architecture required for global releases.
“Everyone uses the Gregorian calendar and records the current year as 2026.”
Naive approach: Hardcoded Gregorian year logic
const year = new Date().getFullYear(); // Always 2026Defect:Thai users expect to see 2569 on official receipts, invoices, and government filings.
Thailand uses the Buddhist calendar (+543 years). Iran and Afghanistan use the Solar Hijri calendar. Saudi Arabia uses the Islamic lunar calendar.
Production standard: Locale-aware calendar formatting
new Intl.DateTimeFormat("th-TH-u-ca-buddhist", { year: "numeric", month: "long", day: "numeric" }).format(new Date());Benefit:Correctly renders '2569' with Thai month names while preserving underlying UTC date integrity.
Cross-Functional Review Questions
Questions for product managers, designers, engineers, and testers to ask during sprint reviews.
“Do our target markets (such as Thailand or Saudi Arabia) require regional calendar support?”
“Are backend timestamps stored strictly in standard UTC epochs rather than pre-formatted strings?”
“Does the date picker component support localized year ranges and era pickers?”
“Are fiscal year and annual reporting calculations validated against local calendars?”
Mechanism
Calendar systems and BCP 47 extensions
A calendar system defines how an instant in time maps to a year, month, and day number. On July 29, 2026 in the Gregorian calendar, the Thai Buddhist calendar reads year 2569, the Saudi Umm al-Qura calendar reads 1448 AH, the Hebrew calendar reads 5786, and the Japanese calendar reads Reiwa 8.
BCP 47 encodes the calendar choice in the -u-ca- Unicode extension subtag, such as en-u-ca-hebrew. When a locale tag omits the -u-ca- extension, Intl.DateTimeFormat selects the default calendar for the locale from CLDR (buddhist for th-TH and persian for fa-IR). Calling resolvedOptions().calendar on the formatter returns the active calendar identifier, and Intl.supportedValuesOf('calendar') lists all calendars supported by the runtime.
Interactive demo
Guided exercises
- 1In One day, eight year counters, set Date (Gregorian) to 2019-05-01. The `japanese` row displays `1 Reiwa` while `gregory` displays `2019`. Stepping back one day to `2019-04-30` changes the `japanese` row to `31 Heisei`.
- 2Set the date to 2026-06-16. The `islamic-umalqura` row reads `Muharram 1, 1448`, marking the Islamic New Year in mid-June. Because the lunar year is 354 or 355 days long, the Hijri New Year moves 10 to 11 days earlier each Gregorian year.
- 3Read the ar-SA row in What your browser ships, then open this page in another browser if one is handy. Current CLDR releases set the default civil calendar for `ar-SA` to `gregory`, whereas older runtimes resolved `ar-SA` to `islamic-umalqura`.
- 4In The shape of the week, compare the ar-SA and he-IL rows against en-US. All three locales start the week on Sunday, but `ar-SA` and `he-IL` mark Friday and Saturday as the weekend.
- 5Read the Min. days column for en-US and de-DE. Runtimes that expose `minimalDays` return `1` for `en-US` and `4` for `de-DE`, reflecting the split between North American and ISO 8601 week numbering.
- 6In What your browser ships, type am-ET into the locale field and press Add locale. Amharic in Ethiopia (`am-ET`) defaults to the `gregory` calendar in CLDR with Ethiopic month names and Latin digits.
One day, eight year counters
Each row formats the same day with a different -u-ca- calendar.
| Calendar | Year reads | Full date (en) |
|---|---|---|
| gregoryThe ISO 8601 and international trade default. | 2026 | Wednesday, July 29, 2026 |
| japaneseGregorian months, with a year count that restarts for each emperor. | 8 Reiwa | Wednesday, July 29, 8 Reiwa |
| buddhistThailand's official calendar. Gregorian + 543. | 2569 BE | Wednesday, July 29, 2569 BE |
| islamic-umalquraSaudi Arabia's calendar. Lunar: a year is 354–355 days. | 1448 AH | Wednesday, Safar 15, 1448 AH |
| hebrewLunisolar: a leap year adds a month, Adar I. | 5786 | Wednesday, 15 Av 5786 |
| persianIran and Afghanistan. Solar, new year at the March equinox. | 1405 AP | Wednesday, Mordad 7, 1405 AP |
| rocTaiwan's official era: year 1 = 1912. | 115 Minguo | Wednesday, July 29, 115 Minguo |
| indianIndia's civil Śaka calendar, published alongside Gregorian. | 1948 Śaka | Wednesday, Sravana 7, 1948 Śaka |
Intl.supportedValuesOf("calendar") lists every calendar the runtime supports.
What your browser ships
Each row is a plain locale tag with no -u-ca- extension; resolvedOptions().calendar reports the default it gets. CLDR changed the ar-SA default from islamic-umalqura to gregory, so a browser with older CLDR data shows the old default.
| Locale tag | Default calendar | Output in this browser |
|---|---|---|
| en-US | — | — |
| th-TH | — | — |
| fa-IR | — | — |
| ar-SA | — | — |
| ja-JP | — | — |
| ja-JP-u-ca-japanese | — | — |
The default is a starting point: device settings can override it. A tag whose language has no locale data falls back to the runtime's default locale.
An era boundary, frame by frame
The Japanese calendar restarts its year count when a new emperor accedes. Shōwa 64 lasted seven days (January 1–7, 1989), and Reiwa 1 began on a Wednesday.
Last day of Shōwa · 1989-01-07
January 7, 64 Shōwa
昭和64年1月7日
First day of Heisei · 1989-01-08
January 8, 1 Heisei
平成元年1月8日
Last day of Heisei · 2019-04-30
April 30, 31 Heisei
平成31年4月30日
First day of Reiwa · 2019-05-01
May 1, 1 Reiwa
令和元年5月1日
Walk across a boundary
May 1, 1 Reiwa
令和元年5月1日
May 1, 2019 · boundary day
Unicode 12.1.0 added a single character for the new era: U+32FF ㋿, the square Reiwa era sign.
The shape of the week
First day and weekend come from Intl.Locale week info in this browser. Shaded cells are the weekend.
Reading week data…
Min. days is the week-numbering rule: the minimum number of days of the new year that week 1 must contain. ISO 8601, used across most of Europe, says 4; the US says 1. A dash means this engine's week info omits the value, as current Chrome's does; CLDR still defines it.
Common false assumptions
- Everyone agrees what year it is. The date above is 2569 BE in Thailand's Buddhist calendar, 1448 AH in Saudi Arabia's Umm al-Qura calendar, and 8 Reiwa in the Japanese calendar.
- A year is 365 days, give or take a leap day. An Islamic calendar year has 354 or 355 days, so a Hijri date falls about 10–11 days earlier in the Gregorian year each year. A Hebrew leap year adds a month.
- Eras are ancient history. Reiwa 1 began on May 1, 2019, and Japanese government forms use era years. A birth-year field that lists only Gregorian years does not match them.
- The weekend is Saturday and Sunday. In Saudi Arabia and Israel it is Friday and Saturday.
- Calendars can be converted with arithmetic. Buddhist is Gregorian + 543, but Umm al-Qura month lengths follow a published Saudi table and Hebrew leap months follow a 19-year cycle.
Implementation rules
- Store dates in ISO 8601 proleptic Gregorian format. Convert to the target calendar only at display time using
Intl.DateTimeFormatand the user's locale or an explicit-u-ca-Unicode extension subtag. - Never perform arithmetic on formatted year strings. Thai Buddhist (+543) and Minguo (-1911) calendars use fixed year offsets, but Islamic Umm al-Qura months follow lunar sightings and Japanese eras change on imperial accession.
- Query week metadata from
Intl.Locale. Read the first day of the week and weekend days fromnew Intl.Locale(tag).getWeekInfo()instead of hardcoding Sunday or Monday. - Update CLDR and ICU dependencies regularly. Calendar era tables are runtime data. Japan announced the Reiwa era one month before it took effect on May 1, 2019.
Operational context
Roles
Workflow stages
- ·Building date pickers, calendars, and scheduling views
- ·Supporting non-Gregorian markets (TH, JP, SA, IR, IL, TW)
- ·Calculating weekly reporting intervals
Production incident
Japan announced the Reiwa era name on April 1, 2019, thirty days before it took effect on May 1, 2019. The Unicode Consortium released Unicode 12.1.0 that May to add a single code point, U+32FF (SQUARE ERA NAME REIWA). Applications that read era definitions from ICU and CLDR updated via data patches, whereas applications with hardcoded era logic required code changes.