Tawfir.Tafqit 1.1.2

Tawfir.Tafqit

تفقيط — Numbers, money amounts, and ages in words, with correct Arabic grammar.

Turn 1234.50 into ألف ومائتان وأربعة وثلاثون ريالاً سعودياً وخمسون هللةً — for invoices, receipts, cheques, contracts, and HR letters across the GCC and Egypt. Arabic by default, plus English, Persian, and Turkish.

TafqitConverter.ToWords(1234.50m, TafqitCurrency.Sar);
// ألف ومائتان وأربعة وثلاثون ريالاً سعودياً وخمسون هللةً

Contents

• Installation
• Quick Start
• Features
• Which Method Do I Need?
• Plain Numbers
• Currency Amounts
• Age
• All Languages at a Glance
• Common Use Cases
• Arabic Grammar Handled for You
• Error Handling
• API Reference
• FAQ
• Requirements
• License
• Support and Contact

Installation

dotnet add package Tawfir.Tafqit

Or in Visual Studio: Manage NuGet Packages → search for Tawfir.Tafqit → Install.

Quick Start

using Tawfir.Tafqit;

string words  = TafqitConverter.ToWords(1234);                         // ألف ومائتان وأربعة وثلاثون
string amount = TafqitConverter.ToWords(1234.50m, TafqitCurrency.Sar); // ألف ومائتان وأربعة وثلاثون ريالاً سعودياً وخمسون هللةً
string age    = TafqitConverter.ToAge(25, 3, 2);                       // خمسة وعشرون عاماً وثلاثة أشهر ويومان

💡 Everything is in one static class, TafqitConverter, with two methods: ToWords and ToAge. No setup, no dependency injection, no configuration.

Features

Which Method Do I Need?

Plain Numbers

Use ToWords with a long or decimal to spell a number with no currency or unit.

using Tawfir.Tafqit;

TafqitConverter.ToWords(21);          // واحد وعشرون
TafqitConverter.ToWords(1234);        // ألف ومائتان وأربعة وثلاثون
TafqitConverter.ToWords(11000);       // أحد عشر ألفاً
TafqitConverter.ToWords(15500);       // خمسة عشر ألفاً وخمسمائة
TafqitConverter.ToWords(103000);      // مائة وثلاثة آلاف
TafqitConverter.ToWords(1000000);     // مليون
TafqitConverter.ToWords(-21);         // سالب واحد وعشرون

TafqitConverter.ToWords(12.04m);      // اثنا عشر فاصلة صفر أربعة
TafqitConverter.ToWords(12.00m);      // اثنا عشر

In other languages — pass a TafqitLanguage:

TafqitConverter.ToWords(1234, TafqitLanguage.English);    // one thousand two hundred and thirty-four
TafqitConverter.ToWords(1234, TafqitLanguage.Persian);    // هزار و دویست و سی و چهار
TafqitConverter.ToWords(1234, TafqitLanguage.Turkish);    // bin iki yüz otuz dört

TafqitConverter.ToWords(12.04m, TafqitLanguage.English);  // twelve point zero four

📌 Rules

• Digits after the decimal point are read one by one: 12.04 → twelve point zero four
• A whole value such as 12.00 has no decimal part
• English uses British style: one hundred and five

Currency Amounts

Use ToWords with a TafqitCurrency to spell an amount with its main and minor units.

using Tawfir.Tafqit;

TafqitConverter.ToWords(1m, TafqitCurrency.Sar);         // ريال سعودي واحد
TafqitConverter.ToWords(2m, TafqitCurrency.Sar);         // ريالان سعوديان
TafqitConverter.ToWords(5m, TafqitCurrency.Sar);         // خمسة ريالات سعودية
TafqitConverter.ToWords(11m, TafqitCurrency.Sar);        // أحد عشر ريالاً سعودياً
TafqitConverter.ToWords(15000m, TafqitCurrency.Sar);     // خمسة عشر ألف ريال سعودي
TafqitConverter.ToWords(1234.50m, TafqitCurrency.Sar);   // ألف ومائتان وأربعة وثلاثون ريالاً سعودياً وخمسون هللةً
TafqitConverter.ToWords(0.13m, TafqitCurrency.Sar);      // ثلاث عشرة هللةً

TafqitConverter.ToWords(1.250m, TafqitCurrency.Bhd);     // دينار بحريني واحد ومائتان وخمسون فلساً
TafqitConverter.ToWords(0.750m, TafqitCurrency.Kwd);     // سبعمائة وخمسون فلساً

