Skip to content
Locale Lab

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.

Intl.DateTimeFormat-u-ca-getWeekInfo

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.

Stakeholder Teaching Aid & Novice Guide
Cross-functional alignment tool

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.

Naive mental model

“Everyone uses the Gregorian calendar and records the current year as 2026.”

Naive approach: Hardcoded Gregorian year logic

const year = new Date().getFullYear(); // Always 2026

Defect:Thai users expect to see 2569 on official receipts, invoices, and government filings.

Production standard

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.

For ProductQuestion #1

“Do our target markets (such as Thailand or Saudi Arabia) require regional calendar support?”

What to look for: Product specifications defining requirements for Buddhist or Islamic Hijri calendars on customer documents.
For EngineeringQuestion #2

“Are backend timestamps stored strictly in standard UTC epochs rather than pre-formatted strings?”

What to look for: API contracts passing ISO 8601 strings or millisecond timestamps across all service boundaries.
For DesignQuestion #3

“Does the date picker component support localized year ranges and era pickers?”

What to look for: Calendar widgets that can render Japanese Imperial eras (Reiwa) and Thai Buddhist years.
For QAQuestion #4

“Are fiscal year and annual reporting calculations validated against local calendars?”

What to look for: Verification that annual roll-overs align with local fiscal and regional calendar boundaries.

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

  1. 1
    In 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`.
  2. 2
    Set 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.
  3. 3
    Read 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`.
  4. 4
    In 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.
  5. 5
    Read 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.
  6. 6
    In 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.

CalendarYear readsFull date (en)
gregoryThe ISO 8601 and international trade default.2026Wednesday, July 29, 2026
japaneseGregorian months, with a year count that restarts for each emperor.8 ReiwaWednesday, July 29, 8 Reiwa
buddhistThailand's official calendar. Gregorian + 543.2569 BEWednesday, July 29, 2569 BE
islamic-umalquraSaudi Arabia's calendar. Lunar: a year is 354–355 days.1448 AHWednesday, Safar 15, 1448 AH
hebrewLunisolar: a leap year adds a month, Adar I.5786Wednesday, 15 Av 5786
persianIran and Afghanistan. Solar, new year at the March equinox.1405 APWednesday, Mordad 7, 1405 AP
rocTaiwan's official era: year 1 = 1912.115 MinguoWednesday, July 29, 115 Minguo
indianIndia's civil Śaka calendar, published alongside Gregorian.1948 ŚakaWednesday, 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 tagDefault calendarOutput 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.DateTimeFormat and 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 from new 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

EngineeringProductQA

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.

Unicode 12.1.0 (the single-character release) ↗

Terms in this chapter

Further reading

Related chapters