Amount to Words #

A comprehensive Flutter package for converting numbers and amounts to words in multiple languages with full currency support.

🌟 Overview #

Transform numbers into human-readable text across multiple languages and currencies. Perfect for invoices, receipts, financial applications, and any app that needs to display amounts in words.

🎯 Key Highlights #

• 7 Supported Currencies: Iranian Rial, Toman, US Dollar, Euro, Canadian Dollar, Turkish Lira, Afghan Afghani
• 3 Languages: Persian (Farsi), English, Turkish with native grammar rules
• Smart Pluralization: Automatic singular/plural handling for each language
• Multiple Formats: Pure words, mixed (digits + words), and native digit formats
• Zero Dependencies: Pure Dart implementation with minimal footprint

Features #

• ✅ Multi-language Support: Persian (Farsi), English, and Turkish
• ✅ Currency Integration: Full support for major currencies with proper pluralization
• ✅ Multiple Number Formats: Words, Mixed (digits + words), Language digits, Latin digits
• ✅ Automatic Localization: Integrates seamlessly with Flutter's localization system
• ✅ Extensible Architecture: Easy to add new languages and currencies
• ✅ Smart Pluralization: Handles singular/plural forms correctly for each language
• ✅ No Dependencies: Pure Dart implementation with minimal footprint
• ✅ Comprehensive Testing: 100% test coverage with edge cases
• ✅ TypeScript-like Type Safety: Full null safety support

Supported Languages #

💰 Supported Currencies #

🔍 Currency Details #

• Iranian Currencies: Rial and Toman (no decimal support as per local usage)
• Major International: USD, EUR, CAD with full decimal support
• Regional: Turkish Lira and Afghan Afghani for regional applications
• Smart Pluralization: Automatic handling of singular/plural forms
• Custom Currencies: Easy to add your own currency configurations

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  amount_to_word: ^2.0.0

Then run:

flutter pub get

Number Formats #

This package supports multiple number display formats:

🚀 Quick Start #

Basic Number Conversion #

import 'package:amount_to_word/amount_to_word.dart';

void main() {
  // Create converter for specific language
  final persianConverter = AmountToWords(Language.fa);
  final englishConverter = AmountToWords(Language.en);
  final turkishConverter = AmountToWords(Language.tr);
  
  // Convert numbers to words
  print(persianConverter.toWords(12345));  
  // Output: دوازده هزار و سیصد و چهل و پنج
  
  print(englishConverter.toWords(12345));  
  // Output: twelve thousand three hundred forty-five
  
  print(turkishConverter.toWords(12345));  
  // Output: on iki bin üç yüz kırk beş
}

💡 Real-World Examples #

// Invoice amounts
final invoiceAmount = 1250.75;
final converter = AmountToWords(Language.en);

print(converter.convert(invoiceAmount, currency: CurrencyConfig.usDollar));
// Output: one thousand two hundred fifty dollars and seventy-five cents

// Persian invoice
final persianConverter = AmountToWords(Language.fa);
print(persianConverter.convert(1000000, currency: CurrencyConfig.iranianToman));
// Output: یک میلیون تومان

// Turkish price
final turkishConverter = AmountToWords(Language.tr);
print(turkishConverter.convert(89.99, currency: CurrencyConfig.euro));
// Output: seksen dokuz euro ve doksan dokuz sent

Currency Conversion #

import 'package:amount_to_word/amount_to_word.dart';

void main() {
  final converter = AmountToWords(Language.en);
  
  // US Dollar with proper pluralization
  print(converter.convert(1, currency: CurrencyConfig.usDollar));
  // Output: one dollar
  
  print(converter.convert(5.99, currency: CurrencyConfig.usDollar));
  // Output: five dollars and ninety-nine cents
  
  // Iranian currencies (no decimals)
  print(converter.convert(1000, currency: CurrencyConfig.iranianToman));
  // Output: one thousand toman
}

Mixed Format (Digits + Words) #

The mixed format combines digits with scale words for a more compact and readable representation:

import 'package:amount_to_word/amount_to_word.dart';

