Tafkeet - تفقيط #

A Flutter package for converting numbers to words in Arabic and English with currency support.

Features #

• ✅ Convert numbers to words in Arabic and English
• ✅ Support for 90+ world currencies
• ✅ Custom currency support
• ✅ Large number support (up to trillions)
• ✅ Decimal number support with automatic rounding based on currency precision
• ✅ Gender-aware conversion (masculine/feminine)
• ✅ Custom prefix and suffix
• ✅ Extensions on double, int, and String
• ✅ Extensible for more languages

Installation #

Add the package to your pubspec.yaml:

dependencies:
  tafkeet: ^1.2.1

Then run:

flutter pub get

Usage #

Simple Example #

import 'package:tafkeet/tafkeet.dart';

void main() {
  // Convert number to Arabic
  print(Tafkeet.convert(120, lang: Lang.ar));
  // Output: مائة و عشرون

  // Convert number to English
  print(Tafkeet.convert(120, lang: Lang.en));
  // Output: One Hundred Twenty

}

Using Currencies #

// Convert amount in Saudi Riyal
print(Tafkeet.convert(250.50, lang: Lang.ar, currency: Currency.SAR));
// Output: مئتان و خمسون ريالاً سعودياً و خمسون هللة

// Convert amount in US Dollar
print(Tafkeet.convert(100, lang: Lang.en, currency: Currency.USD));
// Output: One Hundred US Dollars

Note: Decimal numbers are automatically rounded based on the currency's precision (defined by partPrecision). Most currencies use 2 decimal places, but some like Bitcoin can support up to 8 decimal places.

// Example: 19002.989 will be rounded to 2 decimal places (99) for most currencies
print(Tafkeet.convert(19002.989, lang: Lang.ar, currency: Currency.SAR));
// Result: تسعة عشر ألف و اثنان ريال سعودي و تسعة و تسعون هللة

Configure Default Settings #

// Set default language and currency
Tafkeet.configure(
  defaultLang: Lang.ar,
  defaultCurrency: Currency.SAR,
);

// Now you can use convert without specifying language and currency
print(Tafkeet.convert(100));
// Output: مائة ريال سعودي

Using Available Currencies #

All currencies in the Currency enum can be used directly:

// Use Egyptian Pound (already available)
print(Tafkeet.convert(50, lang: Lang.ar, currency: Currency.EGP));
// Output: خمسون جنيهاً مصرياً

// Use Kuwaiti Dinar
print(Tafkeet.convert(100, lang: Lang.ar, currency: Currency.KWD));

// Use Euro
print(Tafkeet.convert(200, lang: Lang.ar, currency: Currency.EUR));

Customize Existing Currency #

If you want to customize an existing currency (e.g., change part names):

CurrencyConfig.updateCurrency(
  'EGP',
  CurrencyInfo(
    currencyId: 10,
    currencyCode: 'EGP',
    isCurrencyNameFeminine: false,
    englishCurrencyName: 'Egyptian Pound',
    englishPluralCurrencyName: 'Egyptian Pounds',
    englishCurrencyPartName: 'Piaster',
    englishPluralCurrencyPartName: 'Piasters',
    arabic1CurrencyName: 'جنيه مصري',
    arabic2CurrencyName: 'جنيهان مصريان',
    arabic310CurrencyName: 'جنيهات مصرية',
    arabic1199CurrencyName: 'جنيهاً مصرياً',
    arabic1CurrencyPartName: 'قرش',
    arabic2CurrencyPartName: 'قرشان',
    arabic310CurrencyPartName: 'قروش',
    arabic1199CurrencyPartName: 'قرشاً',
    partPrecision: 2,
    isCurrencyPartNameFeminine: false,
  ),
);

// Now use the customized currency
print(Tafkeet.convert(50, lang: Lang.ar, currency: Currency.EGP));

Add New Currency #

If you want to add a currency that's not in the Currency enum:

CurrencyConfig.addCurrency(
  'BTC',
  CurrencyInfo(
    currencyId: 999,
    currencyCode: 'BTC',
    isCurrencyNameFeminine: false,
    englishCurrencyName: 'Bitcoin',
    englishPluralCurrencyName: 'Bitcoins',
    englishCurrencyPartName: 'Satoshi',
    englishPluralCurrencyPartName: 'Satoshi',
    arabic1CurrencyName: 'بيتكوين',
    arabic2CurrencyName: 'بيتكوينان',
    arabic310CurrencyName: 'بيتكوينات',
    arabic1199CurrencyName: 'بيتكويناً',
    arabic1CurrencyPartName: 'ساتوشي',
    arabic2CurrencyPartName: 'ساتوشيان',
    arabic310CurrencyPartName: 'ساتوشيات',
    arabic1199CurrencyPartName: 'ساتوشياً',
    partPrecision: 8,
    isCurrencyPartNameFeminine: false,
  ),
);