Supported Currencies

Formal Closing for Cheques and Official Documents

Set formalClosing: true to wrap the amount in the standard closing phrase:

TafqitConverter.ToWords(1234.50m, TafqitCurrency.Sar, formalClosing: true);
// فقط ألف ومائتان وأربعة وثلاثون ريالاً سعودياً وخمسون هللةً لا غير

TafqitConverter.ToWords(1234.50m, TafqitCurrency.Sar, TafqitLanguage.English, formalClosing: true);
// one thousand two hundred and thirty-four Saudi riyals and fifty halalas only

📌 Rules

• The minor unit is rounded to the currency's decimal places (midpoint away from zero): 1.005 SAR → ريال سعودي واحد وهللة واحدة
• A zero main part is left out: 0.13 SAR → ثلاث عشرة هللةً
• A zero minor part is left out: 15000.00 SAR → خمسة عشر ألف ريال سعودي
• A negative amount throws ArgumentOutOfRangeException — an amount in words should never be negative

Choosing the Layout: Currency Name, Minor Unit, Closing

Pass a TafqitMoneyOptions to decide how the amount looks — for example from a per-company or per-invoice-type setting:

var options = new TafqitMoneyOptions
{
    Language = TafqitLanguage.Arabic,           // default
    IncludeCurrency = true,                     // default: write ريال / دينار and هللة / فلس
    MinorUnits = TafqitMinorUnitStyle.Digits,   // Words (default), Digits, or Fraction
    FormalClosing = false,                      // default
};

TafqitConverter.ToWords(154.212m, TafqitCurrency.Bhd, options);
// مائة وأربعة وخمسون ديناراً بحرينياً و212 فلساً

📌 Rules

• The defaults give exactly the same text as ToWords(amount, currency, language, formalClosing)
• Digits: the unit follows Arabic counting rules (5 فلوس، 12 فلساً، 212 فلساً); 1 and 2 take the singular (2 فلس)
• Fraction is padded to the currency's decimal places: 154.005 BHD → و005/1000, 0.05 SAR → 05/100
• Without the currency name, the minor unit is always a fraction — "و212" alone would not say what it counts

Age

From Years, Months, and Days

using Tawfir.Tafqit;

TafqitConverter.ToAge(1);            // عام واحد
TafqitConverter.ToAge(2);            // عامان
TafqitConverter.ToAge(7);            // سبعة أعوام
TafqitConverter.ToAge(25, 3, 2);     // خمسة وعشرون عاماً وثلاثة أشهر ويومان
TafqitConverter.ToAge(0, 1, 0);      // شهر واحد
TafqitConverter.ToAge(0, 0, 10);     // عشرة أيام
TafqitConverter.ToAge(0);            // أقل من يوم

From a Date of Birth

// Age as of today
string age = TafqitConverter.ToAge(new DateOnly(1990, 5, 20));

// Age as of a specific date
TafqitConverter.ToAge(new DateOnly(2000, 1, 15), asOf: new DateOnly(2026, 3, 10));
// ستة وعشرون عاماً وشهر واحد وثلاثة وعشرون يوماً

TafqitConverter.ToAge(new DateOnly(1990, 5, 20), TafqitLanguage.English, asOf: new DateOnly(2026, 10, 27));
// thirty-six years, five months, and seven days

Arabic Year Word: عام or سنة

Choose the Arabic word for "year" with yearWord. The default is عام. This option only changes Arabic output.

TafqitConverter.ToAge(7);                                         // سبعة أعوام
TafqitConverter.ToAge(7, yearWord: TafqitYearWord.Sanah);         // سبع سنوات
TafqitConverter.ToAge(25, 3, 2, yearWord: TafqitYearWord.Sanah);  // خمس وعشرون سنةً وثلاثة أشهر ويومان

📌 Rules

• Zero parts are left out: ToAge(0, 1, 0) → شهر واحد
• A zero age — ToAge(0), or a date of birth equal to asOf (a newborn) — is أقل من يوم / less than a day / کمتر از یک روز / bir günden az
• Parts are spelled as given: 18 months stays eighteen months
• From a date of birth, the age is counted in completed years, months, and days; asOf defaults to today
• Born on the 29th–31st: when that day does not exist in a month, the month is completed on its last day — born 31 January, the age on 1 March is شهر واحد ويوم واحد
• Born on 29 February: the year is completed on 28 February in non-leap years
• A negative part, or a date of birth after asOf, throws ArgumentOutOfRangeException

All Languages at a Glance

