Documentation Index Fetch the complete documentation index at: https://persian-tools.usestrict.dev/llms.txt
Use this file to discover all available pages before exploring further.
Persian Character Conversion
The toPersianChars utility converts Arabic and English characters to their proper Persian equivalents, ensuring consistent Persian text rendering and processing.
Basic Usage
import { toPersianChars } from '@persian-tools/persian-tools' ;
Simple Conversion
toPersianChars ( "علي احمد" ); // 'علی احمد' (Arabic ي to Persian ی)
toPersianChars ( "كتاب" ); // 'کتاب' (Arabic ك to Persian ک)
toPersianChars ( "ي ك" ); // 'ی ک' (multiple conversions)
Character Mappings
Arabic to Persian
English to Persian
Arabic Persian Description ي ی Ya (Arabic to Persian) ك ک Kaf (Arabic to Persian) ٪ ٪ Percent sign ء ء Hamza
English Persian Description y ی Latin y to Persian ya k ک Latin k to Persian kaf % ٪ Percent to Persian percent
Advanced Examples
Text Normalization
function normalizePersianeText ( text : string ) : string {
// Convert characters to Persian
let normalized = toPersianChars ( text );
// Apply half-space corrections
normalized = halfSpace ( normalized );
// Convert digits to Persian
normalized = digitsEnToFa ( normalized );
return normalized . trim ();
}
normalizePersianeText ( "علي در كتابخانه مي خواند" );
// Output: 'علی در کتابخانه میخواند'
interface UserInput {
name : string ;
description : string ;
tags : string [];
}
function processUserInput ( input : UserInput ) : UserInput {
return {
name: toPersianChars ( input . name ),
description: toPersianChars ( input . description ),
tags: input . tags . map (( tag ) => toPersianChars ( tag )),
};
}
const processed = processUserInput ({
name: "علي محمدي" ,
description: "كتاب جديد در مورد برنامه نويسي" ,
tags: [ "برنامه نويسي" , "كتاب" , "آموزش" ],
});
Content Management System
class ContentProcessor {
static processArticle ( article : { title : string ; content : string ; author : string }) {
return {
title: toPersianChars ( article . title ),
content: this . processContent ( article . content ),
author: toPersianChars ( article . author ),
slug: slugify ( toPersianChars ( article . title )),
};
}
private static processContent ( content : string ) : string {
// Convert characters
let processed = toPersianChars ( content );
// Fix spacing issues
processed = halfSpace ( processed );
// Ensure proper Persian formatting
return processed ;
}
}
Text Validation Integration
Combined with Persian Text Validation
function validateAndNormalizePersianText ( text : string ) : {
original : string ;
normalized : string ;
isPersian : boolean ;
corrections : string [];
} {
const corrections : string [] = [];
let normalized = text ;
// Convert characters to Persian
const converted = toPersianChars ( text );
if ( converted !== text ) {
corrections . push ( "نویسههای عربی به فارسی تبدیل شدند" );
normalized = converted ;
}
// Check if result is Persian
const isPersianText = isPersian ( normalized );
return {
original: text ,
normalized ,
isPersian: isPersianText ,
corrections ,
};
}
Search Optimization
function createSearchableText ( text : string ) : string {
// Normalize characters for consistent searching
let searchable = toPersianChars ( text );
// Convert to lowercase equivalent (where applicable)
searchable = searchable . toLowerCase ();
// Remove extra whitespace
searchable = searchable . replace ( / \s + / g , " " ). trim ();
return searchable ;
}
// Usage in search function
function searchContent ( query : string , content : string []) : string [] {
const normalizedQuery = createSearchableText ( query );
return content . filter (( item ) => createSearchableText ( item ). includes ( normalizedQuery ));
}
Database Considerations
Storage Strategy
interface DatabaseRecord {
id : string ;
originalText : string ; // Keep original for audit
normalizedText : string ; // Normalized for consistency
searchableText : string ; // Optimized for search
}
function createDatabaseRecord ( text : string ) : Omit < DatabaseRecord , "id" > {
const normalized = toPersianChars ( text );
const searchable = createSearchableText ( normalized );
return {
originalText: text ,
normalizedText: normalized ,
searchableText: searchable ,
};
}
Migration Script
async function migratePersianTexts ( records : Array <{ id : string ; text : string }>) {
const migrated = records . map (( record ) => ({
... record ,
text: toPersianChars ( record . text ),
updatedAt: new Date (),
}));
// Log changes
const changedRecords = migrated . filter (( record , index ) => record . text !== records [ index ]. text );
console . log ( `Updated ${ changedRecords . length } records with Persian character conversion` );
return migrated ;
}
📦 Optimization Strategies
Cache results for frequently converted text
Process in chunks for very large texts
Combine with other text processing for efficiency
Use with debouncing for real-time input processing
import { useState , useCallback } from 'react' ;
import { debounce } from 'lodash' ;
function PersianTextInput ({ onChange } : { onChange : ( text : string ) => void }) {
const [ value , setValue ] = useState ( '' );
const debouncedProcess = useCallback (
debounce (( text : string ) => {
const processed = toPersianChars ( text );
onChange ( processed );
}, 300 ),
[ onChange ]
);
const handleChange = ( e : React . ChangeEvent < HTMLInputElement >) => {
const inputValue = e . target . value ;
setValue ( inputValue );
debouncedProcess ( inputValue );
};
return (
< input
type = "text"
value = { value }
onChange = { handleChange }
placeholder = "متن فارسی خود را وارد کنید"
dir = "rtl"
/>
);
}
Vue.js Directive
// Vue directive for automatic Persian character conversion
app . directive ( "persian-chars" , {
mounted ( el : HTMLInputElement ) {
el . addEventListener ( "input" , ( e ) => {
const target = e . target as HTMLInputElement ;
const converted = toPersianChars ( target . value );
if ( converted !== target . value ) {
target . value = converted ;
target . dispatchEvent ( new Event ( "input" ));
}
});
},
});
Edge Cases
Mixed Content
toPersianChars ( "Hello علي" ); // 'Hello علی' (only Persian chars converted)
toPersianChars ( "123 ك 456" ); // '123 ک 456' (numbers unchanged)
toPersianChars ( "email@domain.com ي" ); // 'email@domain.com ی'
Already Converted Text
toPersianChars ( "علی کتاب" ); // 'علی کتاب' (no change needed)
toPersianChars ( "" ); // '' (empty string)
toPersianChars ( null ); // '' (graceful handling)
Special Characters
toPersianChars ( "نرخ %5 است" ); // 'نرخ ٪۵ است' (with digit conversion)
toPersianChars ( "كلمهي مهم" ); // 'کلمهی مهم' (preserves half-space)
TypeScript Support
import { toPersianChars } from "persian-tools" ;
// Type-safe usage
const converted : string = toPersianChars ( "علي" );
// Generic text processor
function processText < T extends { text : string }>( obj : T ) : T {
return {
... obj ,
text: toPersianChars ( obj . text ),
};
}
Half Space Fix Persian text spacing issues
Is Persian Validate Persian text content
Digit Conversion Convert between Persian, Arabic, and English digits
Slugify Create URL-friendly slugs from Persian text