// Use custom currency by code
print(Tafkeet.convert(3, lang: Lang.ar, currencyCode: 'BTC'));
// Output: ثلاثة بيتكوينات

Using Custom Prefix and Suffix #

By default, prefix and suffix are empty. You can add them as needed:

// Without prefix and suffix (default)
print(Tafkeet.convert(500, lang: Lang.ar, currency: Currency.SAR));
// Output: خمسمائة ريال سعودي

// With custom prefix and suffix
print(Tafkeet.convert(
  500,
  lang: Lang.ar,
  currency: Currency.SAR,
  prefix: 'المبلغ:',
  suffix: 'فقط لاغير',
));
// Output: المبلغ: خمسمائة ريال سعودي فقط لاغير

Using Extensions #

The package provides useful extensions to convert numbers directly to words in an easier and shorter way:

Extension on Double #

// Use extension on double
120.5.tafkeet(lang: Lang.ar);
// Output: مائة و عشرون و خمسون

// With currency
250.75.tafkeet(lang: Lang.ar, currency: Currency.SAR);
// Output: مئتان و خمسون ريالاً سعودياً و خمسة و سبعون هللة

Extension on Int #

// Use extension on int
100.tafkeet(lang: Lang.en);
// Output: One Hundred

// With currency
500.tafkeet(lang: Lang.ar, currency: Currency.USD);
// Output: خمسمائة دولار أمريكي

Extension on String #

// Use extension on string (if text is numeric)
'75.25'.tafkeet(lang: Lang.ar);
// Output: خمسة و سبعون و خمسة و عشرون

// If text is not numeric, returns original text
'Hello World'.tafkeet(lang: Lang.ar);
// Output: Hello World

// With currency
'1000'.tafkeet(lang: Lang.en, currency: Currency.EUR);
// Output: One Thousand Euros

// Supports Arabic-Indic numerals (automatically converted)
'٥٠٠'.tafkeet(lang: Lang.ar, currency: Currency.SAR);
// Output: خمسمائة ريال سعودي

// Replace Arabic numerals with English numerals
'١٢٣.٤٥'.replaceArabicNumbers();
// Output: 123.45

Comprehensive Extension Example #

void main() {
  // Configure default settings
  Tafkeet.configure(defaultLang: Lang.ar, defaultCurrency: Currency.SAR);
  
  // Use with different types
  final double amount1 = 123.45;
  final int amount2 = 200;
  final String amount3 = '350.75';
  final String text = 'not a number';
  
  print(amount1.tafkeet());  // Uses default settings
  print(amount2.tafkeet(lang: Lang.en));
  print(amount3.tafkeet(currency: Currency.EGP));
  print(text.tafkeet());  // Returns: not a number
}

Benefits of Using Extensions #

• ✅ Shorter and clearer code: Instead of Tafkeet.convert(120) you can write 120.tafkeet()
• ✅ Better readability: Code becomes more natural and easy to read
• ✅ String support: Convert numeric text directly, with protection from non-numeric text
• ✅ Arabic numerals support: Automatically handles Arabic-Indic digits (٠١٢٣٤٥٦٧٨٩)
• ✅ Number formatting: Format numbers with thousand separators using amountFormat()
• ✅ Full flexibility: Same parameters available in Tafkeet.convert()

Number Formatting #

The package provides utilities to format numbers with thousand separators:

Format Numbers with Separators #

// Using static method
NumberUtils.amountFormat(1234567); // Returns: '1,234,567'
NumberUtils.amountFormat(1234567.89, digit: 2); // Returns: '1,234,567.89'

// Using extension on double
1234567.89.amountFormat(digit: 2); // Returns: '1,234,567.89'

// Using extension on int
1234567.amountFormat(); // Returns: '1,234,567'

// Using extension on String
'1234567.89'.amountFormat(digit: 2); // Returns: '1,234,567.89'

// Works with Arabic numerals
'١٢٣٤٥٦٧'.amountFormat(); // Returns: '1,234,567'

// Large numbers
1234567890.12.amountFormat(digit: 2); // Returns: '1,234,567,890.12'

Combine with tafkeet() #

final amount = 1234567.89;

// Format the number
print(amount.amountFormat(digit: 2)); 
// Output: 1,234,567.89

// Convert to words
print(amount.tafkeet(lang: Lang.ar, currency: Currency.SAR));
// Output: واحد مليون و مئتان و أربعة و ثلاثون ألف و خمسمائة و سبعة و ستون ريالاً سعودياً و تسعة و ثمانون هللة

Arabic-Indic Numerals Support #

The package provides full support for Arabic-Indic numerals (٠١٢٣٤٥٦٧٨٩) used in Arabic texts:

Automatic Conversion in tafkeet() #

The tafkeet() extension automatically converts Arabic-Indic numerals:

// Works with English numerals
'123'.tafkeet(lang: Lang.ar);
// Output: مائة و ثلاثة و عشرون

