Skip to main content
toPersianChars replaces Arabic letterforms that look identical to Persian with the Persian code points, plus normalizes Arabic diacritics. Content inside {{...}} template segments is preserved verbatim.

​
Function

toPersianChars(str: string): string

import { toPersianChars } from "@persian-tools/persian-tools";

toPersianChars("علي"); // "علی"
toPersianChars("كتاب"); // "کتاب"
toPersianChars("عبدالله بن عبدالعزیز"); // "عبدالله بن عبدالعزیز" (no change — already Persian)

toPersianChars(""); // ""
toPersianChars(null as any); // ""
toPersianChars(undefined as any); // ""

​
What it normalizes

InputOutputCodepoint shift
يیU+064A → U+06CC
ىیU+0649 → U+06CC
كکU+0643 → U+06A9
Plus diacritics (ً ٌ ٍ َ ُ ِ ّ ْ) and Arabic punctuation (٫, ٬) — see src/modules/toPersianChars/index.ts for the full table.

​
What it does NOT do

  • No Latin → Persian. It does not convert y → ی, k → ک, or % → ٪.
  • No digit conversion. It does not touch ٠١٢ (Arabic-Indic) or 123 (Latin). Use the Digits module for that.
  • No whitespace / ZWNJ normalization. Use the Half-Space module for ZWNJ insertion.
For a full normalization pipeline: 
import { toPersianChars, autoConvertDigitsToEN, autoArabicToPersian } from "@persian-tools/persian-tools";

const normalize = (s: string) => toPersianChars(autoArabicToPersian(autoConvertDigitsToEN(s))).trim();

​
Template preservation

Anything between {{ and }} is preserved verbatim: 
toPersianChars("كشتى ىيكى {{ARABIC|كلمه}}");
// "کشتی یکی {{ARABIC|كلمه}}"
// Notice: standalone words got normalized; the `كلمه` inside {{ }} kept its Arabic ك
The implementation extracts {{...}} segments into placeholders, transforms the rest, then restores the segments.

​
Pitfalls

  • Latin and digits are untouched — older docs claim Latin → Persian conversion. They are wrong.
  • Running on text with intentional Arabic content will silently change it. Wrap Arabic sections in {{...}} or skip the call.
  • For very large documents, each replacement rule runs O(n). Consider per-field application rather than whole-document.

​
Source

src/modules/toPersianChars/index.ts · Tests: test/toPersianChars.spec.ts