Common Use Cases

🧾 Invoices and receipts — amount in words

public class InvoiceModel
{
    public decimal Total { get; set; }

    public string TotalInWordsAr => TafqitConverter.ToWords(Total, TafqitCurrency.Sar);
    public string TotalInWordsEn => TafqitConverter.ToWords(Total, TafqitCurrency.Sar, TafqitLanguage.English);
}

🏦 Cheques and payment vouchers

string chequeLine = TafqitConverter.ToWords(15000.500m, TafqitCurrency.Bhd, formalClosing: true);
// فقط خمسة عشر ألف دينار بحريني وخمسمائة فلس لا غير

📄 Contracts and HR letters — age

string age = TafqitConverter.ToAge(employee.DateOfBirth, yearWord: TafqitYearWord.Sanah);

🌍 Multilingual apps — language from the user's profile

TafqitLanguage language = user.LanguageCode switch
{
    "en" => TafqitLanguage.English,
    "fa" => TafqitLanguage.Persian,
    "tr" => TafqitLanguage.Turkish,
    _    => TafqitLanguage.Arabic
};

string text = TafqitConverter.ToWords(order.Total, TafqitCurrency.Sar, language);

Arabic Grammar Handled for You

✅ Gender agreement — the number takes the opposite gender for 3–10: خمسة ريالات, but ثلاث هللات
✅ One and two — the noun comes first for one, and the dual is used for two: ريال سعودي واحد، ريالان سعوديان
✅ Plural for 3–10 — خمسة دنانير بحرينية، ثماني سنوات
✅ Accusative for 11–99 — أحد عشر ريالاً سعودياً، ثلاث عشرة هللةً
✅ Thousands and millions — ثلاثة آلاف، أحد عشر ألفاً، مائة وثلاثة آلاف، أحد عشر مليوناً
✅ Before a noun — the scale word drops its accusative ending before the currency: خمسة عشر ألف ريال سعودي
✅ Feminine units — هللة, بيسة, and سنة take feminine numbers: إحدى عشرة سنةً، ثماني هللات

Error Handling

Invalid input always throws ArgumentOutOfRangeException — you never get an empty or partial string.

try
{
    string words = TafqitConverter.ToWords(amount, TafqitCurrency.Sar);
}
catch (ArgumentOutOfRangeException ex)
{
    logger.LogWarning(ex, "Cannot spell amount {Amount}", amount);
}

API Reference

namespace Tawfir.Tafqit;

public static class TafqitConverter
{
    // Plain numbers
    string ToWords(long number, TafqitLanguage language = TafqitLanguage.Arabic);
    string ToWords(decimal number, TafqitLanguage language = TafqitLanguage.Arabic);

    // Currency amounts
    string ToWords(decimal amount, TafqitCurrency currency,
                   TafqitLanguage language = TafqitLanguage.Arabic, bool formalClosing = false);
    string ToWords(decimal amount, TafqitCurrency currency, TafqitMoneyOptions options);

    // Age
    string ToAge(int years, int months = 0, int days = 0,
                 TafqitLanguage language = TafqitLanguage.Arabic, TafqitYearWord yearWord = TafqitYearWord.Aam);
    string ToAge(DateOnly dateOfBirth,
                 TafqitLanguage language = TafqitLanguage.Arabic, TafqitYearWord yearWord = TafqitYearWord.Aam,
                 DateOnly? asOf = null);
}

TafqitMoneyOptions properties: Language (Arabic), IncludeCurrency (true), MinorUnits (Words), FormalClosing (false).

All types are in the Tawfir.Tafqit namespace.

FAQ

Is it free?
Yes. Tawfir.Tafqit is free to use in your own applications, including commercial ones. See License.

Does it need internet access or a database?
No. Everything runs in memory inside your application.

Can I use it from several threads at once?
Yes. TafqitConverter is static and keeps no state, so it is safe to call in parallel.

Will the output change if my server's language or region changes?
No. The output is the same on every machine and culture.

My currency or language is not listed. Can it be added?
Contact us — see Support and Contact.

Requirements

• .NET 10.0 or higher (SDK-style projects; TargetFramework net10.0)

License

Proprietary — Free to Use

• ✅ Free to use in your own applications, including commercial applications
• 🔒 Closed source — decompiling, modifying, or redistributing the library on its own is not permitted
• 📄 See LICENSE.txt in the package for the full terms

Support and Contact

Questions, bugs, a new currency or language, or custom work — get in touch:

Author

Wael El Azizy — waelelazizy.com