راهنمای متنباز · v1.0.0 · MIT
تقویم جلالی (شمسی) برای برنامهنویسها
یک راهنمای کاربردی برای برنامهنویسهایی که میخوان تقویم جلالی (هجری شمسی / خورشیدی) رو بدون دردسر به پروژههاشون اضافه کنن. هر چیزی که لازم دارید اینجا یکجا جمع شده، مستند شده و کامل تست شده: اینکه تقویم شمسی چطور کار میکنه، چطور دقیق حسابش کنیم، کدوم کتابخونهها خروجی درست میدن و کدهای آماده برای ۱۴ زبان که میتونید راحت کپی و استفاده کنید. هدف ما خیلی سادهست: وقت کمتری سر جزئیات تقویم بذاریم و خیالمون راحت باشه که تاریخها توی پروژهمون درست کار میکنن.
- زبان برنامهنویسی، بدون وابستگی
- ۱۴
- روز راستیآزماییشده در هر دو جهت
- ۶۶۵٬۸۳۷
- نمونهٔ تست مرزی
- ۸٬۵۱۰
- کتابخانه و API ارزیابیشده
- ۲۳
امتحان کنید: تبدیل تاریخ
در مرورگر خودتان و با پیادهسازی جاوااسکریپت همین راهنما اجرا میشود.
میلادی ← شمسی
شمسی ← میلادی
فصلهای راهنما
مبانی تقویم
نامها، ماهها، روزهای هفته و تاریخچه
سالهای کبیسه
قانون نجومی، فرمول ۳۳ ساله و اینکه چرا نباید سراغ چرخهٔ ۲۸۲۰ بریم
الگوریتم
توضیح کامل فرمولها همراه با مثال قدمبهقدم
راهنمای پیادهسازی
دیتابیس، تایمزون، محاسبات، گرفتن ورودی، رابط کاربری و چکلیست
بومیسازی (Localization)
اعداد فارسی، ی/ک، نیمفاصله، راستبهچپ (RTL) و نام ماهها
زبانها و کتابخانهها
بررسی کتابخونهها و نمونهکد برای ۱۴ زبان
تعطیلات و مناسبتها
تعطیلات رسمی، چالش مناسبتهای قمری و ساختار داده
خطاهای رایج
۳۳ باگ واقعی که توی پروژههای مختلف دیدیم
تست و بررسی درستی کد
دادههای تست و حداقل تستهایی که باید بنویسید
منابع و مراجع
فهرست تمام منابعی که در نوشتن این راهنما استفاده شده
کد آماده برای ۱۴ زبان
هر پیادهسازی یک فایل است که میتوانید در پروژهتان کپی کنید و تستهای خودش را دارد.
چرا این موضوع مهمه؟ خیلی از کتابخونهها و کدهایی که الان استفاده میشن، باگهای ریز و پنهانی دارن. موقع نوشتن این راهنما، کتابخونههای رایج رو با تقویم رسمی مقایسه کردم: یکی از معروفترینها همین سال گذشته (۱۴۰۳/۱۴۰۴) رو اشتباه حساب میکنه، یکی دیگه هر چهار سال یکبار، دو ماه از سال رو یک روز جابهجا نشون میده، و سومی هم از اسفند ۱۴۰۷ (مارس ۲۰۲۹) به بعد به خطا میخوره. جزئیات کاملش رو میتونید توی بخش زبانها و کتابخانهها ببینید.
تقویم شمسی در یک دقیقه
پیوند به بخش تقویم شمسی در یک دقیقه- سال با نوروز (۱ فروردین) و همزمان با اعتدال بهاری شروع میشه که به میلادی میافته ۲۰، ۲۱ یا ۲۲ مارس (مثلا ۱ فروردین ۱۴۰۴ برابر با ۲۱ مارس ۲۰۲۵ بود).
- ماهها: ۶ ماه اول ۳۱ روزه، ۵ ماه بعدی ۳۰ روزه، و اسفند ۲۹ روزهست (توی سالهای کبیسه ۳۰ روزه).
- هفته از شنبه شروع میشه و جمعه هم تعطیل آخر هفتهست.
- سال کبیسه بر پایهٔ نجومه: قانونش اینه که اگر لحظهٔ تحویل سال قبل از ظهر نصفالنهار ۵۲٫۵ درجهٔ شرقی (ساعت رسمی ایران) باشه، همون روز ۱ فروردینه. نتیجه؟ توی هر دورهٔ ۳۳ ساله ۸ تا سال کبیسه داریم؛ کبیسهها معمولا ۴ سال یکبارن، ولی گاهی فاصلهشون ۵ ساله میشه (مثلا بعد از ۱۴۰۳، کبیسهٔ بعدی سال ۱۴۰۸ هست).
- با این فرمول ساده، نتیجه برای کل بازهٔ سالهای ۱۱۷۸ تا ۳۰۰۰ مو به مو با تقویم رسمی یکی درمیآد:
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', …) - نمونهکد |
| محاسبه و تبدیل تاریخ در جاوااسکریپت | Temporal (با calendar: 'persian')، یا jalaali-js، یا date-fns-jalali |
| پایتون (Python) | persiantools یا jdatetime |
| جاوا / اندروید | ICU4J یا android.icu با fa_IR@calendar=persian |
| Scala | ICU4J یا پیادهسازی 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) | یکی از پیادهسازیهای آماده توی همین مخزن |
نکته: ابزارهای داخلی بر پایهٔ ICU از نسخهٔ ICU 77.1 به بعد (مثلا Node.js 24 به بالا) تا سال ۳۰۰۰ شمسی کاملا دقیق هستن؛ نسخههای قدیمیتر ICU هم تا اسفند ۱۵۰۲ (مارس ۲۱۲۴) درست کار میکنن.
محتوای مخزن
پیوند به بخش محتوای مخزنیک الگوریتم واحد که برای ۱۴ زبان پیادهسازی شده: 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 ببینید.
دادههای تست - data/
پیوند به بخش دادههای تست - data/مجموعهای از تاریخهای دقیق که به روش نجومی محاسبه شدن و با جدول رسمی مرکز تقویم دانشگاه تهران (سالهای ۱۲۰۶ تا ۱۴۹۸) مطابقت دارن. این پوشه شامل فهرست سالهای کبیسه و تاریخ نوروز برای سالهای ۱۱۷۸ تا ۳۰۰۰، ۸٬۵۱۰ نمونه تست تبدیل تاریخ، جدول اصلاح استثناها، و نام ماهها و روزهای هفته از CLDR به ۱۱ زبانه. میتونید از این دادهها برای تست کردن کدهای خودتون استفاده کنید.
ابزارها - tools/
پیوند به بخش ابزارها - tools/calendar-data/(نوشتهشده با Rust): موتور محاسبهٔ نجومی که فایلهای پوشهٔdata/رو تولید و بررسی میکنه، لحظهٔ دقیق تحویل سال رو نشون میده و به تست کتابخونهها امتیاز میده.icu-cross-check/: ابزاری که تکتک روزهای سال ۱۱۷۸ تا ۳۰۰۰ رو در هر ۱۴ زبان با ICU4X، ICU4J، ICU4C، Temporal وPersianCalendarدر .NET مقایسه میکنه.library-evaluation/: اسکریپتهای تست و بررسی ۲۳ کتابخونه و API داخلی، همراه با جدول نتایج.
چطوری همهٔ اینها رو تست کردیم؟
پیوند به بخش چطوری همهٔ اینها رو تست کردیم؟- اول محاسبات نجومی (
tools/calendar-dataبر اساس نصفالنهار ۵۲٫۵ درجه) رو با تمام ۲۹۳ سال جدول رسمی مرکز تقویم دانشگاه تهران (۱۲۰۶ تا ۱۴۹۸) چک کردیم؛ خروجی صددرصد با جدول رسمی و یک پیادهسازی نجومی مستقل یکی بود. - از روی همین محاسبات نجومی، دادههای تست مرجع رو ساختیم.
- هر ۱۴ پیادهسازی رو روی این دادهها اجرا و تست کردیم: 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.
- برای هر ۱۴ زبان، تکتک روزهای سال ۱۱۷۸ تا ۳۰۰۰ رو در هر دو جهت با 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). - هر ورودیای خارج از بازهٔ مجاز (سالهای ۱۰۰٬۰۰۰− تا ۱۰۰٬۰۰۰) به جای اینکه باعث سرریز (Overflow)، هنگ کردن برنامه یا برگردوندن تاریخ اشتباه بشه، با خطا رد میشه. داخل این بازه هم تمام سالها توی همهٔ زبانها و تکتک روزها (۷۳٬۰۴۸٬۸۵۰ روز) توی Rust بررسی شدن و خروجیشون با ICU4X (روزبهروز) و ICU4C/ICU4J 77.1+ و Temporal (سالبهسال) کاملا یکسانه.
- در نهایت، ۲۳ کتابخونهٔ معروف و API داخلی زبانهای مختلف رو هم با همین روش محک زدیم.
مشارکت
پیوند به بخش مشارکتاز هر کمکی (اصلاح متن، اضافه کردن زبان جدید یا بررسی کتابخونههای بیشتر) استقبال میکنیم! برای شروع، یک سر به CONTRIBUTING.md بزنید. فقط یادتون باشه که برای هر نکتهٔ مربوط به تقویم منبع معتبر بیارید و برای هر کدی هم تست بنویسید.
مجوز استفاده (License)
پیوند به بخش مجوز استفاده (License)- کدها (پیادهسازیها، ابزارها و تستها): MIT
- مستندات (
docs/و فایلهای README): CC BY 4.0 - دادههای تولیدشده (
data/*.csv،data/*.txt،data/*.json): CC0 1.0 - فایل
data/official/kabise-1206-1498.txt: نسخهٔ متنی جدول رسمی کبیسههای دانشگاه تهران با مجوز CC0 که روزبه پورنادر از روی فایل PDF رسمی آماده کرده است.
سازنده
پیوند به بخش سازندهگودرز جعفری (Goudarz Jafari) - hi@goudarzjafari.com
تشکر و قدردانی
پیوند به بخش تشکر و قدردانی- ابراهیم بیاگوی، سازندهٔ persian-calendar/calendar، persian-calendar/events و پروژهٔ persian-calendar، بابت کتابخانهٔ تقویم و دادههای آزاد مناسبتها که در نوشتن این راهنما خیلی ازشون یاد گرفتم.
- روزبه پورنادر، بابت کد تقویم نجومی روی نصفالنهار ۵۲٫۵ درجه، جدول اصلاح قاعدهٔ ۳۳ ساله و نسخهٔ متنی جدول رسمی کبیسهها.
- پروژهٔ jalaali، کازیمیرژ بورکوفسکی، ادوارد ریینگولد و ناخوم درشوویتز.
- مرکز تقویم دانشگاه تهران.
- Unicode CLDR/ICU.