void main() {
  final faConverter = AmountToWords(Language.fa);
  final enConverter = AmountToWords(Language.en);
  final trConverter = AmountToWords(Language.tr);
  
  final number = 2566;
  
  // Persian mixed format
  print(faConverter.toMixed(number));
  // Output: ۲ هزار و ۵۶۶
  
  // English mixed format
  print(enConverter.toMixed(number));
  // Output: 2 thousand 566
  
  // Turkish mixed format
  print(trConverter.toMixed(number));
  // Output: 2 bin 566
  
  // With currency
  print(faConverter.convertToMixed(2566.75, currency: CurrencyConfig.usDollar));
  // Output: ۲ هزار و ۵۶۶ دلار و ۷۵ سنت
  
  print(enConverter.convertToMixed(2566.75, currency: CurrencyConfig.usDollar));
  // Output: 2 thousand 566 dollars and 75 cents
}

Number Format Configuration #

Customize the display format with NumberFormatConfig:

import 'package:amount_to_word/amount_to_word.dart';

void main() {
  final converter = AmountToWords(Language.fa);
  
  // Mixed format configuration
  final mixedConfig = NumberFormatConfig(
    format: NumberFormat.mixed,
    mixedFormatThreshold: 100, // Numbers below this use pure words
  );
  
  print(converter.toMixed(95));  // پنج و نود (below threshold)
  print(converter.toMixed(2566, formatConfig: mixedConfig));  // ۲ هزار و ۵۶۶
  
  // Language digits with commas
  final digitConfig = NumberFormatConfig(
    format: NumberFormat.languageDigits,
    addCommas: true,
  );
  
  print(NumberFormatter.formatLanguageNumber(1234567, Language.fa, addCommas: true));
  // Output: ۱,۲۳۴,۵۶۷
}

Flutter Integration with Auto-Detection #

import 'package:flutter/material.dart';
import 'package:amount_to_word/amount_to_word.dart';

class PriceDisplay extends StatelessWidget {
  final double amount;
  final CurrencyConfig currency;
  
  const PriceDisplay({required this.amount, required this.currency});
  
  @override
  Widget build(BuildContext context) {
    // Automatically detects language from app locale
    final converter = AmountToWords.fromContext(context);
    
    return Column(
      children: [
        Text('$amount'),
        Text(
          converter.convert(amount, currency: currency),
          style: TextStyle(fontStyle: FontStyle.italic),
        ),
      ],
    );
  }
}

Advanced Usage #

Custom Currency Configuration #

// Create custom currency
final bitcoin = CurrencyConfig(
  mainUnits: {
    Language.en: 'bitcoin',
    Language.fa: 'بیت‌کوین',
    Language.tr: 'bitcoin',
  },
  subUnits: {
    Language.en: 'satoshi',
    Language.fa: 'ساتوشی',
    Language.tr: 'satoshi',
  },
  subUnitInMainUnit: 100000000, // 100M satoshis = 1 bitcoin
);

final converter = AmountToWords(Language.en);
print(converter.convert(1.5, currency: bitcoin));
// Output: one bitcoin and fifty million satoshis

Adding New Languages to Existing Currencies #

// Extend existing currency with new language support
final usdWithArabic = CurrencyConfig.usDollar.addLanguage(
  Language.en, // Using English as placeholder for new language
  'dollar (arabic)',
  'cent (arabic)',
);

// Use the extended currency
final result = converter.convert(100.50, currency: usdWithArabic);

Integration with App's Currency System #

// Map your app's currency enum to package currencies
enum AppCurrency { rial, toman, dollar, euro, lira }

CurrencyConfig getCurrencyConfig(AppCurrency appCurrency) {
  return CurrencyConfig.getByAppCurrency(appCurrency);
}

// Usage
final config = getCurrencyConfig(AppCurrency.dollar);
final result = converter.convert(amount, currency: config);

API Reference #

AmountToWords Class #

Constructors

• AmountToWords(Language language) - Create converter for specific language
• AmountToWords.fromLocale([String? localeCode]) - Auto-detect from locale code
• AmountToWords.fromContext(BuildContext context) - Auto-detect from Flutter context

Methods

• String toWords(num number) - Convert number to words (no currency)
• String convert(num amount, {CurrencyConfig? currency}) - Convert amount with currency
• String integerToWords(int number) - Convert integer only
• bool isValidNumber(num number) - Check if number is in supported range

Properties

• Language language - Current language
• String conjunctionWord - Conjunction word for current language ("و", "and", "ve")

CurrencyConfig Class #

