<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Mohamed Samir</title>
    <description>The latest articles on DEV Community by Mohamed Samir (@mosamirdev).</description>
    <link>https://dev.to/mosamirdev</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4257241%2Ffb34eb08-ba50-4a18-b197-badf75efd235.png</url>
      <title>DEV Community: Mohamed Samir</title>
      <link>https://dev.to/mosamirdev</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/mosamirdev"/>
    <language>en</language>
    <item>
      <title>Why Arabic search breaks in WordPress (and how I fixed it)</title>
      <dc:creator>Mohamed Samir</dc:creator>
      <pubDate>Sat, 21 Nov 2026 11:34:23 +0000</pubDate>
      <link>https://dev.to/mosamirdev/why-arabic-search-breaks-in-wordpress-and-how-i-fixed-it-49he</link>
      <guid>https://dev.to/mosamirdev/why-arabic-search-breaks-in-wordpress-and-how-i-fixed-it-49he</guid>
      <description>&lt;p&gt;If you run a WordPress site with Arabic content, you have probably heard this complaint: "I searched for a product I &lt;em&gt;know&lt;/em&gt; exists, and got zero results." The content is there. The word is right. And search still fails.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  The problem: one letter, many shapes
&lt;/h2&gt;

&lt;p&gt;Arabic text has variations that are invisible to a reader but completely different to a database:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Alef variants&lt;/strong&gt;: ا, أ, إ, آ, and ٱ are five different Unicode code points. A reader sees them all as "alef". MySQL does not.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Diacritics (tashkeel)&lt;/strong&gt;: marks like ً ُ ِ ّ are optional in modern writing. Religious or formal content often includes them, everyday typing almost never does.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Tatweel (ـ)&lt;/strong&gt;: a stretching character used for justification. Pure decoration, but it sits inside the word as a real character.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Yeh vs alef maqsura&lt;/strong&gt;: ي and ى are mixed constantly, even by native speakers.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Teh marbuta vs heh&lt;/strong&gt;: ة and ه sound identical at the end of a word.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Real examples. A customer types &lt;strong&gt;القران&lt;/strong&gt; (plain alefs), but your post contains &lt;strong&gt;القرآن&lt;/strong&gt; (alef with maddah, U+0622). No match. Someone searches &lt;strong&gt;محمد&lt;/strong&gt;, your content has &lt;strong&gt;محمّد&lt;/strong&gt; with a shadda. No match. An Egyptian shopper types &lt;strong&gt;قهوة&lt;/strong&gt; and your catalog says &lt;strong&gt;قهوه&lt;/strong&gt;. No match.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why the default search can't cope
&lt;/h2&gt;

&lt;p&gt;WordPress search is simple substring matching. When you search, &lt;code&gt;WP_Query&lt;/code&gt; turns your term into SQL along these lines:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt; &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;post_title&lt;/span&gt; &lt;span class="k"&gt;LIKE&lt;/span&gt; &lt;span class="s1"&gt;'%القران%'&lt;/span&gt; &lt;span class="k"&gt;OR&lt;/span&gt; &lt;span class="n"&gt;post_content&lt;/span&gt; &lt;span class="k"&gt;LIKE&lt;/span&gt; &lt;span class="s1"&gt;'%القران%'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;MySQL's &lt;code&gt;utf8mb4_unicode_ci&lt;/code&gt; collation is accent-insensitive for Latin text (&lt;code&gt;café&lt;/code&gt; matches &lt;code&gt;cafe&lt;/code&gt;), but it does &lt;strong&gt;not&lt;/strong&gt; treat Arabic alef variants as equal, does not ignore diacritics, and does not ignore tatweel. &lt;code&gt;LIKE&lt;/code&gt; compares the string as stored, byte sequence against byte sequence. One extra shadda and the substring is simply not there.&lt;/p&gt;

&lt;p&gt;So this is not a bug in your site. It is a mismatch between how Arabic is written and how &lt;code&gt;LIKE&lt;/code&gt; works.&lt;/p&gt;

&lt;h2&gt;
  
  
  The fix: normalize both sides
&lt;/h2&gt;

&lt;p&gt;The approach that works is straightforward: reduce Arabic text to a canonical form &lt;strong&gt;before&lt;/strong&gt; comparing, and do it on both sides, the search query and the content being searched.&lt;/p&gt;

&lt;p&gt;Normalization means:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Strip diacritics (Unicode range U+064B to U+065F and friends).&lt;/li&gt;
&lt;li&gt;Remove tatweel (U+0640).&lt;/li&gt;
&lt;li&gt;Map all alef variants (أ إ آ ٱ) to plain alef (ا).&lt;/li&gt;
&lt;li&gt;Optionally map ى to ي, and ة to ه.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;After normalization, &lt;strong&gt;القرآن&lt;/strong&gt; and &lt;strong&gt;القران&lt;/strong&gt; become the same string. &lt;strong&gt;محمّد&lt;/strong&gt; and &lt;strong&gt;محمد&lt;/strong&gt; become the same string. Search starts behaving the way users expect.&lt;/p&gt;

&lt;p&gt;In PHP the core of it is a few regex replaces:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight php"&gt;&lt;code&gt;&lt;span class="k"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;ar_normalize&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="nv"&gt;$text&lt;/span&gt; &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// Strip diacritics and tatweel.&lt;/span&gt;
    &lt;span class="nv"&gt;$text&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;preg_replace&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt; &lt;span class="s1"&gt;'/[\x{064B}-\x{065F}\x{0670}\x{0640}]/u'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;''&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$text&lt;/span&gt; &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="c1"&gt;// Unify alef variants.&lt;/span&gt;
    &lt;span class="nv"&gt;$text&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;preg_replace&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt; &lt;span class="s1"&gt;'/[\x{0623}\x{0625}\x{0622}\x{0671}]/u'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"\x{0627}"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$text&lt;/span&gt; &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="c1"&gt;// Alef maqsura to yeh.&lt;/span&gt;
    &lt;span class="nv"&gt;$text&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;str_replace&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt; &lt;span class="s2"&gt;"\x{0649}"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"\x{064A}"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$text&lt;/span&gt; &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="nv"&gt;$text&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The harder part is wiring it into WordPress so every search uses it. Hooking &lt;code&gt;posts_search&lt;/code&gt; lets you replace the generated &lt;code&gt;LIKE&lt;/code&gt; 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.&lt;/p&gt;

&lt;h2&gt;
  
  
  I packaged this as a plugin
&lt;/h2&gt;

&lt;p&gt;I turned the fix into a plugin called &lt;strong&gt;Arabic Search Fix&lt;/strong&gt;: 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.&lt;/p&gt;

&lt;p&gt;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.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Mohamed Samir is a WordPress &amp;amp; WooCommerce developer based in Cairo, Egypt. He builds stores, plugins, and unglamorous fixes for real problems across Egypt and the Gulf.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>wordpress</category>
      <category>php</category>
      <category>mysql</category>
      <category>arabic</category>
    </item>
  </channel>
</rss>
