پرش به محتوای اصلی
فهرست مطالب

راهنمای متن‌باز · v1.0.0 · MIT

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

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

زبان برنامه‌نویسی، بدون وابستگی
۱۴
روز راستی‌آزمایی‌شده در هر دو جهت
۶۶۵٬۸۳۷
نمونهٔ تست مرزی
۸٬۵۱۰
کتابخانه و API ارزیابی‌شده
۲۳

فصل‌های راهنما

  1. مبانی تقویم

    نام‌ها، ماه‌ها، روزهای هفته و تاریخچه

  2. سال‌های کبیسه

    قانون نجومی، فرمول ۳۳ ساله و اینکه چرا نباید سراغ چرخهٔ ۲۸۲۰ بریم

  3. الگوریتم

    توضیح کامل فرمول‌ها همراه با مثال قدم‌به‌قدم

  4. راهنمای پیاده‌سازی

    دیتابیس، تایم‌زون، محاسبات، گرفتن ورودی، رابط کاربری و چک‌لیست

  5. بومی‌سازی (Localization)

    اعداد فارسی، ی/ک، نیم‌فاصله، راست‌به‌چپ (RTL) و نام ماه‌ها

  6. زبان‌ها و کتابخانه‌ها

    بررسی کتابخونه‌ها و نمونه‌کد برای ۱۴ زبان

  7. تعطیلات و مناسبت‌ها

    تعطیلات رسمی، چالش مناسبت‌های قمری و ساختار داده

  8. خطاهای رایج

    ۳۳ باگ واقعی که توی پروژه‌های مختلف دیدیم

  9. تست و بررسی درستی کد

    داده‌های تست و حداقل تست‌هایی که باید بنویسید

  10. منابع و مراجع

    فهرست تمام منابعی که در نوشتن این راهنما استفاده شده

کد آماده برای ۱۴ زبان

هر پیاده‌سازی یک فایل است که می‌توانید در پروژه‌تان کپی کنید و تست‌های خودش را دارد.

چرا این موضوع مهمه؟ خیلی از کتابخونه‌ها و کدهایی که الان استفاده می‌شن، باگ‌های ریز و پنهانی دارن. موقع نوشتن این راهنما، کتابخونه‌های رایج رو با تقویم رسمی مقایسه کردم: یکی از معروف‌ترین‌ها همین سال گذشته (۱۴۰۳/۱۴۰۴) رو اشتباه حساب می‌کنه، یکی دیگه هر چهار سال یک‌بار، دو ماه از سال رو یک روز جابه‌جا نشون می‌ده، و سومی هم از اسفند ۱۴۰۷ (مارس ۲۰۲۹) به بعد به خطا می‌خوره. جزئیات کاملش رو می‌تونید توی بخش زبان‌ها و کتابخانه‌ها ببینید.

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

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

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

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

پیوند به بخش چطوری همهٔ این‌ها رو تست کردیم؟
  1. اول محاسبات نجومی (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).
  5. هر ورودی‌ای خارج از بازهٔ مجاز (سال‌های ۱۰۰٬۰۰۰− تا ۱۰۰٬۰۰۰) به جای اینکه باعث سرریز (Overflow)، هنگ کردن برنامه یا برگردوندن تاریخ اشتباه بشه، با خطا رد می‌شه. داخل این بازه هم تمام سال‌ها توی همهٔ زبان‌ها و تک‌تک روزها (۷۳٬۰۴۸٬۸۵۰ روز) توی Rust بررسی شدن و خروجی‌شون با ICU4X (روزبه‌روز) و ICU4C/ICU4J 77.1+‎ و Temporal (سال‌به‌سال) کاملا یکسانه.
  6. در نهایت، ۲۳ کتابخونهٔ معروف و API داخلی زبان‌های مختلف رو هم با همین روش محک زدیم.

از هر کمکی (اصلاح متن، اضافه کردن زبان جدید یا بررسی کتابخونه‌های بیشتر) استقبال می‌کنیم! برای شروع، یک سر به CONTRIBUTING.md بزنید. فقط یادتون باشه که برای هر نکتهٔ مربوط به تقویم منبع معتبر بیارید و برای هر کدی هم تست بنویسید.

  • کدها (پیاده‌سازی‌ها، ابزارها و تست‌ها): 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.