Calendars in ECMAScript

Calendars in ECMAScript ふぁぼん / fabon

Who am I? ふぁぼん / fabon I love web standards and everything related to human languages, cultures, etc. The author of temporal-polyfill-lite , the smallest polyfill (so far) for the Temporal API https://npmx.dev/package/temporal-polyfill-lite A graduate student studying modern Russian history For historians, dealing with various languages, writing systems, calendars, and cultures is a daily task.

• https://npmx.dev/package/temporal-polyfill-lite

Localization, Internationalization, Translation These are different concepts. I’ll explain them based on the W3C definition. https://www.w3.org/International/questions/qa-i18n

• https://www.w3.org/International/questions/qa-i18n

Localization (l10n) Localization refers to the adaptation of a product, application or document content to meet the language, cultural and other requirements of a specific target market (a locale). 日本語訳 (筆者): ローカライズとは、プロダクトやソフトウェア、そして文書を特定マーケット（「ロケール」）の言語や各種の（文化などの）要件に適合 させる作業のことを指す。

Localization (l10n) Translation is part of localization. Translation itself is harder than you might think, btw. Dates, times, numerals, amounts Keyboard layout and usage e.g., problems related to input methods (mainly in Japanese, Chinese, and Korean) Writing systems and fonts RTL scripts (Arabic, Hebrew, Thaana, N’ko…) Vertical writing Some scripts can be written only vertically! (e.g., Mongolian script, Manchu alphabet) Locale-dependent font selection for the same code points CJK Unified Ideographs (the so-called "Chinese font problem" among Japanese speakers) Some users may expect Urdu in Nastaliq style or Bulgarian in Bulgarian-styled Cyrillic

Internationalization (i18n) Internationalization is the design and development of a product, application or document content that enables easy localization for target audiences that vary in culture, region, or language. 日本語訳 (筆者): 国際化はプロダクト、アプリケーション、文書を多様な文化・地域・言語のユーザーに合わせてローカライズしやすくする ための設 計・開発プロセスを指す。

Why is i18n important for web standards? The web should work for everyone Web standards should enable everyone to build their own websites and web apps Web standards should embrace reality Human languages are complicated Human cultures are diverse

Calendar support in ECMAScript Formatting dates in non-Gregorian calendars via toLocaleString and Intl.DateTimeFormat Date arithmetic for non-Gregorian calendars via Temporal Design doc for calendar support in Temporal: https://tc39.es/proposal-temporal/docs/calendarreview.html The API and arithmetic are consistent across calendars An enormous effort was made to achieve this goal

• https://tc39.es/proposal-temporal/docs/calendar-review.html

What should ECMAScript specify about calendars? A list of supported calendars (calendar IDs and what they actually mean) Caveats for calendars that are not rule-based (calendar authorities and well-defined ranges)

Definition of the chinese calendar: Traditional Chinese calendar. Lunisolar calendar, based on data published by the Purple Mountain Observatory for dates between 1900 and 2100 (which complies with GB/T 33661-2017, Calculation and Promulgation of the Chinese Calendar), falling back to an implementation-defined approximation outside that range. The arithmetic year is as in "gregory" , and there are no eras. 筆者訳: 伝統的な中国暦（農暦）。紫金山天文台の発行する暦のデータ（中国暦の計算・公布に関する標準であるGB/T 33661-2017に基づく）に 1900〜2100年の間は準拠し、その外では実装依存の近似計算にフォールバックする。arithmetic yearは "gregory" と同様で、時代・ 年号は存在しない。 Note: arithmetic year is the year number in Temporal.PlainDate.prototype.year

Every Calendar in ECMAScript Explained in `$rest` minutes

more precisely (in MessageFormat2): .input {$rest_minute :number} .match $rest_minute one {{Every Calendar in ECMAScript Explained in {$rest_minute} minute}} * {{Every Calendar in ECMAScript Explained in {$rest_minute} minutes}}

