Open-source guide · v1.0.0 · MIT
Jalali (Persian / Shamsi) Calendar for Developers
A practical, developer-to-developer guide for adding the Jalali calendar (Solar Hijri, Persian, Shamsi — تقویم هجری شمسی) to your software. Everything you need is gathered and tested in one place: how the calendar actually works, how to compute it accurately, which existing libraries you can trust, and ready-to-copy implementations in 14 languages. The goal is simple: spend less time debugging calendar quirks, and ship accurate dates in your apps.
- languages, zero dependencies
- 14
- days verified in both directions
- 665,837
- boundary test vectors
- 8,510
- libraries and APIs evaluated
- 23
Try it: convert a date
Runs in your browser with the JavaScript implementation from this guide.
Gregorian → Persian
Persian → Gregorian
The guide, chapter by chapter
Calendar basics
names, months, weeks, history
Leap years
the astronomical rule, the 33-year rule, why not 2820
The algorithm
step-by-step math with a worked example
Implementation guide
database storage, time zones, arithmetic, parsing, UI, checklist
Localization
digits, ی/ک, ZWNJ, RTL layout, month names
Languages & libraries
test verdicts and code examples for 14 languages
Holidays and events
official holidays, the lunar Hijri challenge, data modeling
Common pitfalls
33 real-world bugs and how to fix them
Testing
reference datasets and the essential test suite
References
official sources, papers, and standards
Ready-to-use code in 14 languages
Each implementation is one file you can copy into your project, with its own test suite.
Why does this matter? A surprising number of popular implementations get the calendar subtly wrong. While writing this guide, I tested common libraries against the official calendar: one widely used library gets last year (1403/1404) wrong, another shifts every date by one day during the first two months of every Gregorian leap year, and a third breaks starting in March 2029. See the full breakdown in Languages & libraries.
The calendar in 60 seconds
Link to section: The calendar in 60 seconds-
New Year: The year starts on Nowruz (1 Farvardin), the day of the March equinox—which falls on 20, 21, or 22 March. For example, 1404 AP began on 21 March 2025.
-
Months: The first 6 months have 31 days, the next 5 have 30 days, and the last month (Esfand) has 29 days—or 30 in a leap year.
-
Weeks: The week starts on Saturday, and Friday is the official weekly holiday.
-
Leap years are astronomical: A new year starts on the day the spring equinox occurs before true noon at 52.5° E (Iran Standard Time). This works out to 8 leap years every 33 years—usually 4 years apart, and occasionally 5 years apart (for example, 1403 → 1408).
-
The arithmetic formula: This simple rule matches the official astronomical calendar across the entire 1178–3000 AP range:
leap(y) = y ∉ C and (y−1 ∈ C or (25y + 11) mod 33 < 8) C = {1502, 1601, 1634, … 78 years …, 2987} (data/corrections.txt) -
Warning: Do not use the popular 2820-year cycle (Birashk's algorithm)—it already disagrees with the official calendar for 1403/1404.
What should I use?
Link to section: What should I use?| If you want to… | Best choice |
|---|---|
| Format and display Persian dates in the browser or Node.js | Built-in Intl.DateTimeFormat('fa-IR', …) — example |
| Do date math or conversions in JavaScript / TypeScript | Temporal with calendar: 'persian', jalaali-js, or date-fns-jalali |
| Work in Python | persiantools or jdatetime |
| Work in Java or Android | ICU4J / android.icu with fa_IR@calendar=persian |
| Work in Scala | ICU4J, or the Scala implementation in this repository |
| Work in C# / .NET | Built-in System.Globalization.PersianCalendar with culture fa-IR |
| Work in Go | go-jalaali or go-persian-calendar |
| Work in Rust | icu_calendar (ICU4X) |
| Work in PHP | Built-in intl (IntlDateFormatter with @calendar=persian) or morilog/jalali |
| Work in Swift / iOS / macOS | Built-in Calendar(identifier: .persian) |
| Work in Dart / Flutter | shamsi_date |
| Work in Ruby, C/C++, SQL, or want zero dependencies | Copy the implementation for your language from this repository |
Built-in ICU APIs are accurate all the way to 3000 AP starting from ICU 77.1 (Node.js 24+ and modern browsers); older ICU versions are accurate up to March 2124 (end of 1502 AP).
What's in this repository
Link to section: What's in this repositoryReady-to-use implementations — implementations/
Link to section: Ready-to-use implementations — implementations/The exact same algorithm implemented in 14 languages: Python, JavaScript, TypeScript, Java, Kotlin, Scala, C#, Go, Rust, PHP, Dart, C (and C++),
Ruby, and PostgreSQL. Every implementation has zero external dependencies, exposes the same clean API (is_leap_year, days_in_month, to_jdn, from_jdn,
to_gregorian, from_gregorian, day_of_week, day_of_year), and passes the same rigorous test suite:
- Every single day from 1178 to 3000 AP (665,837 days) verified in both directions against the astronomical calendar;
- 8,510 Gregorian ↔ Persian boundary test cases, plus every day of the extrapolated years −1000…1177 and 3001…4000;
- Every year across the full supported range (−100000…100000), verified with checksums that match ICU 77.1+, ICU4X, and Temporal;
- Strict input validation: out-of-range dates, huge numbers, non-integers, and invalid Gregorian dates (like Feb 30) are cleanly rejected with an error.
Every language implementation is also cross-checked day by day across 1178–3000 AP against an independent calendar engine:
| Language | Cross-checked against | Language | Cross-checked against |
|---|---|---|---|
| Python | ICU4C 76.1–79.1 | Go | ICU4C 76.1–79.1 (including 32-bit) |
| JavaScript | ICU4C (Intl), Temporal |
Rust | ICU4X 2.4 (every day of the full range) |
| TypeScript | ICU4C (Intl), Temporal |
PHP | ICU4C 77.1 (intl) |
| Java | ICU4J 76.1–79.1 | Dart | ICU4C 76.1–79.1 (VM and web) |
| Kotlin | ICU4J 76.1–79.1 | C / C++ | ICU4C 76.1–79.1 (UBSan, 32-bit) |
| Scala | ICU4J 76.1–79.1 | Ruby | ICU4C 76.1–79.1 |
| C# | ICU4C 76.1–79.1, .NET PersianCalendar |
PostgreSQL | ICU4C (Intl), Temporal |
For the full breakdown of what is verified per language, see implementations/README.md.
Reference test data — data/
Link to section: Reference test data — data/Ground-truth dates computed astronomically and verified against the official table published by the University of Tehran Calendar Center (1206–1498 AP). It includes leap years and Nowruz dates for 1178–3000 AP, 8,510 conversion test vectors, the 78-year correction table, and CLDR month and weekday names in 11 languages. You can drop these files straight into your own project's test suite.
calendar-data/(Rust): the astronomical engine that generates and verifiesdata/, calculates exact equinox times, and scores third-party libraries.icu-cross-check/: tests every day of 1178–3000 AP across all 14 implementations against ICU4X, ICU4J, ICU4C, Temporal, and .NET'sPersianCalendar.library-evaluation/: automated benchmarks and accuracy tests for 23 popular libraries and built-in APIs (see summary).
How everything was verified
Link to section: How everything was verified- Our astronomical engine (
tools/calendar-data, calculated on the 52.5° E meridian) matches all 293 years of the official University of Tehran Calendar Center table (1206–1498 AP) and produces the exact same output as an independent astronomical implementation. - All reference test files in
data/are generated directly from that astronomical engine. - All 14 language implementations are tested against
data/on current runtimes: Python 3.13, Node.js 26, Java 26, Kotlin 2.4, Scala 3.9, .NET 8, Go 1.27, Rust 1.98, PHP 8.5, Dart 3.13, C99 (Zig/Clang), Ruby 4.0, and PostgreSQL 17. - Across all 14 implementations, every day of 1178–3000 AP is cross-checked in both directions against ICU4X 2.4, ICU4J 76.1–79.1,
ICU4C 76.1–79.1, and Temporal. ICU 77.1+, ICU4X, and Temporal agree on every single day; ICU 76.1 lacks the correction table and diverges starting in
1503 AP; .NET's
PersianCalendardiverges starting in 1535 AP (tools/icu-cross-check). - Inputs outside the supported range (years −100000…100000) are rejected with an explicit error instead of overflowing, hanging, or silently returning bogus dates. Within that range, every year is tested in every language, every single day (73,048,850 days) is tested in Rust, and the results match ICU4X (every day) as well as ICU4C/ICU4J 77.1+ and Temporal (every year).
- 23 third-party libraries and built-in APIs were tested against the exact same dataset.
Contributing
Link to section: ContributingBug fixes, improvements, new language implementations, and additional library evaluations are very welcome! Check out CONTRIBUTING.md. Please include a reliable source for any calendar fact and tests for any code changes.
License
Link to section: License- Code (implementations, tools, tests): MIT
- Documentation (
docs/, READMEs): CC BY 4.0 - Generated data (
data/*.csv,data/*.txt,data/*.json): CC0 1.0 data/official/kabise-1206-1498.txtis a CC0 plain-text transcription of the official table prepared by Roozbeh Pournader.
Author
Link to section: AuthorGoudarz Jafari — hi@goudarzjafari.com
Acknowledgements
Link to section: Acknowledgements- Ebrahim Byagowi, creator of persian-calendar/calendar, persian-calendar/events, and the persian-calendar project—for the calendar library and open holiday datasets I learned so much from while writing this guide.
- Roozbeh Pournader—for the astronomical Persian calendar implementation on the 52.5° E meridian, the 78-year correction table for the 33-year rule, and the plain-text transcription of the official leap-year table.
- The jalaali project, Kazimierz Borkowski, Edward Reingold and Nachum Dershowitz, the Calendar Center of the University of Tehran, and the Unicode CLDR/ICU teams.