Description
Themefour Shamsi Kit converts the dates WordPress displays to the Jalali (Shamsi) calendar. Post, page and archive dates, the dashboard post lists, the publish panel and comments are all shown in the Jalali calendar, while the dates WordPress stores and uses internally stay exactly as they are.
Conversion accuracy
Dates are converted with an exact, break-table based algorithm from the same family as the reference implementations of the Jalali calendar. Leap years, including years in which Esfand has 30 days, are calculated correctly. The conversion does not rely on the approximate 33-year cycle.
Machine-readable dates stay Gregorian
This is an important distinction that many date plugins miss. Formats such as Y-m-d, ISO 8601 timestamps and RFC dates are not meant for people to read; they are data that browsers, feed readers, search engines and other software parse.
Converting these machine-readable dates can break <time datetime=""> attributes, schema.org structured data, RSS feeds and sitemaps. Themefour Shamsi Kit recognises machine-readable formats, leaves them in Gregorian unchanged, and converts only the formats meant to be shown to people.
Correct Persian word order
When a theme or another plugin uses an English date format such as F j, Y, Themefour Shamsi Kit puts the day before the month, so the date reads “5 Mordad 1405” in Persian rather than “Mordad 5, 1405”.
This behaviour applies consistently to date_i18n(), wp_date(), get_the_date(), get_the_modified_date() and comment dates, so a single point in time is never shown in different formats on the same page.
Features
- Jalali dates on the front end, in the WordPress dashboard and in comments, each configurable on its own.
- Optional Persian digits.
- Correct Persian word order for date formats written in English order.
- An optional custom date format that applies only to converted dates and leaves the site’s own date format untouched.
- Today’s Jalali date in the admin toolbar, optionally with the Gregorian date beneath it, so both calendars are always at hand.
- The Vazirmatn font for the WordPress dashboard, served from the site’s own server with no request to any external font service.
- A Jalali date picker in the block editor (Gutenberg): the calendar that opens from the publish date is Jalali.
- Jalali date fields for the publish date in the classic editor and in Quick Edit.
- The WooCommerce order date in the order editor as a Jalali year, month and day.
- Jalali months in the “All dates” filter above the WooCommerce orders list, the posts and products lists and the Media Library (grid view, list view and every media window), each filtering exactly that Jalali month.
- A Jalali calendar for product and variation sale start and end dates, and for WooCommerce coupon expiry dates.
- In every one of these pickers, WordPress and WooCommerce store the same correct Gregorian date; only the way the date is entered becomes Jalali.
- Shortcodes for Jalali dates anywhere on the site: [shamsi_today], [shamsi_date], [shamsi_post_date] and [shamsi_post_modified], with a “Documentation” tab and ready-to-copy examples. Today’s date stays correct behind a page cache.
- Jalali dates in post permalinks (such as /1405/08/05/post-name/), with permanent redirects from the previous Gregorian links to the new address. Off by default.
- Replacement of Arabic Yeh, Kaf and Arabic digits with their Persian equivalents on save, and a search that finds results whichever keyboard layout is used. Off by default.
- Disabling the Gutenberg editor to return posts and pages to the classic WordPress editor.
- Disabling the block-based widgets screen to return to the classic widgets interface.
Pro version features
The Pro version offers broader Jalali support for WordPress, WooCommerce, form builders, third-party plugins and calendar building tools.
- More than 15 add-ons for compatibility with popular WordPress plugins
- A shortcode builder for clocks and time display
- A dedicated calendar builder with ready-made designs
- More features for WordPress and WooCommerce
- Compatibility with the Easy Digital Downloads (EDD) store builder
- Dozens more capabilities and features
For more information, visit themefour.com.
Third-party resources
The Vazirmatn font is distributed with this plugin and is loaded only when its option is enabled.
- Font name: Vazirmatn, by Saber Rastikerdar
- License: SIL Open Font License 1.1, license URL: https://scripts.sil.org/OFL
- Source: https://github.com/rastikerdar/vazirmatn
- Full license text:
admin/fonts/Vazirmatn-OFL.txt
The font file is served from the site’s own server; no connection is made to external services such as Google Fonts.
Installation
- Upload the plugin to the
/wp-content/plugins/directory, or install it from Plugins > Add New. - Activate the plugin.
- Open “Themefour Shamsi Kit” from the WordPress admin menu. The plugin works out of the box with sensible defaults and needs no configuration.
FAQ
Does this plugin change the dates stored in the database?
No. Post dates stay exactly as WordPress stores them; only the displayed date changes. If you deactivate the plugin, dates are shown in Gregorian again, with nothing to convert back or restore in the database.
Will this plugin break my sitemap, RSS feed or structured data?
No. Formats meant for machines are recognised and kept in Gregorian. This is a deliberate design decision, not an accident or a side effect.
My theme shows the month before the day. Can I fix that?
Yes. Turn on the “Persian date order” option. When a date format is written in English order, the plugin puts the day before the month.
If you enter a custom date format, the plugin uses exactly the format you entered.
Can I control the date format?
Yes. If you leave the custom date format empty, the plugin uses the format set under Settings > General. You can also enter a format such as j F Y to apply your own format to converted dates only.
Does it work with WooCommerce?
Dates that WooCommerce displays through the standard WordPress date functions are converted to the Jalali calendar.
Since version 1.3.0, WooCommerce also has Jalali date pickers: the order date in the order editor, product and variation sale dates, and coupon expiry dates are picked on a Jalali calendar, and WooCommerce stores the same correct Gregorian date. Each picker can be switched off separately on the “Display” tab.
Since version 1.5.0, the “All dates” filter above the orders list shows Jalali months.
Check Pro version at themefour.com.
Screenshots
Changelog
1.5.2
- New: the date filter of the Media Library now shows Jalali months, in both the grid and the list view, and so does the date filter inside every media window (Add Media, featured image, image blocks). Choosing a month shows exactly the files uploaded in that Jalali month. It is part of Core Dates and follows the “Convert dates in the dashboard” option.
- Fixed (root cause): 1.5.0 replaced only the dropdown that list tables print through months_dropdown(), and only on the posts screen (edit.php). The Media Library is different on both counts. Its grid view and the media window are JavaScript apps that receive a ready-made list of Gregorian months from wp_enqueue_media() and send the chosen month to admin-ajax as a Gregorian year and month, so no list table hook ever runs. Its list view does use months_dropdown(), but on upload.php, which the 1.5.0 screen check rejected. Both paths are now handled: the month list is replaced, and the request is turned into the exact Gregorian range of the chosen Jalali month.
- Performance: on the Media Library, WordPress’s own Gregorian month scan is now skipped instead of being run and then discarded, so the page costs one query, as before.
- Compatibility: a site that supplies its own month list through media_library_months_with_files or pre_months_dropdown_query, usually to avoid the scan on a very large library, keeps that choice. Each of its Gregorian months is shown as the two Jalali months it overlaps, rather than running the scan that site opted out of.
1.5.1
- Changed: the readme is now in English, as WordPress.org requires. The Persian description is provided through translate.wordpress.org.
- Changed: “Tested up to” now names the major version only (7.1), as the readme standard requires.
- Changed: on WordPress 6.8 and later, WordPress loads the bundled Persian translation itself, so the plugin no longer calls load_plugin_textdomain() there. It still does on WordPress 5.8 to 6.7, which cannot find a bundled translation on their own.
- Hardening: the WooCommerce orders table name in the date filter query is now passed through esc_sql().
1.5.0
- New: the “All dates” dropdown above the WooCommerce orders list (HPOS) and above the posts, pages, products and every other post type list in the dashboard now shows Jalali months (for example “Mehr 1405”) and filters exactly the orders or posts of that Jalali month. Both WordPress and WooCommerce build this dropdown directly from Gregorian month names, outside the date functions, and each option’s value is a Gregorian month. Relabelling the options was not enough: a Jalali month starts around the 22nd of a Gregorian one and matches no Gregorian month, so the whole dropdown is replaced and the request is turned into the exact Gregorian range of that Jalali month. Existing Gregorian links, including the “orders on this day” links in WooCommerce reports, keep working and show their range in Jalali. The feature follows the “Convert dates in the dashboard” option; on WooCommerce older than 8.6, WooCommerce’s own Gregorian dropdown is left untouched.
1.4.1
- Fix: comment dates in the dashboard comments list and file dates in the media list were shown in Gregorian (for example “2026/10/28” next to a time in Persian digits). WordPress builds these columns with the numeric format “Y/m/d”, and the plugin deliberately treated every numeric format as a machine format and kept it Gregorian so ISO dates and date pickers would not break. Now this table format alone is converted, only inside the comment and post date filters and only in the dashboard.
1.4.0
- New: Jalali date shortcodes [shamsi_today], [shamsi_date], [shamsi_post_date] and [shamsi_post_modified], with a “Documentation” tab showing each shortcode’s live output on the site and a copy button. [shamsi_today] stays correct behind a page cache: the date is rebuilt in the visitor’s browser from the site’s timezone, so a page cached yesterday does not show yesterday’s date. [shamsi_date] also accepts a Jalali date and prints nothing for an invalid Jalali date rather than a wrong one. The post date shortcodes also work outside the loop with the id attribute.
- New: Jalali dates in post permalinks, off by default. Digits deliberately stay Latin, because Persian digits are percent-encoded in URLs. Previous Gregorian links are moved to the Jalali address with a 301 redirect, Jalali day, month and year archives work, and turning the option off sends Jalali links back to the Gregorian address instead of breaking them. A day such as 31 Ordibehesht, which has no equivalent in the second Gregorian month, opens correctly.
- New: Arabic letter correction, off by default. Arabic Yeh, Alef Maksura, Kaf and Arabic digits are converted to Persian on save in titles, content, excerpts, comments and category names, and search also finds older posts written with Arabic letters. Links, HTML tags, block data and shortcodes are left untouched, existing post addresses do not change, and Teh Marbuta is deliberately not converted.
1.3.2
- Compatibility with WordPress 7.1.4.
1.3.1
- Fix: the classic editor script wrote the Gregorian day without a leading zero (“5”), while WordPress keeps the original value as two digits (“05”) and compares the two as strings. For days 1 to 9 of a Gregorian month, merely opening the date box made WordPress treat the date as changed, pin an “immediately” draft to that moment and make the “Cancel” button ineffective. All values are now written with two digits.
- Fix: entering day 31 in a 30-day month in the classic editor silently moved to the first day of the next month. The day is now limited to the last day of the month.
1.3.0
- New: a Jalali date picker in the block editor (Gutenberg). The calendar that opens from the publish date is Jalali and the date is set directly in the editor, so WordPress stores the same correct Gregorian date. The publish date button in the sidebar is also shown in Jalali.
- New: Jalali date fields for the publish date in the classic editor and in Quick Edit.
- New: Jalali date pickers in WooCommerce for the order date in the order editor (both the classic screen and HPOS), product and variation sale start and end dates, and coupon expiry dates. Each picker can be switched off separately on the “Display” tab.
- Fix: every direct wp_date() call showed the time in UTC, three and a half hours behind on a site in the Tehran timezone, and the previous day’s date from 20:30 to midnight. wp_date() passes the raw UTC time to its filter and the plugin converted it without applying the site’s timezone. Post dates looked fine because their own filters rewrite the output later.
- Fix: a format containing an escaped c, r or U (such as “j F \r”) was detected as a machine format and printed an English Gregorian date. Escaped characters are now set aside before this check.
- Fix: saving the settings on a host without the mbstring extension stopped with a fatal error, because mb_substr() was called without checking that it exists. A method that does not need mbstring is now used.
- Fix: deleting the plugin also removed the settings shared with the Pro version, so someone who upgraded to Pro and then deleted the free version lost their settings. The settings are now kept when the Pro version is installed. On multisite networks, cleanup is no longer limited to the first 100 sites.
- Compatibility with WordPress 7.1.
1.2.1
- Fix: a Latin “S” appeared inside Jalali dates. The formatting engine printed any character it did not recognise as is, and the S token (the English ordinal suffix such as “st” and “th”) was among them. Avada’s default meta format is “F jS, Y”, which is why it showed on that theme. S now correctly produces no output in Persian and is removed from the format before the day and month are reordered, so the leftover comma is removed too.
- Fix: the tokens z, W, o, u, v, B and the timezone tokens e, I, O, P, p, T and Z were also printed as is. Calendar tokens are now calculated on the Jalali calendar and timezone tokens are rendered with the site’s real timezone.
1.2.0
- New: an option to disable the Gutenberg editor and return to the classic WordPress editor.
1.1.0
- New: an option to use the Vazirmatn font in the WordPress dashboard.
1.0.1
- Removed every trace of the separate commercial plugin from this package.
1.0.0
- Initial release.






