feat(i18n): add Persian (fa) locale with Jalali-aware date formatting

i18n.json

@@ -16,6 +16,7 @@
       "es-419",
       "eu",
       "et",
+      "fa",
       "fi",
       "fr",
       "he",

packages/i18n/locales/fa/common.json

@@ -0,0 +1,32 @@
+{
+  "today": "امروز",
+  "view_previous_month": "مشاهده ماه قبل",
+  "view_next_month": "مشاهده ماه بعد",
+  "select": "انتخاب کنید...",
+  "save": "ذخیره",
+  "cancel": "لغو",
+  "back": "بازگشت",
+  "next": "بعدی",
+  "date": "تاریخ",
+  "time": "زمان",
+  "timezone": "منطقه زمانی",
+  "confirm": "تأیید",
+  "loading": "در حال بارگذاری...",
+  "duration": "مدت زمان",
+  "no_available_slots": "زمان خالی موجود نیست",
+  "reschedule": "زمان‌بندی مجدد",
+  "required": "الزامی",
+  "submit": "ارسال",
+  "continue": "ادامه",
+  "close": "بستن",
+  "search": "جستجو",
+  "settings": "تنظیمات",
+  "general": "عمومی",
+  "language": "زبان",
+  "availability": "در دسترس بودن",
+  "event_type": "نوع رویداد",
+  "bookings": "رزروها",
+  "upcoming": "آینده",
+  "past": "گذشته",
+  "minute_timeUnit": "دقیقه"
+}

packages/lib/dateTimeFormatter.test.ts

@@ -2,7 +2,13 @@ import { describe, expect, it } from "vitest";
 
 import "@calcom/dayjs/locales";
 
