تقویم شمسی

Jalali calendar (تقویم شمسی)

Iran runs on the Solar Hijri (Jalali) calendar. Users think in it, laws and invoices use it, fiscal years follow it. Gregorian is for storage and APIs only. Getting this wrong is visible on every screen with a date.

1. The calendar in one table

• The year starts at Nowruz (نوروز), the March equinox, on 20 or 21 March.

• Year 1405 began on 21 March 2026. As a sanity anchor: 20 September 2026 is ۲۹ شهریور ۱۴۰۵.

• Leap years do not follow a simple % 4 rule; use a tested conversion algorithm (VibeFarsi ships lib/jalali.ts, dependency-free and verified). Do not implement leap logic from memory.

2. Week and weekend

• The week starts on Saturday (شنبه). Calendars, date pickers, weekly charts and "this week" ranges all start on Saturday, never Monday.

• Weekday order: شنبه، یکشنبه، دوشنبه، سه‌شنبه، چهارشنبه، پنجشنبه، جمعه.

• Friday is the weekend. Many offices close Thursday afternoon or all day. "Business days" means Saturday–Wednesday (or Thursday, ask the user).

• Intl locales for fa-IR already report Saturday as the first day; do not override it with a Monday-first library default.

3. Time zone

• Iran is UTC+03:30 all year. Daylight saving was abolished; do not apply a summer offset.

• IANA zone: Asia/Tehran. Store instants in UTC (ISO 8601) and convert to Asia/Tehran for display.

• Half-hour offset means naive "round to the hour" logic breaks; always convert through the zone, never by adding hours.

4. Storage and transport

• Database and API: ISO 8601 / Unix time, Gregorian, UTC. Never store a Jalali string as the source of truth.

• Convert to Jalali at the edge (server render or client display).

• If a Jalali date must travel (a filter param, a form field), send it as 1405-06-29 with Latin digits, and validate it with a converter round-trip.

• Birth dates and contract dates entered in Jalali are converted once on input; keep the original Jalali string only for display audit if needed.

5. Display formats

• Persian digits everywhere the user reads; Latin digits in values.

• Month names are never translated or transliterated; take them from a table.

• Never show «Sep 20, 2026» to an Iranian user, even as a secondary line, unless the product is bilingual by design.

6. Using Intl correctly

Intl.DateTimeFormat with the Persian calendar is fine for labels:

1new Intl.DateTimeFormat("fa-IR-u-ca-persian", {2  dateStyle: "long",3  timeZone: "Asia/Tehran",4}).format(date); // «۲۹ شهریور ۱۴۰۵»56// Latin digits when you need them (inputs, logs):7new Intl.DateTimeFormat("fa-IR-u-ca-persian-nu-latn", { dateStyle: "short" }).format(date);

Limits: Intl formats but does not give you year/month/day integers for arithmetic, month grids or validation. For a date picker, ranges, "add one month", leap checks and age, use a converter (toJalali / toGregorian).

7. Date pickers and ranges

• Grid starts on Saturday; header shows «مهر ۱۴۰۵»; navigation arrows flip in RTL (previous month points right, next points left).

• Today, selected and disabled states are visible without color alone.

• Range picker: start and end inclusive, «از تاریخ / تا تاریخ» labels, presets like «۷ روز گذشته»، «این ماه»، «ماه گذشته» computed in Jalali.

• Typing is allowed with Persian or Latin digits and / or - separators; normalize before parsing.

• Min/max and disabled days (Fridays, holidays) are data, not hard-coded.

8. Reports, fiscal periods, age

• Monthly reports group by Jalali month, not Gregorian; quarterly = بهار، تابستان، پاییز، زمستان.

• Fiscal year for most Iranian companies is the Jalali year (1 فروردین to 29/30 اسفند). Ask before assuming otherwise.

• Age and durations: compute from the Gregorian instants, then say it in Persian: «۲۴ سال»، «۳ ماه و ۱۰ روز».

• «سال ۱۴۰۵» in prose, «۱۴۰۵» in tables; never «۰۵».

9. Holidays

• Fixed Jalali holidays exist (Nowruz 1–4 فروردین, 12 and 13 فروردین, 14 and 15 خرداد, 22 بهمن, 29 اسفند), but most public holidays are religious and follow the lunar calendar, so they move ~11 days earlier every year.

• Never hard-code a full holiday list from memory. Load it from an official calendar source the user provides or an API, keyed by Gregorian date, and cache per year.

• Mark holidays in the picker as data (disabled + a tooltip with the name).

10. Checklist

1. Storage Gregorian/UTC; display Jalali via a converter.

2. Week starts Saturday; Friday is the weekend.

3. Asia/Tehran, +03:30, no DST.

4. Persian digits and month names in every visible date.

5. Formats from section 5; no English month names.

6. Leap years from the algorithm, not % 4.

7. Holidays from data, not memory.