# Jalali Calendar for Developers (تقویم جلالی برای برنامه‌نویس‌ها) > A practical, developer-to-developer guide for adding the Jalali calendar (Solar Hijri, Persian, Shamsi — تقویم هجری شمسی) to your software. Everything you… A bilingual (English and Persian) guide by Goudarz Jafari to adding the Jalali (Persian, Solar Hijri, Shamsi) calendar to software: the astronomical leap-year rule, the 33-year rule with 78 corrections (the same algorithm as ICU 77.1+ and ICU4X), dependency-free code in 14 languages, reference data checked against the University of Tehran Calendar Center table, and an evaluation of 23 libraries. Every link below is plain Markdown; the HTML page has the same address without ".md". Version 1.0.0. Source: https://github.com/Goudarz/PersianCalendar - The whole guide in one file: [English](https://goudarzjafari.com/persian-calendar/llms-full.txt), [Persian](https://goudarzjafari.com/fa/persian-calendar/llms-full.txt) - Code, data and docs as one .zip: https://goudarzjafari.com/persian-calendar/files/persian-calendar-1.0.0.zip - Licenses: text [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), code [MIT](https://opensource.org/license/mit), data [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/) ## Guide - [Jalali (Persian / Shamsi) Calendar for Developers](https://goudarzjafari.com/persian-calendar/index.md): A practical, developer-to-developer guide for adding the Jalali calendar (Solar Hijri, Persian, Shamsi — تقویم هجری شمسی) to your software. Everything you… - [Calendar basics](https://goudarzjafari.com/persian-calendar/basics.md): Calendar basics: names, months, weeks, history. The official calendar of Iran (and Afghanistan, with different month names) goes by several names in English… - [Leap years](https://goudarzjafari.com/persian-calendar/leap-years.md): Leap years are the single trickiest part of the Persian calendar—and the source of almost every bug you'll encounter in existing libraries. - [The algorithm](https://goudarzjafari.com/persian-calendar/algorithm.md): Here is the complete, self-contained specification of the algorithm used by all 14 implementations in this repository. It uses pure integer math, needs no… - [Implementation guide](https://goudarzjafari.com/persian-calendar/implementation-guide.md): This page is a practical architectural guide for adding the Persian calendar to a real-world app, website, backend API, or database. We'll walk through how to… - [Localization](https://goudarzjafari.com/persian-calendar/localization.md): Getting the calendar math right is only half the battle. The other half is typography and text: digits, Persian vs. Arabic characters, half-spaces (ZWNJ)… - [Languages & libraries](https://goudarzjafari.com/persian-calendar/languages-and-libraries.md): Here is a practical breakdown for 14 programming languages: what comes built into the platform, which third-party libraries we actually tested in this… - [Holidays and events](https://goudarzjafari.com/persian-calendar/holidays.md): While leap years can be computed with a mathematical formula, most official holidays in Iran cannot. In your architecture, always treat holidays as versioned… - [Common pitfalls](https://goudarzjafari.com/persian-calendar/pitfalls.md): Here are 33 real-world bugs that show up again and again in Persian calendar code, along with how to spot them and how to fix them. Almost all of these were… - [Testing](https://goudarzjafari.com/persian-calendar/testing.md): Whether you write your own calendar converter or adopt a third-party library, you should never take its accuracy on faith—test it against independent… - [References](https://goudarzjafari.com/persian-calendar/references.md): References: official sources, papers, and standards. ## Implementations - [Implementations](https://goudarzjafari.com/persian-calendar/implementations.md): Copy-ready Jalali calendar code in 14 languages with no dependencies: Python, JavaScript, TypeScript, Java, Kotlin, Scala, C#, Go, Rust, PHP, Dart, C/C++, Ruby and PostgreSQL. - [Persian (Jalali) calendar in Python](https://goudarzjafari.com/persian-calendar/implementations/python.md): Dependency-free Python implementation of the Jalali (Persian, Solar Hijri) calendar: leap years, date validation, Gregorian and Julian Day conversion, weekday and day of year. Verified day by day for 1178–3000 AP. MIT license. - [Persian (Jalali) calendar in JavaScript](https://goudarzjafari.com/persian-calendar/implementations/javascript.md): Dependency-free JavaScript implementation of the Jalali (Persian, Solar Hijri) calendar: leap years, date validation, Gregorian and Julian Day conversion, weekday and day of year. Verified day by day for 1178–3000 AP. MIT license. - [Persian (Jalali) calendar in TypeScript](https://goudarzjafari.com/persian-calendar/implementations/typescript.md): Dependency-free TypeScript implementation of the Jalali (Persian, Solar Hijri) calendar: leap years, date validation, Gregorian and Julian Day conversion, weekday and day of year. Verified day by day for 1178–3000 AP. MIT license. - [Persian (Jalali) calendar in Java](https://goudarzjafari.com/persian-calendar/implementations/java.md): Dependency-free Java implementation of the Jalali (Persian, Solar Hijri) calendar: leap years, date validation, Gregorian and Julian Day conversion, weekday and day of year. Verified day by day for 1178–3000 AP. MIT license. - [Persian (Jalali) calendar in Kotlin](https://goudarzjafari.com/persian-calendar/implementations/kotlin.md): Dependency-free Kotlin implementation of the Jalali (Persian, Solar Hijri) calendar: leap years, date validation, Gregorian and Julian Day conversion, weekday and day of year. Verified day by day for 1178–3000 AP. MIT license. - [Persian (Jalali) calendar in Scala](https://goudarzjafari.com/persian-calendar/implementations/scala.md): Dependency-free Scala implementation of the Jalali (Persian, Solar Hijri) calendar: leap years, date validation, Gregorian and Julian Day conversion, weekday and day of year. Verified day by day for 1178–3000 AP. MIT license. - [Persian (Jalali) calendar in C#](https://goudarzjafari.com/persian-calendar/implementations/csharp.md): Dependency-free C# implementation of the Jalali (Persian, Solar Hijri) calendar: leap years, date validation, Gregorian and Julian Day conversion, weekday and day of year. Verified day by day for 1178–3000 AP. MIT license. - [Persian (Jalali) calendar in Go](https://goudarzjafari.com/persian-calendar/implementations/go.md): Dependency-free Go implementation of the Jalali (Persian, Solar Hijri) calendar: leap years, date validation, Gregorian and Julian Day conversion, weekday and day of year. Verified day by day for 1178–3000 AP. MIT license. - [Persian (Jalali) calendar in Rust](https://goudarzjafari.com/persian-calendar/implementations/rust.md): Dependency-free Rust implementation of the Jalali (Persian, Solar Hijri) calendar: leap years, date validation, Gregorian and Julian Day conversion, weekday and day of year. Verified day by day for 1178–3000 AP. MIT license. - [Persian (Jalali) calendar in PHP](https://goudarzjafari.com/persian-calendar/implementations/php.md): Dependency-free PHP implementation of the Jalali (Persian, Solar Hijri) calendar: leap years, date validation, Gregorian and Julian Day conversion, weekday and day of year. Verified day by day for 1178–3000 AP. MIT license. - [Persian (Jalali) calendar in Dart](https://goudarzjafari.com/persian-calendar/implementations/dart.md): Dependency-free Dart implementation of the Jalali (Persian, Solar Hijri) calendar: leap years, date validation, Gregorian and Julian Day conversion, weekday and day of year. Verified day by day for 1178–3000 AP. MIT license. - [Persian (Jalali) calendar in C / C++](https://goudarzjafari.com/persian-calendar/implementations/c.md): Dependency-free C / C++ implementation of the Jalali (Persian, Solar Hijri) calendar: leap years, date validation, Gregorian and Julian Day conversion, weekday and day of year. Verified day by day for 1178–3000 AP. MIT license. - [Persian (Jalali) calendar in Ruby](https://goudarzjafari.com/persian-calendar/implementations/ruby.md): Dependency-free Ruby implementation of the Jalali (Persian, Solar Hijri) calendar: leap years, date validation, Gregorian and Julian Day conversion, weekday and day of year. Verified day by day for 1178–3000 AP. MIT license. - [Persian (Jalali) calendar in PostgreSQL](https://goudarzjafari.com/persian-calendar/implementations/postgresql.md): Dependency-free PostgreSQL implementation of the Jalali (Persian, Solar Hijri) calendar: leap years, date validation, Gregorian and Julian Day conversion, weekday and day of year. Verified day by day for 1178–3000 AP. MIT license. ## Data and verification - [Reference data](https://goudarzjafari.com/persian-calendar/data.md): Ground-truth datasets for testing any Persian (Solar Hijri / Jalali) calendar implementation. For a complete guide on how to use these files in your tests… - [calendar-data: the astronomical engine](https://goudarzjafari.com/persian-calendar/tools/calendar-data.md): Generates and verifies the ground-truth reference data in /data directly from the astronomical definition of the Solar Hijri calendar, and scores the library… - [ICU / ICU4X cross-check](https://goudarzjafari.com/persian-calendar/tools/icu-cross-check.md): This test suite compares three independent sources across every single day of 1178–3000 AP (665,837 days, 1,823 years): - [Library evaluation](https://goudarzjafari.com/persian-calendar/tools/library-evaluation.md): Library evaluation · Jalali Calendar for Developers. While implementations/ contains our own reference code, this folder tests third-party libraries and… - [Library evaluation results](https://goudarzjafari.com/persian-calendar/tools/library-evaluation/results.md): Generated by tools/calendar-data (score-libraries). Ground truth: data/years.csv (astronomical calendar on the 52.5° E meridian; matches the official table… - [Contributing](https://goudarzjafari.com/persian-calendar/contributing.md): Thanks for taking the time to contribute! The number-one priority of this repository is accuracy, so please back up any calendar claim with a reliable source… ## راهنما به فارسی - [تقویم جلالی (شمسی) برای برنامه‌نویس‌ها](https://goudarzjafari.com/fa/persian-calendar/index.md): یک راهنمای کاربردی برای برنامه‌نویس‌هایی که می‌خوان تقویم جلالی (هجری شمسی / خورشیدی) رو بدون دردسر به پروژه‌هاشون اضافه کنن. هر چیزی که لازم دارید این‌جا… - [مبانی تقویم](https://goudarzjafari.com/fa/persian-calendar/basics.md): مبانی تقویم: نام‌ها، ماه‌ها، روزهای هفته و تاریخچه. تقویم رسمی ایران (و همچنین تقویم افغانستان، البته با نام ماه‌های متفاوت) اسم‌های مختلفی داره که همه‌شون به… - [سال‌های کبیسه](https://goudarzjafari.com/fa/persian-calendar/leap-years.md): تشخیص سال کبیسه تنها بخش واقعا چالش‌برانگیز تقویم شمسیه و بیشتر باگ‌هایی که توی نرم‌افزارها می‌بینیم، ریشه‌شون دقیقا همین‌جاست. - [الگوریتم](https://goudarzjafari.com/fa/persian-calendar/algorithm.md): این صفحه مشخصات کامل الگوریتمی رو توضیح می‌ده که توی تمام پیاده‌سازی‌های این مخزن استفاده شده است. این الگوریتم فقط با اعداد صحیح (Integer) کار می‌کنه، به جز… - [راهنمای پیاده‌سازی](https://goudarzjafari.com/fa/persian-calendar/implementation-guide.md): این صفحه یک راهنمای عملی برای اضافه کردن تقویم شمسی به یک اپلیکیشن، وب‌سایت، کتابخونه یا دیتابیس واقعیه: اینکه چه تصمیم‌هایی باید بگیرید، تقویم کجای معماری… - [بومی‌سازی (Localization)](https://goudarzjafari.com/fa/persian-calendar/localization.md): درست حساب کردن ریاضیات تقویم نیمی از راهه؛ نیمهٔ دیگه‌ش نمایش درست متنه: ارقام فارسی، کدهای یونیکد حروف، جهت نوشتار (RTL) و نام ماه‌ها. - [زبان‌ها و کتابخانه‌ها](https://goudarzjafari.com/fa/persian-calendar/languages-and-libraries.md): در این بخش، وضعیت هر زبان برنامه‌نویسی رو بررسی کردیم: ابزارهای داخلی خود زبان، کتابخونه‌های معروفی که توی همین مخزن تست و محک زده شدن، و نمونه‌کدهای کاربردی.… - [تعطیلات و مناسبت‌ها](https://goudarzjafari.com/fa/persian-calendar/holidays.md): سال‌های کبیسه رو می‌شه با فرمول حساب کرد، اما بیشتر تعطیلات رو نمی‌شه! همیشه به تعطیلات به چشم داده (Data) (که منبع و تاریخ ویرایش داره) نگاه کنید، نه کدی که… - [خطاهای رایج](https://goudarzjafari.com/fa/persian-calendar/pitfalls.md): اینجا فهرست ۳۳ باگ واقعی رو می‌بینید که بارها توی پروژه‌ها و کتابخونه‌های مختلف تکرار شدن، همراه با نشونهٔ هر باگ و راه حلش. بیشتر این باگ‌ها رو موقع نوشتن… - [تست و بررسی درستی کد](https://goudarzjafari.com/fa/persian-calendar/testing.md): چه الگوریتم تبدیل تاریخ رو خودتون بنویسید و چه از یک کتابخونهٔ آماده استفاده کنید، حتما باید اون رو با داده‌های مرجع مستقل تست کنید. توی این مخزن تمام… - [منابع و مراجع](https://goudarzjafari.com/fa/persian-calendar/references.md): منابع و مراجع: فهرست تمام منابعی که در نوشتن این راهنما استفاده شده. ## Optional - [پیاده‌سازی‌ها](https://goudarzjafari.com/fa/persian-calendar/implementations.md): پیاده‌سازی الگوریتم بخش ۳ راهنما برای ۱۴ زبان برنامه‌نویسی؛ همه بدون وابستگی خارجی (Dependency-free)، با مجوز MIT و تست‌شده با داده‌های مرجع /data. کافیه فایل… - [تقویم شمسی (جلالی) در Python](https://goudarzjafari.com/fa/persian-calendar/implementations/python.md): پیاده‌سازی بدون وابستگی تقویم جلالی (هجری شمسی) در Python: تشخیص سال کبیسه، اعتبارسنجی تاریخ، تبدیل به میلادی و شمارهٔ روز جولیانی، روز هفته و روز سال؛ روزبه‌روز برای سال‌های ۱۱۷۸ تا ۳۰۰۰ راستی‌آزمایی شده. مجوز MIT. - [تقویم شمسی (جلالی) در JavaScript](https://goudarzjafari.com/fa/persian-calendar/implementations/javascript.md): پیاده‌سازی بدون وابستگی تقویم جلالی (هجری شمسی) در JavaScript: تشخیص سال کبیسه، اعتبارسنجی تاریخ، تبدیل به میلادی و شمارهٔ روز جولیانی، روز هفته و روز سال؛ روزبه‌روز برای سال‌های ۱۱۷۸ تا ۳۰۰۰ راستی‌آزمایی شده. مجوز MIT. - [تقویم شمسی (جلالی) در TypeScript](https://goudarzjafari.com/fa/persian-calendar/implementations/typescript.md): پیاده‌سازی بدون وابستگی تقویم جلالی (هجری شمسی) در TypeScript: تشخیص سال کبیسه، اعتبارسنجی تاریخ، تبدیل به میلادی و شمارهٔ روز جولیانی، روز هفته و روز سال؛ روزبه‌روز برای سال‌های ۱۱۷۸ تا ۳۰۰۰ راستی‌آزمایی شده. مجوز MIT. - [تقویم شمسی (جلالی) در Java](https://goudarzjafari.com/fa/persian-calendar/implementations/java.md): پیاده‌سازی بدون وابستگی تقویم جلالی (هجری شمسی) در Java: تشخیص سال کبیسه، اعتبارسنجی تاریخ، تبدیل به میلادی و شمارهٔ روز جولیانی، روز هفته و روز سال؛ روزبه‌روز برای سال‌های ۱۱۷۸ تا ۳۰۰۰ راستی‌آزمایی شده. مجوز MIT. - [تقویم شمسی (جلالی) در Kotlin](https://goudarzjafari.com/fa/persian-calendar/implementations/kotlin.md): پیاده‌سازی بدون وابستگی تقویم جلالی (هجری شمسی) در Kotlin: تشخیص سال کبیسه، اعتبارسنجی تاریخ، تبدیل به میلادی و شمارهٔ روز جولیانی، روز هفته و روز سال؛ روزبه‌روز برای سال‌های ۱۱۷۸ تا ۳۰۰۰ راستی‌آزمایی شده. مجوز MIT. - [تقویم شمسی (جلالی) در Scala](https://goudarzjafari.com/fa/persian-calendar/implementations/scala.md): پیاده‌سازی بدون وابستگی تقویم جلالی (هجری شمسی) در Scala: تشخیص سال کبیسه، اعتبارسنجی تاریخ، تبدیل به میلادی و شمارهٔ روز جولیانی، روز هفته و روز سال؛ روزبه‌روز برای سال‌های ۱۱۷۸ تا ۳۰۰۰ راستی‌آزمایی شده. مجوز MIT. - [تقویم شمسی (جلالی) در C#](https://goudarzjafari.com/fa/persian-calendar/implementations/csharp.md): پیاده‌سازی بدون وابستگی تقویم جلالی (هجری شمسی) در C#: تشخیص سال کبیسه، اعتبارسنجی تاریخ، تبدیل به میلادی و شمارهٔ روز جولیانی، روز هفته و روز سال؛ روزبه‌روز برای سال‌های ۱۱۷۸ تا ۳۰۰۰ راستی‌آزمایی شده. مجوز MIT. - [تقویم شمسی (جلالی) در Go](https://goudarzjafari.com/fa/persian-calendar/implementations/go.md): پیاده‌سازی بدون وابستگی تقویم جلالی (هجری شمسی) در Go: تشخیص سال کبیسه، اعتبارسنجی تاریخ، تبدیل به میلادی و شمارهٔ روز جولیانی، روز هفته و روز سال؛ روزبه‌روز برای سال‌های ۱۱۷۸ تا ۳۰۰۰ راستی‌آزمایی شده. مجوز MIT. - [تقویم شمسی (جلالی) در Rust](https://goudarzjafari.com/fa/persian-calendar/implementations/rust.md): پیاده‌سازی بدون وابستگی تقویم جلالی (هجری شمسی) در Rust: تشخیص سال کبیسه، اعتبارسنجی تاریخ، تبدیل به میلادی و شمارهٔ روز جولیانی، روز هفته و روز سال؛ روزبه‌روز برای سال‌های ۱۱۷۸ تا ۳۰۰۰ راستی‌آزمایی شده. مجوز MIT. - [تقویم شمسی (جلالی) در PHP](https://goudarzjafari.com/fa/persian-calendar/implementations/php.md): پیاده‌سازی بدون وابستگی تقویم جلالی (هجری شمسی) در PHP: تشخیص سال کبیسه، اعتبارسنجی تاریخ، تبدیل به میلادی و شمارهٔ روز جولیانی، روز هفته و روز سال؛ روزبه‌روز برای سال‌های ۱۱۷۸ تا ۳۰۰۰ راستی‌آزمایی شده. مجوز MIT. - [تقویم شمسی (جلالی) در Dart](https://goudarzjafari.com/fa/persian-calendar/implementations/dart.md): پیاده‌سازی بدون وابستگی تقویم جلالی (هجری شمسی) در Dart: تشخیص سال کبیسه، اعتبارسنجی تاریخ، تبدیل به میلادی و شمارهٔ روز جولیانی، روز هفته و روز سال؛ روزبه‌روز برای سال‌های ۱۱۷۸ تا ۳۰۰۰ راستی‌آزمایی شده. مجوز MIT. - [تقویم شمسی (جلالی) در C / C++](https://goudarzjafari.com/fa/persian-calendar/implementations/c.md): پیاده‌سازی بدون وابستگی تقویم جلالی (هجری شمسی) در C / C++: تشخیص سال کبیسه، اعتبارسنجی تاریخ، تبدیل به میلادی و شمارهٔ روز جولیانی، روز هفته و روز سال؛ روزبه‌روز برای سال‌های ۱۱۷۸ تا ۳۰۰۰ راستی‌آزمایی شده. مجوز MIT. - [تقویم شمسی (جلالی) در Ruby](https://goudarzjafari.com/fa/persian-calendar/implementations/ruby.md): پیاده‌سازی بدون وابستگی تقویم جلالی (هجری شمسی) در Ruby: تشخیص سال کبیسه، اعتبارسنجی تاریخ، تبدیل به میلادی و شمارهٔ روز جولیانی، روز هفته و روز سال؛ روزبه‌روز برای سال‌های ۱۱۷۸ تا ۳۰۰۰ راستی‌آزمایی شده. مجوز MIT. - [تقویم شمسی (جلالی) در PostgreSQL](https://goudarzjafari.com/fa/persian-calendar/implementations/postgresql.md): پیاده‌سازی بدون وابستگی تقویم جلالی (هجری شمسی) در PostgreSQL: تشخیص سال کبیسه، اعتبارسنجی تاریخ، تبدیل به میلادی و شمارهٔ روز جولیانی، روز هفته و روز سال؛ روزبه‌روز برای سال‌های ۱۱۷۸ تا ۳۰۰۰ راستی‌آزمایی شده. مجوز MIT. - [دادهٔ مرجع](https://goudarzjafari.com/fa/persian-calendar/data.md): این پوشه شامل داده‌های مرجع و راستی‌آزمایی‌شده برای تست هر نوع پیاده‌سازی یا کتابخونهٔ تقویم هجری شمسی (جلالی) است. برای اینکه ببینید چطور می‌تونید با این… - [ابزار محاسبات نجومی و تولید دادهٔ مرجع](https://goudarzjafari.com/fa/persian-calendar/tools/calendar-data.md): این ابزار (نوشته‌شده به زبان Rust و بدون هیچ وابستگی خارجی) داده‌های مرجع پوشهٔ /data رو مستقیما بر اساس تعریف نجومیِ تقویم هجری شمسی تولید و راستی‌آزمایی… - [تطبیق متقابل با موتورهای ICU و ICU4X](https://goudarzjafari.com/fa/persian-calendar/tools/icu-cross-check.md): این مجموعه تست، برای تک‌تک روزهای سال ۱۱۷۸ تا ۳۰۰۰ ه‍.ش (۶۶۵٬۸۳۷ روز در ۱٬۸۲۳ سال)، سه مرجع مستقل رو در هر دو جهت (شمسی به میلادی و میلادی به شمسی) با هم… - [ارزیابی کتابخانه‌ها](https://goudarzjafari.com/fa/persian-calendar/tools/library-evaluation.md): پوشهٔ implementations/ کدهای خود ما رو نگه می‌داره، اما این‌جا کدهای بقیه رو تست می‌کنیم: یعنی همون کتابخونه‌ها و APIهای داخلی‌ای که برنامه‌نویس‌ها همین الان… - [نتایج ارزیابی کتابخانه‌ها](https://goudarzjafari.com/fa/persian-calendar/tools/library-evaluation/results.md): این جدول به صورت خودکار توسط ابزار tools/calendar-data (با دستور score-libraries) و بر مبنای دادهٔ مرجع نجومی در data/years.csv ساخته شده است: - [مشارکت](https://goudarzjafari.com/fa/persian-calendar/contributing.md): ممنون که وقت می‌ذارید و کمک می‌کنید! اولویت اول این مخزن درستی و دقت اطلاعاته، پس برای هر تغییری لطفا یک منبع معتبر یا تست همراهش بذارید.