-import { formatDateTime, formatDateTimeRange, formatWeekday, getWeekdayNames } from "./dateTimeFormatter";
+import {
+  formatDateTime,
+  formatDateTimeRange,
+  formatWeekday,
+  getWeekdayNames,
+  isPersianCalendarLocale,
+} from "./dateTimeFormatter";
 
 describe("dateTimeFormatter", () => {
   describe("formatDateTime", () => {
@@ -278,6 +284,45 @@ describe("dateTimeFormatter", () => {
     });
   });
 
+  describe("Persian (Shamsi) calendar", () => {
+    // 2025-12-01 (Gregorian) corresponds to 10 Azar 1404 in the Jalali calendar.
+    const date = new Date("2025-12-01T10:30:00Z");
+
+    it("detects Persian locales", () => {
+      expect(isPersianCalendarLocale("fa")).toBe(true);
+      expect(isPersianCalendarLocale("fa-IR")).toBe(true);
+      expect(isPersianCalendarLocale("en-US-u-ca-persian")).toBe(true);
+      expect(isPersianCalendarLocale("en")).toBe(false);
+      expect(isPersianCalendarLocale("fawn")).toBe(false);
+    });
+
+    it("formats dates using the Jalali calendar, not Gregorian", () => {
+      const result = formatDateTime(date, { locale: "fa", timeZone: "UTC", dateStyle: "long" });
+
+      expect(result).toContain("آذر"); // Azar (Jalali month)
+      expect(result).toContain("۱۴۰۴"); // Jalali year 1404
+      expect(result).not.toContain("2025"); // never the Gregorian year
+    });
+
+    it("formats the Jalali month name for month-only output", () => {
+      const result = formatDateTime(date, { locale: "fa", timeZone: "UTC", month: "long" });
+
+      expect(result).toBe("آذر");
+    });
+
+    it("returns Persian weekday names", () => {
+      expect(formatWeekday("fa", 6, "long")).toBe("شنبه"); // Saturday
+    });
+
+    it("orders weekday names starting on Saturday", () => {
+      const result = getWeekdayNames("fa", 6, "long");
+
+      expect(result).toHaveLength(7);
+      expect(result[0]).toBe("شنبه"); // Saturday first
+      expect(result[6]).toBe("جمعه"); // Friday last
+    });
+  });
+
   describe("timezone handling", () => {
     it("formats in UTC correctly for both Intl and dayjs paths", () => {
       const date = new Date("2025-12-01T10:30:00Z");

packages/lib/dateTimeFormatter.ts

@@ -27,6 +27,24 @@ const localeSupport = new Map<string, boolean>();
 const formatterCache = new Map<string, Intl.DateTimeFormat>();
 const weekdayCache = new Map<string, string[]>();
 
+/**
+ * Persian (fa) uses the Jalali/Shamsi calendar, which the dayjs fallback path cannot
+ * render. `Intl` defaults `fa` to the Persian calendar, so we always route Persian
+ * locales through `Intl` to avoid silently emitting Gregorian dates.
+ */
+export function isPersianCalendarLocale(locale: string): boolean {
+  const normalized = locale.toLowerCase();
+  return /^fa(-|$)/.test(normalized) || normalized.includes("-ca-persian");
+}
+
+/** Makes the Persian calendar explicit so behavior is stable across ICU versions. */
+function resolveFormatterLocale(locale: string): string {
+  if (isPersianCalendarLocale(locale) && !locale.toLowerCase().includes("-ca-")) {
+    return `${locale}-u-ca-persian`;
+  }
+  return locale;
+}
+
 function isSupported(locale: string): boolean {
   let supported = localeSupport.get(locale);
   if (supported === undefined) {
@@ -36,6 +54,11 @@ function isSupported(locale: string): boolean {
   return supported;
 }
 
+/** Persian locales are forced through Intl (Jalali-aware) instead of the Gregorian dayjs fallback. */
+function shouldUseIntl(locale: string): boolean {
+  return isPersianCalendarLocale(locale) || isSupported(locale);
+}
+
 function getFormatter(locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
   const key = `${locale}|${JSON.stringify(options)}`;
   let formatter = formatterCache.get(key);
@@ -87,22 +110,25 @@ function getDateForWeekday(day: number): Date {
 }
 
 export function formatDateTime(date: Date, options: DateTimeFormatOptions): string {
-  if (isSupported(options.locale)) {
-    return getFormatter(options.locale, buildIntlOptions(options)).format(date);
+  if (shouldUseIntl(options.locale)) {
+    return getFormatter(resolveFormatterLocale(options.locale), buildIntlOptions(options)).format(date);
   }
   return formatWithDayjs(date, options);
 }
 
 export function formatDateTimeRange(startDate: Date, endDate: Date, options: DateTimeFormatOptions): string {
-  if (isSupported(options.locale)) {
-    return getFormatter(options.locale, buildIntlOptions(options, false)).formatRange(startDate, endDate);
+  if (shouldUseIntl(options.locale)) {
+    return getFormatter(resolveFormatterLocale(options.locale), buildIntlOptions(options, false)).formatRange(
+      startDate,
+      endDate
+    );
   }
   return `${formatWithDayjs(startDate, options)} — ${formatWithDayjs(endDate, options)}`;
 }
 
 export function formatWeekday(locale: string, day: number, format: "short" | "long"): string {
-  if (isSupported(locale)) {
-    return getFormatter(locale, { weekday: format }).format(getDateForWeekday(day));
+  if (shouldUseIntl(locale)) {
+    return getFormatter(resolveFormatterLocale(locale), { weekday: format }).format(getDateForWeekday(day));
   }
   return dayjs().day(day).locale(locale).format(WEEKDAY_FORMATS[format]);
 }
@@ -116,8 +142,8 @@ export function getWeekdayNames(locale: string, weekStart = 0, format: "short" |
       weekdayCache.clear();
     }
 
-    if (isSupported(locale)) {
-      const formatter = getFormatter(locale, { weekday: format });
+    if (shouldUseIntl(locale)) {
+      const formatter = getFormatter(resolveFormatterLocale(locale), { weekday: format });
       names = Array.from({ length: 7 }, (_, i) => formatter.format(getDateForWeekday((i + weekStart) % 7)));
     } else {
       names = Array.from({ length: 7 }, (_, i) =>

packages/lib/weekday.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest";
 
 import "@calcom/dayjs/locales";
 
-import { nameOfDay, weekdayNames } from "./weekday";
+import { getWeekStartForLocale, nameOfDay, weekdayNames } from "./weekday";
 
 describe("Weekday tests", () => {
   describe("fn: weekdayNames", () => {
@@ -71,4 +71,18 @@ describe("Weekday tests", () => {
       expect(nameOfDay("nb", 1, "long")).toMatch(/mandag/i); // Monday in Norwegian
     });
   });
+
+  describe("fn: getWeekStartForLocale", () => {
+    it("defaults to Saturday (6) for Persian locales", () => {
+      expect(getWeekStartForLocale("fa")).toBe(6);
+      expect(getWeekStartForLocale("fa-IR")).toBe(6);
+      expect(getWeekStartForLocale(["fa-IR", "fa"])).toBe(6);
+    });
+
+    it("defaults to Sunday (0) for non-Persian locales", () => {
+      expect(getWeekStartForLocale("en")).toBe(0);
+      expect(getWeekStartForLocale("ar")).toBe(0);
+      expect(getWeekStartForLocale(undefined)).toBe(0);
+    });
+  });
 });

packages/lib/weekday.ts

@@ -1,7 +1,19 @@
-import { getWeekdayNames, formatWeekday } from "./dateTimeFormatter";
+import { formatWeekday, getWeekdayNames, isPersianCalendarLocale } from "./dateTimeFormatter";
 
 type WeekdayFormat = "short" | "long";
 
+const SATURDAY = 6;
+const SUNDAY = 0;
+
+/**
+ * Default first day of the week for a locale when the user has not set one explicitly.
+ * Persian (Shamsi) calendars start the week on Saturday; everything else defaults to Sunday.
+ */
+export function getWeekStartForLocale(locale: string | string[] | undefined): 0 | 6 {
+  const normalizedLocale = Array.isArray(locale) ? locale[0] : locale || "en";
+  return isPersianCalendarLocale(normalizedLocale) ? SATURDAY : SUNDAY;
+}
+
 export function weekdayNames(locale: string | string[], weekStart = 0, format: WeekdayFormat = "long") {
   const normalizedLocale = Array.isArray(locale) ? locale[0] : locale || "en";
   return getWeekdayNames(normalizedLocale, weekStart, format);