Skip to content

persian.md

Latest commit

 

History

History
173 lines (122 loc) · 7.64 KB

persian.md

File metadata and controls

173 lines (122 loc) · 7.64 KB

Harfizer — خواندن اعداد، تاریخ و زمان به زبان فارسی

Harfizer یک بسته قدرتمند است که برای تبدیل اعداد، تاریخ‌ها و زمان‌ها به متن فارسی طراحی شده است. این بسته با استفاده از پلاگین‌های زبان خاص، به شما امکان می‌دهد تا به سادگی اعداد و زمان‌ها را به نمایش متنی فارسی درآورید.
اگر مایل به استفاده از زبان‌های دیگر هستید، می‌توانید از لینک‌های مستندات مربوطه در بالا یا پایین صفحه استفاده کنید.

فهرست مطالب

نصب

برای نصب Harfizer از npm استفاده کنید:

npm install harfizer

روش استفاده

ابتدا پلاگین فارسی و کلاس CoreConverter را از بسته Harfizer وارد کنید:

import { CoreConverter, PersianLanguagePlugin } from 'harfizer';

const persianPlugin = new PersianLanguagePlugin();
const converter = new CoreConverter(persianPlugin);

توابع

convertNumber(input: InputNumber, options?: ConversionOptions): string

این تابع یک عدد (صحیح یا اعشاری؛ امکان منفی بودن نیز وجود دارد) را به متن فارسی تبدیل می‌کند. در صورت وجود بخش اعشاری، هر رقم به صورت مجزا تبدیل شده و از عبارت "ممیز" برای جدا کردن بخش اعشار استفاده می‌شود.

پارامترها:

  • input: عدد، رشته عددی یا bigint.
  • options (اختیاری): شیئی برای سفارشی‌سازی فرایند تبدیل:
    • customZeroWord – تغییر کلمه پیش‌فرض "صفر".
    • customNegativeWord – تغییر کلمه پیش‌فرض "منفی".
    • customSeparator – تغییر جداکننده پیش‌فرض.

مقدار بازگشتی:
رشته‌ای متنی که معادل عدد ورودی به زبان فارسی است.

مثال:

converter.convertNumber("123"); 
// خروجی: "صد و بیست و سه"

converter.convertNumber("-456.78"); 
// خروجی: "منفی چهارصد و پنجاه و شش ممیز هفت و هشت"

convertTripleToWords(num: InputNumber, lexicon?: any, _separator?: string): string

این تابع یک عدد با حداکثر چهار رقم (مناسب برای اعداد کمتر از 10,000) را به صورت متنی فارسی تبدیل می‌کند.

پارامترها:

  • num: عدد با حداکثر ۴ رقم.

مقدار بازگشتی:
رشته‌ای متنی که معادل عدد ورودی (مثلاً "چهارصد و پنجاه و شش") است.

مثال:

converter.convertTripleToWords(789); 
// خروجی: "هفتصد و هشتاد و نه"

convertDateToWords(dateStr: string, calendar?: "jalali" | "gregorian"): string

این تابع یک رشته تاریخ به فرمت "YYYY/MM/DD" یا "YYYY-MM-DD" را به متن فارسی تبدیل می‌کند. خروجی شامل تبدیل روز و سال به اعداد متنی و نمایش نام ماه به زبان فارسی (بر اساس تقویم انتخابی) است.

پارامترها:

  • dateStr: رشته تاریخ.
  • calendar (اختیاری): نوع تقویم؛ "jalali" یا "gregorian"؛ پیش‌فرض "jalali".

مقدار بازگشتی:
رشته‌ای متنی که معادل تاریخ ورودی به زبان فارسی است.

مثال:

converter.convertDateToWords("1402/05/17"); 
// خروجی: "هفدهم مرداد یک هزار و چهارصد و دو"

convertTimeToWords(timeStr: string): string

این تابع یک رشته زمان به فرمت "HH:mm" را به متن فارسی تبدیل می‌کند. خروجی به صورت "ساعت <ساعت> و <دقیقه> دقیقه" است؛ در صورتی که دقیقه صفر باشد، فقط ساعت نمایش داده می‌شود.

پارامترها:

  • timeStr: رشته زمان به فرمت "HH:mm".

مقدار بازگشتی:
رشته‌ای متنی که معادل زمان ورودی به زبان فارسی است.

مثال:

converter.convertTimeToWords("09:00"); 
// خروجی: "ساعت نه"

converter.convertTimeToWords("09:05"); 
// خروجی: "ساعت نه و پنج دقیقه"

مثال‌ها

نمونه زیر نحوه استفاده از PersianLanguagePlugin و CoreConverter را نشان می‌دهد:

import { CoreConverter, PersianLanguagePlugin } from 'harfizer';

const persianPlugin = new PersianLanguagePlugin();
const converter = new CoreConverter(persianPlugin);

console.log(converter.convertNumber("123")); 
// خروجی: "صد و بیست و سه"

console.log(converter.convertDateToWords("1402/05/17")); 
// خروجی: "هفدهم مرداد یک هزار و چهارصد و دو"

console.log(converter.convertTimeToWords("09:05")); 
// خروجی: "ساعت نه و پنج دقیقه"

گزینه‌های اضافی

تابع convertNumber امکان پذیرش شیئی به نام ConversionOptions را دارد تا بتوانید فرایند تبدیل را سفارشی کنید:

const options = {
  customZeroWord: "صفر",
  customNegativeWord: "منفی",
  customSeparator: " و "
};

console.log(converter.convertNumber("-123", options)); 
// خروجی: "منفی صد و بیست و سه"

مستندات پلاگین‌های زبان‌های دیگر

برای مشاهده مستندات سایر پلاگین‌های زبان، لطفاً به موارد زیر مراجعه کنید:

مجوز

این بسته تحت مجوز MIT منتشر شده است.