normalizeArabicYeh

⚠️ Version Recommendation: Always install and use the latest version of rtl-text-tools (npm install rtl-text-tools@latest). While this specific feature was introduced in an earlier version, the latest release includes crucial bug fixes, better edge-case handling, and improved legacy browser compatibility. Avoid pinning your project to an old version just to use this function.

Normalizes the Arabic letter Alef Maqsura (ى) to the standard Yeh (ي). In many Arabic dialects (such as Egyptian) and common typing habits, Alef Maqsura is used interchangeably with Yeh at the end of words. Normalizing these characters ensures consistent search results, accurate text comparison, and standardized data storage.

📝 Syntax

normalizeArabicYeh(text: string): string

Parameters

Name	Type	Description
text	string	The Arabic text containing Alef Maqsura to normalize.

Returns

• string : Returns the text with all instances of Alef Maqsura (ى) converted to standard Yeh (ي). Returns the original string unchanged if it is empty, null, or contains no Alef Maqsura.

💡 Examples

Basic Usage

import { normalizeArabicYeh } from 'rtl-text-tools';

normalizeArabicYeh("على");      // "علي" (Alef Maqsura -> standard Yeh)
normalizeArabicYeh("مصرى");     // "مصري" (Common Egyptian spelling -> standard)
normalizeArabicYeh("هذى");      // "هذا" -> wait, "هذي" (End of word Yeh)
normalizeArabicYeh("يوسف");     // "يوسف" (Already standard Yeh -> unchanged)

Search and Text Comparison

When building a search feature or filtering data, users might type words with different Yeh variations depending on their regional dialect or keyboard layout. Normalizing both the database text and the user's query ensures accurate matches:

import { normalizeArabicYeh } from 'rtl-text-tools';

const databaseText = "علي";     // Stored with standard Yeh
const userQuery = "على";        // User typed with Alef Maqsura

const normalizedDB = normalizeArabicYeh(databaseText);   // "علي"
const normalizedQuery = normalizeArabicYeh(userQuery);   // "علي"

if (normalizedDB === normalizedQuery) {
  console.log("Match found!"); // This will now successfully match
}

🌍 Character Mapping

This function specifically targets the following Unicode character and replaces it with the standard Yeh (\u064A):

Original Character	Name	Unicode	Replaced With
ى	Alef Maqsura	\u0649	ي (\u064A)

⚙️ Technical Details & Compatibility

• Direct Replacement: The function uses a standard String.prototype.replace() method with a global regular expression (/\u0649/g) to ensure every instance of the targeted character is replaced.
• IE11 Compatibility: It avoids modern string methods and the ES6 u regex flag, ensuring full compatibility with legacy browsers like IE11.
• Safe Execution: If the input is falsy (e.g., null, undefined, or ""), it immediately returns the input without throwing an error.

📜 Version History

• v1.2.0: Added normalizeArabicYeh() as part of the Arabic language enhancements for deep text normalization.