If you run a WordPress site with Arabic content, you have probably heard this complaint: "I searched for a product I know exists, and got zero results." The content is there. The word is right. And search still fails.
I ran into this on client stores in Egypt and the Gulf often enough that I finally sat down and fixed it properly. This post explains why it happens and how the fix works, so you can solve it too, or use the plugin I built.
The problem: one letter, many shapes
Arabic text has variations that are invisible to a reader but completely different to a database:
- Alef variants: ا, أ, إ, آ, and ٱ are five different Unicode code points. A reader sees them all as "alef". MySQL does not.
- Diacritics (tashkeel): marks like ً ُ ِ ّ are optional in modern writing. Religious or formal content often includes them, everyday typing almost never does.
- Tatweel (ـ): a stretching character used for justification. Pure decoration, but it sits inside the word as a real character.
- Yeh vs alef maqsura: ي and ى are mixed constantly, even by native speakers.
- Teh marbuta vs heh: ة and ه sound identical at the end of a word.
Real examples. A customer types القران (plain alefs), but your post contains القرآن (alef with maddah, U+0622). No match. Someone searches محمد, your content has محمّد with a shadda. No match. An Egyptian shopper types قهوة and your catalog says قهوه. No match.
Why the default search can't cope
WordPress search is simple substring matching. When you search, WP_Query turns your term into SQL along these lines:
... AND (post_title LIKE '%القران%' OR post_content LIKE '%القران%')
MySQL's utf8mb4_unicode_ci collation is accent-insensitive for Latin text (café matches cafe), but it does not treat Arabic alef variants as equal, does not ignore diacritics, and does not ignore tatweel. LIKE compares the string as stored, byte sequence against byte sequence. One extra shadda and the substring is simply not there.
So this is not a bug in your site. It is a mismatch between how Arabic is written and how LIKE works.
The fix: normalize both sides
The approach that works is straightforward: reduce Arabic text to a canonical form before comparing, and do it on both sides, the search query and the content being searched.
Normalization means:
- Strip diacritics (Unicode range U+064B to U+065F and friends).
- Remove tatweel (U+0640).
- Map all alef variants (أ إ آ ٱ) to plain alef (ا).
- Optionally map ى to ي, and ة to ه.
After normalization, القرآن and القران become the same string. محمّد and محمد become the same string. Search starts behaving the way users expect.
In PHP the core of it is a few regex replaces:
function ar_normalize( string $text ): string {
// Strip diacritics and tatweel.
$text = preg_replace( '/[\x{064B}-\x{065F}\x{0670}\x{0640}]/u', '', $text );
// Unify alef variants.
$text = preg_replace( '/[\x{0623}\x{0625}\x{0622}\x{0671}]/u', "\x{0627}", $text );
// Alef maqsura to yeh.
$text = str_replace( "\x{0649}", "\x{064A}", $text );
return $text;
}
The harder part is wiring it into WordPress so every search uses it. Hooking posts_search lets you replace the generated LIKE clause with one that compares normalized values, for example against a normalized copy of the title and content kept in a separate index table. That keeps queries fast and leaves the original content untouched for display.
I packaged this as a plugin
I turned the fix into a plugin called Arabic Search Fix: it normalizes search queries and indexes a normalized copy of your content, so Arabic search just works, with no changes to your theme. It is tested on a live store running WordPress 7.1.5 and is on its way to the WordPress.org plugin directory.
If Arabic (or Persian, or Urdu, same family of problems) search matters to your site, I would genuinely love to hear your edge cases. The comments are open.
Mohamed Samir is a WordPress & WooCommerce developer based in Cairo, Egypt. He builds stores, plugins, and unglamorous fixes for real problems across Egypt and the Gulf.
Top comments (0)