Skip to main content

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
ArabicPersianDescription
يیYa (Arabic to Persian)
كکKaf (Arabic to Persian)
٪٪Percent sign
ءءHamza

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: 'علی در کتابخانه می‌خواند'

Form Input Processing

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;
}

Performance Optimization

  • Small text (< 100 chars): ~0.1ms
  • Medium text (< 1000 chars): ~0.5ms
  • Large text (< 10000 chars): ~2ms
  • Memory usage: Minimal overhead
  • 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

Real-time Input Processing

React Input Component

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),
	};
}