Persian Tools

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

Input	Output	Codepoint 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

Introduction

Showcase

AI Agent Skills

Getting Started

Number Utilities

Validation

Text Processing

Banking

Geographic

Time Utilities

Vehicle

Persian Character Normalization

Function

What it normalizes

What it does NOT do

Template preservation

Pitfalls

Source

​Function

​What it normalizes

​What it does NOT do

​Template preservation

​Pitfalls

​Source

Function

What it normalizes

What it does NOT do

Template preservation

Pitfalls

Source