Astronomical constants solar year: 365.24 days in solar calendars, a normal year has 365 days and a leap year (almost once every 4 years) has 366 days lunar month: 29.53 days in a lunar calendar, a month has 29 or 30 days 12 lunar months: 354.36 days (shorter than the solar year) in a lunisolar calendar, leap months are inserted to minimize the gap

iso8601 and gregory the Gregorian calendar iso8601 is a culturally "neutral" model gregory refers to the Gregorian calendar in the real world I wrote a detailed article about them recently https://dnevnik.fabon.info/posts/2026/09/14/gregory-vs-iso8601/

• https://dnevnik.fabon.info/posts/2026/09/14/gregory-vs-iso8601/

buddhist and roc Based on the Gregorian calendar, except for eras buddhist : the proleptic Gregorian calendar with the Buddhist era ( 仏滅紀元) used in Thailand AD (CE) 2026 = BE 2569 Thailand officially used a lunisolar calendar before 1941 roc : the proleptic Gregorian calendar with the ROC era ( 民國紀年 / 民国紀年) 1912 as year 1 China officially used a lunisolar calendar (the chinese calendar) before 1912

japanese The proleptic Gregorian calendar with the Japanese regnal year system (gengō) Only modern eras ( meiji , taisho , showa , heisei , reiwa ) era IDs are based on CLDR Eras and their date ranges are hardcoded into the ECMA-402 spec Fallback to "gregory" before 1872 (the 6th year of the Meiji era) Japan officially used a lunisolar calendar before 1872

What will happen when the Japanese government changes the era? The ID of the new era will be added to the CLDR data It will be the same as the official English spelling proposed by the government The normative change for the new era addition based on CLDR will be agreed upon in a TC39 meeting and merged into ECMA-402 ICU4C and ICU4X will add support for the new era JavaScript engines and browsers pull upstream ICU changes to support the new era or patch the JavaScript engine as a temporary solution The order of steps may vary.

coptic , ethioaa , and ethiopic 30 days * 12 months + 5 days (6 days in leap years) Extra days are treated as a 13th month ( M13 ) in Temporal The rule for leap years is the same as in the Julian calendar Same date, but different year numbering

indian Indian national calendar ( インド国定暦) different from traditional Indian calendars Years are counted in the Shaka era The rule for leap years is the same as in the Gregorian calendar

persian Solar Hijri calendar based on the Hijrah epoch Calendar authority: the Iranian government New year begins on every vernal equinox

Islamic calendar Lunar calendar without leap months The year is 354 or 355 days long (shorter than the solar year) the calendar drifts backward through the Gregorian calendar by about 10 days each year

islamic-civil , islamic-tbla islamic-tbla : rule-based (tabular) Islamic calendar used in some countries and regions islamic-civil : almost the same as islamic-tbla (one-day difference) I don’t know the actual usage of islamic-civil

islamic-umalqura Umm al-Qura Calendar Islamic calendar based on astronomical simulation for civil use in Saudi Arabia well-defined range: 1300 AH to the end of 1600 AH (corresponding to 1882-2182 CE) based on the calendar published by the government of Saudi Arabia Fallback to islamic-civil outside that range Note: Saudi Arabia uses an Islamic calendar based on actual moon sightings to determine Islamic holidays, not the Umm al-Qura Calendar

hebrew the Hebrew calendar a rule-based lunisolar calendar the rules are very complicated has leap months

chinese and dangi traditional East Asian lunisolar calendars leap months are inserted to fill the gap between 12 lunar months and 1 solar year once every 2 or 3 years chinese : used in China and Taiwan implementation-defined before 1900 and after 2100 calendar authority: PRC dangi : used in South Korea implementation-defined before 1900 and after 2050

Links https://tc39.es/proposal-intl-era-monthcode/ https://tc39.es/proposal-temporal/docs/calendar-review.html https://dnevnik.fabon.info/posts/2026/09/14/gregory-vs-iso8601/

• https://tc39.es/proposal-intl-era-monthcode/
• https://tc39.es/proposal-temporal/docs/calendar-review.html
• https://dnevnik.fabon.info/posts/2026/09/14/gregory-vs-iso8601/