// Works with Arabic-Indic numerals (automatically converted)
'١٢٣'.tafkeet(lang: Lang.ar);
// Output: مائة و ثلاثة و عشرون

// Works with decimals
'١٢٣.٤٥'.tafkeet(lang: Lang.ar, currency: Currency.SAR);
// Output: مائة و ثلاثة و عشرون ريالاً سعودياً و خمسة و أربعون هللة

Manual Replacement #

You can also manually replace Arabic-Indic numerals using:

// Using static method
NumberUtils.replaceArabicNumber('١٢٣.٤٥');
// Returns: '123.45'

// Using extension
'١٢٣.٤٥'.replaceArabicNumbers();
// Returns: '123.45'

// In mixed text
'السعر: ٩٩٩ ريال'.replaceArabicNumbers();
// Returns: 'السعر: 999 ريال'

// All digits
'٠١٢٣٤٥٦٧٨٩'.replaceArabicNumbers();
// Returns: '0123456789'

Supported Currencies #

90+ World Currencies! #

The package supports more than 90 currencies from around the world:

Arabic Currencies (21 currencies)

SAR, AED, KWD, QAR, OMR, BHD, EGP, SYP, JOD, LBP, IQD, YER, LYD, TND, DZD, MAD, SDG, SOS, MRU, DJF, KMF

Major World Currencies

USD, EUR, GBP, JPY, CHF, CAD, AUD, NZD, CNY, INR, RUB, BRL, ZAR, SEK, NOK, DKK, PLN, TRY, IDR, MYR, THB, PHP, SGD, HKD, KRW, MXN, and more...

Usage Examples #

Getting Currency Lists #

// All supported currencies
print('Total currencies: ${Currency.values.length}'); // 91+

// Arabic currencies only
for (final currency in Currency.arabicCurrencies) {
  print('${currency.code}: ${currency.arabicName}');
}

// Major currencies
for (final currency in Currency.majorCurrencies) {
  print('${currency.code}: ${currency.arabicName}');
}

CurrencyConfig Functions #

// Add currency
CurrencyConfig.addCurrency(code, currencyInfo);

// Update existing currency
CurrencyConfig.updateCurrency(code, currencyInfo);

// Remove currency
CurrencyConfig.removeCurrency(code);

// Get currency
CurrencyInfo? currency = CurrencyConfig.getCurrency(code);

// Check if currency exists
bool exists = CurrencyConfig.hasCurrency(code);

// Get all currencies
Map<String, CurrencyInfo> currencies = CurrencyConfig.getAllCurrencies();

// Get available currency codes
List<String> codes = CurrencyConfig.getAvailableCurrencyCodes();

// Reset to default settings
CurrencyConfig.reset();

Additional Examples #

Convert Large Numbers #

print(Tafkeet.convert(1234567, lang: Lang.ar, currency: Currency.SAR));
// Output: واحد مليون و مئتان و أربعة و ثلاثون ألف و خمسمائة و سبعة و ستون ريالاً سعودياً

Handle Feminine Currencies #

// Syrian Pound (feminine currency)
print(Tafkeet.convert(200, lang: Lang.ar, currency: Currency.SYP));
// Output: مئتا ليرة سورية

Decimal Rounding #

The package automatically rounds decimal numbers based on the currency's partPrecision setting:

// Most currencies use 2 decimal places
print(Tafkeet.convert(19002.989, lang: Lang.ar, currency: Currency.SAR));
// 19002.989 → rounded to 19002.99
// Result: تسعة عشر ألف و اثنان ريال سعودي و تسعة و تسعون هللة

print(Tafkeet.convert(19002.989, lang: Lang.en, currency: Currency.USD));
// Result: Nineteen Thousand Two US Dollars and Ninety Nine Cents

// Bitcoin supports up to 8 decimal places
CurrencyConfig.addCurrency('BTC', CurrencyInfo(
  // ... with partPrecision: 8
));
print(Tafkeet.convert(0.12345678, lang: Lang.en, currencyCode: 'BTC'));
// All 8 decimal places preserved

Supported Languages #

The package currently supports two languages with the ability to extend to other languages:

Language Usage Example #

// Using Arabic
print(Tafkeet.convert(1250, lang: Lang.ar, currency: Currency.SAR));
// Output: واحد ألف و مئتان و خمسون ريالاً سعودياً

// Using English
print(Tafkeet.convert(1250, lang: Lang.en, currency: Currency.SAR));
// Output: One Thousand Two Hundred Fifty Saudi Riyals

// Without specifying language (uses default)
Tafkeet.configure(defaultLang: Lang.ar, defaultCurrency: Currency.SAR);
print(Tafkeet.convert(1250));

License #

This project is licensed under the MIT License.

Contributing #

Contributions are welcome! Please open an issue or pull request on GitHub.

Support #

If you encounter any issues or have suggestions, please open an issue on GitHub.