Skip to main content

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

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

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