Constructors

• CurrencyConfig({required Map<Language, String> mainUnits, Map<Language, String>? subUnits, int subUnitInMainUnit = 100})

Methods

• String getMainUnit(Language language, {int count = 1}) - Get main unit with pluralization
• String? getSubUnit(Language language, {int count = 1}) - Get sub unit with pluralization
• CurrencyConfig addLanguage(Language language, String mainUnit, [String? subUnit]) - Add new language support

Properties

• bool hasSubUnit - Whether currency supports decimal amounts
• int subUnitInMainUnit - Conversion ratio (default: 100)

Predefined Currencies

• CurrencyConfig.iranianRial
• CurrencyConfig.iranianToman
• CurrencyConfig.usDollar
• CurrencyConfig.euro
• CurrencyConfig.canadianDollar
• CurrencyConfig.turkishLira
• CurrencyConfig.afghanAfghani

Language Enum #

enum Language {
  fa('fa', 'Persian'),
  en('en', 'English'),
  tr('tr', 'Turkish');
}

Methods

• static Language? fromCode(String code) - Get language from code
• String get code - Language code ('fa', 'en', 'tr')
• String get name - Language display name

Pluralization Rules #

English #

• Regular: dollar → dollars, cent → cents
• Y-ending: penny → pennies
• S/SH/CH/X/Z-ending: lira → liras

Persian & Turkish #

• No pluralization for currency units (grammatically correct)

Number Range Support #

• Minimum: 0
• Maximum: 999,999,999,999,999 (quadrillion range)
• Decimal Places: Up to 2 decimal places
• Negative Numbers: Not supported (throws ArgumentError)

Error Handling #

try {
  final result = converter.toWords(-100); // Throws ArgumentError
} catch (e) {
  print('Error: $e');
}

try {
  final result = converter.toWords(1e20); // Out of range
} catch (e) {
  print('Error: $e');
}

⚡ Performance & Comparison #

Performance Metrics #

🏆 Why Choose This Package? #

Testing #

Run tests:

flutter test

The package includes comprehensive tests covering:

• All number ranges and edge cases
• Currency conversion accuracy
• Pluralization rules
• Language detection
• Error conditions
• Performance benchmarks

Examples #

Check the /example directory for complete working examples:

• basic_usage.dart - Simple number conversion
• currency_usage.dart - Currency examples with all supported currencies
• flutter_integration.dart - Complete Flutter app example
• custom_currency.dart - Advanced currency customization

Contributing #

Contributions are welcome! Please read our Contributing Guide for details.

Adding New Languages #

1. Add language to Language enum in language_enum.dart
2. Create new converter class extending ConverterBase
3. Add language support to all predefined currencies
4. Add comprehensive tests
5. Update documentation

Adding New Currencies #

1. Define currency in CurrencyConfig with all supported languages
2. Add to getAllCurrencies() method
3. Add tests in currency_config_test.dart
4. Update documentation

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Changelog #

See CHANGELOG.md for version history and migration guides.

🆘 Support #

• 📧 Issues: GitHub Issues
• 📖 Documentation: API Documentation
• 💬 Discussions: GitHub Discussions
• ⭐ Star: GitHub Repository

🎯 Use Cases #

• Financial Apps: Invoices, receipts, banking applications
• E-commerce: Product pricing, order summaries
• Accounting: Financial reports, expense tracking
• Multilingual Apps: International applications with currency support
• Government: Official documents, tax forms
• Education: Language learning, number systems

🏢 Supported by #

This package is proudly supported by Fida Invoice - The most professional and user-friendly invoice application in Iran.

Fida Invoice is an award-winning invoice application that makes creating professional invoices simple, fast, and hassle-free. With features like:

• 🎨 Custom Branding: Add your logo, corporate colors, and custom headers
• 🔏 Legal Validity: Add stamps and signatures directly from the app
• ✅ Automatic Calculations: Shipping costs, discounts, deposits, and customer debts
• ✏️ Real-time Editing: Quick price, quantity, and calculation changes
• ➕ Custom Invoices: Add or remove rows as needed
• 📁 Smart Storage: Save and retrieve frequently used invoices
• 📤 Professional Export: Image or text output for easy sharing

Download Fida Invoice from Cafe Bazaar and experience the future of invoice management!

Made with ❤️ for the Flutter community