If you’re building a Persian-language marketplace with WordPress + WooCommerce + Dokan, one small technical detail can make a huge difference in usability and trust: the date system. The Jalali (Shamsi) calendar is the standard civil calendar in Iran and used widely across Persian-speaking communities. Out of the box, WordPress, WooCommerce, and Dokan use the Gregorian calendar. That means order dates, product publish dates, vendor dashboards, reporting, and customer-facing timestamps can look foreign or confusing.

A Jalali (Shamsi) Date Module for Dokan fills that gap: it converts and displays dates in the Persian calendar across the Dokan experience (admin, vendor dashboard, and storefront), while keeping the underlying timestamps compatible with WordPress and WooCommerce. In this article I’ll explain why this module matters, what features it should provide, how it integrates with Dokan, and practical tips for implementation and testing.

Why Jalali dates matter for a Dokan marketplace

1. User trust & comfort — Local customers expect dates in the format they use every day. Showing Gregorian dates in a Persian-language store can cause confusion about delivery dates, coupon expirations, or order history.


2. Legal & administrative alignment — Some contracts, receipts or local document workflows rely on Shamsi dates. Aligning your e-commerce UI with local practices reduces friction.


3. Vendor expectations — Local sellers are used to Jalali dates in invoices, shipping documents and communication. A marketplace that shows consistent local dates is easier to adopt.


4. Professionalism — Little details like localized date formats increase perceived quality and lower customer support tickets about “What date did I order?”

What a good Jalali Date Module should do

• Display conversion — Convert and display WordPress/WooCommerce/Dokan dates in Jalali format in all customer-facing places: product publish dates (if shown), order timestamps, estimated delivery dates, and seller store info.


• Vendor dashboard support — Show Jalali dates in vendor’s orders, reports, payout schedules, and notice logs.


• Admin area option — Optionally display Jalali dates in WordPress/WooCommerce admin screens for store managers who prefer Shamsi.


• Form inputs & datepickers — Replace or adapt datepickers used in coupon expiry, product scheduling, or Dokan settings to allow selecting Jalali dates (and convert to UTC/Gregorian under the hood).


• Localization & numerals — Support Persian names for months, weekdays and optional Persian numerals.


• Non-destructive — Keep underlying WP timestamps intact (UTC/Gregorian) for compatibility with plugins, reporting, backups and integrations. Only the display layer should change.


• Compatibility — Work alongside Dokan, WooCommerce, and popular date libraries and avoid breaking hooks/filters that other plugins rely on.


• Performance-conscious — Minimal overhead on page load, use conversion only where needed, and cache converted strings where appropriate.

How it integrates with Dokan — practical points

1. Use filters, not DB changes. Hook into date_i18n(), get_the_date(), wc_format_datetime() (WooCommerce), and Dokan-specific templates/filters. This keeps conversions at the presentation layer.


2. Vendor dashboard templates. Dokan’s vendor dashboard shows orders and reports. Either override Dokan templates in a child theme or use Dokan filters/actions to replace displayed dates.


3. Order meta & emails. WooCommerce email templates often include order dates and times. Ensure the module applies conversions on email rendering.


4. Shortcodes & widgets. Replace or filter date output in any shortcode/widget that shows dates.


5. Date inputs (UI). For datepickers, provide a Jalali-aware picker that emits a Gregorian date to the server. Always validate/convert server-side as well.

Example: converting order date display (concept)

// Hook into WooCommerce order date formatting
add_filter( 'woocommerce_order_formatted_date', 'myprefix_jalali_order_date', 10, 2 );

function myprefix_jalali_order_date( $date_string, $order ) {
    // $date_string is the formatted Gregorian string from WooCommerce
    // Convert to timestamp
    $timestamp = strtotime( $date_string );
    // Convert to Jalali using your library
    $jalali = jp_convert_gregorian_to_jalali( date('Y',$timestamp), date('m',$timestamp), date('d',$timestamp) );
    // Format the Jalali date string
    return sprintf('%s %s %s', $jalali['day'], $jalali['month_name'], $jalali['year']);
}

In practice use a tested Jalali library (PHP or JS) to handle leap years and correct month names.

Implementation tips & libraries

• PHP libraries: Use a stable Jalali conversion library. Avoid hand-written conversions.


• JS libraries: persian-date, persian-datepicker, or moment-jalaali are common.


• Caching: Cache repeated conversions per page.


• Settings page: Provide options to toggle Jalali display for admin, vendor, or customer.


• Testing: Test timezones, scheduled posts, and WooCommerce reporting.


• Fallbacks: If conversion fails, fall back to the Gregorian date instead of breaking UI.

UX considerations

• Show both dates? For legal or cross-border workflows, offer a “show both dates” setting.


• Timezones: Only the date portion should change; time should remain based on WP timezone.


• Search & filters: Convert Jalali filters to Gregorian ranges internally.


• Communication: Use Jalali dates in SMS/email delivery estimates to avoid disputes.

Troubleshooting common issues

• Dates off-by-one around midnight — Usually timezone mismatch; ensure you use the WP timezone.


• Emails showing wrong date — Hook into WooCommerce email date formatting directly.


• Plugin conflicts — Some localization plugins filter date_i18n; adjust filter priorities.


• Performance slowdown — Add caching if many dates are shown on one page.