# تقویم جلالی (شمسی) برای برنامه‌نویس‌ها

یک راهنمای کاربردی برای برنامه‌نویس‌هایی که می‌خوان تقویم جلالی (هجری شمسی / خورشیدی) رو بدون دردسر به پروژه‌هاشون اضافه کنن.
هر چیزی که لازم دارید این‌جا یک‌جا جمع شده، مستند شده و کامل تست شده: اینکه تقویم شمسی چطور کار می‌کنه، چطور دقیق حسابش کنیم، کدوم کتابخونه‌ها خروجی درست می‌دن و کدهای آماده برای ۱۴ زبان که می‌تونید راحت کپی و استفاده کنید. هدف ما خیلی ساده‌ست: **وقت کمتری سر جزئیات تقویم بذاریم و خیالمون راحت باشه که تاریخ‌ها توی پروژه‌مون درست کار می‌کنن.**

> **چرا این موضوع مهمه؟** خیلی از کتابخونه‌ها و کدهایی که الان استفاده می‌شن، باگ‌های ریز و پنهانی دارن. موقع نوشتن این راهنما، کتابخونه‌های رایج رو با تقویم رسمی مقایسه کردم:
> یکی از معروف‌ترین‌ها همین سال _گذشته_ (۱۴۰۳/۱۴۰۴) رو اشتباه حساب می‌کنه، یکی دیگه هر چهار سال یک‌بار، دو ماه از سال رو یک روز جابه‌جا نشون می‌ده، و سومی هم از اسفند ۱۴۰۷ (مارس ۲۰۲۹) به بعد به خطا می‌خوره. جزئیات کاملش رو می‌تونید توی بخش [زبان‌ها و کتابخانه‌ها](https://goudarzjafari.com/fa/persian-calendar/languages-and-libraries/) ببینید.

## تقویم شمسی در یک دقیقه

- سال با **نوروز** (۱ فروردین) و هم‌زمان با اعتدال بهاری شروع می‌شه که به میلادی می‌افته ۲۰، ۲۱ یا ۲۲ مارس (مثلا ۱ فروردین ۱۴۰۴ برابر با ۲۱ مارس ۲۰۲۵ بود).
- **ماه‌ها**: ۶ ماه اول ۳۱ روزه، ۵ ماه بعدی ۳۰ روزه، و اسفند ۲۹ روزه‌ست (توی سال‌های کبیسه ۳۰ روزه).
- **هفته** از **شنبه** شروع می‌شه و جمعه هم تعطیل آخر هفته‌ست.
- **سال کبیسه بر پایهٔ نجومه**: قانونش اینه که اگر لحظهٔ تحویل سال قبل از ظهر نصف‌النهار ۵۲٫۵ درجهٔ شرقی (ساعت رسمی ایران) باشه، همون روز ۱ فروردینه.
  نتیجه؟ توی هر دورهٔ ۳۳ ساله ۸ تا سال کبیسه داریم؛ کبیسه‌ها معمولا ۴ سال یک‌بارن، ولی گاهی فاصله‌شون ۵ ساله می‌شه (مثلا بعد از ۱۴۰۳، کبیسهٔ بعدی سال **۱۴۰۸** هست).
- با این فرمول ساده، نتیجه برای کل بازهٔ سال‌های ۱۱۷۸ تا ۳۰۰۰ مو به مو با تقویم رسمی یکی درمی‌آد:

```
leap(y) = y ∉ C  and  (y−1 ∈ C  or  (25y + 11) mod 33 < 8)
C = {1502, 1601, 1634, … 78 years …, 2987}          (data/corrections.txt)
```

- سراغ الگوریتم معروف **چرخهٔ ۲۸۲۰ ساله نرید**: این الگوریتم همین الان برای سال‌های ۱۴۰۳ و ۱۴۰۴ جواب اشتباه می‌ده!

## از چی استفاده کنم؟

| کاری که می‌خوام بکنم یا زبانی که دارم             | پیشنهاد ما                                                                                                                                    |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| نمایش تاریخ شمسی در مرورگر یا Node.js             | `Intl.DateTimeFormat('fa-IR', …)` - [نمونه‌کد](https://goudarzjafari.com/fa/persian-calendar/languages-and-libraries/#javascript--typescript) |
| محاسبه و تبدیل تاریخ در جاوااسکریپت               | `Temporal` (با `calendar: 'persian'`)، یا `jalaali-js`، یا `date-fns-jalali`                                                                  |
| پایتون (Python)                                   | `persiantools` یا `jdatetime`                                                                                                                 |
| جاوا / اندروید                                    | ICU4J یا `android.icu` با `fa_IR@calendar=persian`                                                                                            |
| Scala                                             | ICU4J یا [پیاده‌سازی Scala](https://goudarzjafari.com/fa/persian-calendar/implementations/scala/) توی همین مخزن                               |
| سی‌شارپ / ‎.NET                                   | کلاس داخلی `System.Globalization.PersianCalendar` با فرهنگ(Culture) `fa-IR`                                                                   |
| Go                                                | `go-jalaali` یا `go-persian-calendar`                                                                                                         |
| Rust                                              | `icu_calendar` (ICU4X)                                                                                                                        |
| PHP                                               | افزونهٔ `intl` (`IntlDateFormatter` با `@calendar=persian`) یا `morilog/jalali`                                                               |
| Swift / iOS / macOS                               | `Calendar(identifier: .persian)`                                                                                                              |
| Dart / Flutter                                    | `shamsi_date`                                                                                                                                 |
| روبی، C، SQL یا کد بدون وابستگی (Zero-dependency) | یکی از [پیاده‌سازی‌های آماده](https://goudarzjafari.com/fa/persian-calendar/implementations/) توی همین مخزن                                   |

نکته: ابزارهای داخلی بر پایهٔ ICU از نسخهٔ **ICU 77.1** به بعد (مثلا Node.js 24 به بالا) تا سال ۳۰۰۰ شمسی کاملا دقیق هستن؛ نسخه‌های قدیمی‌تر ICU هم تا اسفند ۱۵۰۲ (مارس ۲۱۲۴) درست کار می‌کنن.

## محتوای مخزن

### کدهای آماده - [`implementations/`](https://goudarzjafari.com/fa/persian-calendar/implementations/)

یک الگوریتم واحد که برای **۱۴ زبان** پیاده‌سازی شده: Python، JavaScript، TypeScript، Java، Kotlin، Scala، C#‎، Go، Rust، PHP، Dart، C (و C++‎)، Ruby و PostgreSQL.
همهٔ این کدها بدون هیچ وابستگی خارجی (Dependency-free) نوشته شدن، توابع یکسانی دارن (`is_leap_year`، `days_in_month`، `to_jdn`، `from_jdn`، `to_gregorian`، `from_gregorian`، `day_of_week`، `day_of_year`) و همگی از این تست‌ها رد شدن:

- **تک‌تک روزهای سال ۱۱۷۸ تا ۳۰۰۰** (یعنی ۶۶۵٬۸۳۷ روز) در هر دو جهت (شمسی به میلادی و برعکس) با تاریخ دقیق نجومی چک شدن؛
- ۸٬۵۱۰ نمونه تست تبدیل میلادی ↔ شمسی، به‌علاوهٔ تک‌تک روزهای سال‌های ۱۰۰۰− تا ۱۱۷۷ و ۳۰۰۱ تا ۴۰۰۰؛
- **تمام سال‌های بازهٔ مجاز (۱۰۰٬۰۰۰− تا ۱۰۰٬۰۰۰)** که خروجی و جمع کنترلی (Checksum) اون‌ها مو به مو با ICU 77.1+‎، ‏ICU4X و Temporal یکیه؛
- کنترل ورودی‌های نامعتبر: مقادیر خارج از بازه، اعداد بیش از حد بزرگ، ورودی‌های غیرصحیح و تاریخ‌های میلادی نامعتبر همگی با خطای مشخص رد می‌شن.

علاوه بر این، خروجی هر زبان برای تک‌تک روزهای سال ۱۱۷۸ تا ۳۰۰۰ با یک موتور تقویم مستقل هم مقایسه شده:

| زبان       | مقایسه شده با                                  | زبان       | مقایسه شده با                           |
| ---------- | ---------------------------------------------- | ---------- | --------------------------------------- |
| Python     | ICU4C 76.1 تا 79.1                             | Go         | ICU4C 76.1 تا 79.1 (۶۴ و ۳۲ بیتی)       |
| JavaScript | ICU4C (`Intl`)، Temporal                       | Rust       | ICU4X 2.4 (تک‌تک روزهای کل بازه)        |
| TypeScript | ICU4C (`Intl`)، Temporal                       | PHP        | ICU4C 77.1 (`intl`)                     |
| Java       | ICU4J 76.1 تا 79.1                             | Dart       | ICU4C 76.1 تا 79.1 (نسخهٔ VM و وب)      |
| Kotlin     | ICU4J 76.1 تا 79.1                             | C / C++‎   | ICU4C 76.1 تا 79.1 (با UBSan و ۳۲ بیتی) |
| Scala      | ICU4J 76.1 تا 79.1                             | Ruby       | ICU4C 76.1 تا 79.1                      |
| C#‎        | ICU4C 76.1 تا 79.1، `PersianCalendar` در ‎.NET | PostgreSQL | ICU4C (`Intl`)، Temporal                |

فهرست کامل تست‌های هر زبان رو می‌تونید توی [implementations/README.md](https://goudarzjafari.com/fa/persian-calendar/implementations/#what-is-verified-for-each-language) ببینید.

### داده‌های تست - [`data/`](https://goudarzjafari.com/fa/persian-calendar/data/)

مجموعه‌ای از تاریخ‌های دقیق که به روش نجومی محاسبه شدن و با جدول رسمی مرکز تقویم دانشگاه تهران (سال‌های ۱۲۰۶ تا ۱۴۹۸) مطابقت دارن. این پوشه شامل فهرست سال‌های کبیسه و تاریخ نوروز برای سال‌های ۱۱۷۸ تا ۳۰۰۰، ۸٬۵۱۰ نمونه تست تبدیل تاریخ، جدول اصلاح استثناها، و نام ماه‌ها و روزهای هفته از CLDR به ۱۱ زبانه. می‌تونید از این داده‌ها برای تست کردن کدهای خودتون استفاده کنید.

### ابزارها - [`tools/`](https://github.com/Goudarz/PersianCalendar/tree/main/tools)

- [`calendar-data/`](https://goudarzjafari.com/fa/persian-calendar/tools/calendar-data/) (نوشته‌شده با Rust): موتور محاسبهٔ نجومی که فایل‌های پوشهٔ `data/` رو تولید و بررسی می‌کنه، لحظهٔ دقیق تحویل سال رو نشون می‌ده و به تست کتابخونه‌ها امتیاز می‌ده.
- [`icu-cross-check/`](https://goudarzjafari.com/fa/persian-calendar/tools/icu-cross-check/): ابزاری که تک‌تک روزهای سال ۱۱۷۸ تا ۳۰۰۰ رو در هر ۱۴ زبان با ICU4X، ICU4J، ICU4C، Temporal و `PersianCalendar` در ‎.NET مقایسه می‌کنه.
- [`library-evaluation/`](https://goudarzjafari.com/fa/persian-calendar/tools/library-evaluation/): اسکریپت‌های تست و بررسی ۲۳ کتابخونه و API داخلی، همراه با [جدول نتایج](https://goudarzjafari.com/fa/persian-calendar/tools/library-evaluation/results/).

## چطوری همهٔ این‌ها رو تست کردیم؟

1. اول محاسبات نجومی ([`tools/calendar-data`](https://goudarzjafari.com/fa/persian-calendar/tools/calendar-data/) بر اساس نصف‌النهار ۵۲٫۵ درجه) رو با تمام ۲۹۳ سال جدول رسمی مرکز تقویم دانشگاه تهران (۱۲۰۶ تا ۱۴۹۸) چک کردیم؛ خروجی صددرصد با جدول رسمی و یک پیاده‌سازی نجومی مستقل یکی بود.
2. از روی همین محاسبات نجومی، داده‌های تست مرجع رو ساختیم.
3. هر ۱۴ پیاده‌سازی رو روی این داده‌ها اجرا و تست کردیم: 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 و PostgreSQL 17.
4. برای هر ۱۴ زبان، تک‌تک روزهای سال ۱۱۷۸ تا ۳۰۰۰ رو در هر دو جهت با ICU4X 2.4، ‏ICU4J (نسخه‌های 76.1 تا 79.1)، ICU4C (نسخه‌های 76.1 تا 79.1) و Temporal مقایسه کردیم. نتیجه: ICU 77.1 به بعد، ICU4X و Temporal توی همهٔ روزها دقیق هستن؛ ICU 76.1 جدول اصلاح رو نداره و از سال ۱۵۰۳ به بعد اشتباه می‌کنه؛ `PersianCalendar` در ‎.NET هم از سال ۱۵۳۵ به خطا می‌خوره ([`tools/icu-cross-check`](https://goudarzjafari.com/fa/persian-calendar/tools/icu-cross-check/)).
5. هر ورودی‌ای خارج از بازهٔ مجاز (سال‌های ۱۰۰٬۰۰۰− تا ۱۰۰٬۰۰۰) به جای اینکه باعث سرریز (Overflow)، هنگ کردن برنامه یا برگردوندن تاریخ اشتباه بشه، با خطا رد می‌شه. داخل این بازه هم تمام سال‌ها توی همهٔ زبان‌ها و تک‌تک روزها (۷۳٬۰۴۸٬۸۵۰ روز) توی Rust بررسی شدن و خروجی‌شون با ICU4X (روزبه‌روز) و ICU4C/ICU4J 77.1+‎ و Temporal (سال‌به‌سال) کاملا یکسانه.
6. در نهایت، ۲۳ کتابخونهٔ معروف و API داخلی زبان‌های مختلف رو هم با همین روش محک زدیم.

## مشارکت

از هر کمکی (اصلاح متن، اضافه کردن زبان جدید یا بررسی کتابخونه‌های بیشتر) استقبال می‌کنیم! برای شروع، یک سر به [CONTRIBUTING.md](https://goudarzjafari.com/fa/persian-calendar/contributing/) بزنید.
فقط یادتون باشه که برای هر نکتهٔ مربوط به تقویم منبع معتبر بیارید و برای هر کدی هم تست بنویسید.

## مجوز استفاده (License)

- کدها (پیاده‌سازی‌ها، ابزارها و تست‌ها): [MIT](https://github.com/Goudarz/PersianCalendar/blob/main/LICENSE)
- مستندات (`docs/` و فایل‌های README): [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/deed.fa)
- داده‌های تولیدشده (`data/*.csv`، `data/*.txt`، `data/*.json`): [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/deed.fa)
- فایل [`data/official/kabise-1206-1498.txt`](https://goudarzjafari.com/fa/persian-calendar/data/): نسخهٔ متنی جدول رسمی کبیسه‌های دانشگاه تهران با مجوز CC0 که روزبه پورنادر از روی فایل PDF رسمی آماده کرده است.

## سازنده

**گودرز جعفری** (Goudarz Jafari) - <hi@goudarzjafari.com>

## تشکر و قدردانی

- **ابراهیم بیاگوی**، سازندهٔ [persian-calendar/calendar](https://github.com/persian-calendar/calendar)،
  [persian-calendar/events](https://github.com/persian-calendar/events) و پروژهٔ [persian-calendar](https://github.com/persian-calendar)،
  بابت کتابخانهٔ تقویم و داده‌های آزاد مناسبت‌ها که در نوشتن این راهنما خیلی ازشون یاد گرفتم.
- **روزبه پورنادر**، بابت کد تقویم نجومی روی نصف‌النهار ۵۲٫۵ درجه، جدول اصلاح قاعدهٔ ۳۳ ساله و نسخهٔ متنی جدول رسمی کبیسه‌ها.
- پروژهٔ [jalaali](https://github.com/jalaali)، کازیمیرژ بورکوفسکی، ادوارد ریینگولد و ناخوم درشوویتز.
- مرکز تقویم دانشگاه تهران.
- Unicode CLDR/ICU.

---

نشانی صفحه: https://goudarzjafari.com/fa/persian-calendar/
مجوز: متن CC BY 4.0، کد MIT، داده CC0 1.0. نسخهٔ 1.0.0 از https://github.com/Goudarz/PersianCalendar
