🔢 Number to Words Converter

A professional PyQt5 desktop app that converts numbers into words in Persian, English, and Finglish

Turn any number up to 999,000,000,000 into clean, accurate words — in three languages.

🇮🇷 مطالعه به فارسی · 🐛 Report a Bug · ✨ Request a Feature

---

📖 About The Project

Number to Words Converter is a professional desktop application written in Python with a polished PyQt5 graphical user interface. It accurately converts numeric values up to 999 billion into their fully spelled-out word form across three languages:

• 🇮🇷 Persian (فارسی) — e.g. 1234 → «یک هزار و دویست و سی و چهار»
• 🇬🇧 English — e.g. 1234 → one thousand, two hundred and thirty-four
• 🌐 Finglish (فینگلیش) — Persian pronounced with Latin letters — e.g. 1234 → yek hezar o devist o si o chahar

This tool is engineered for real-world use cases where number-to-word conversion is essential — making it a perfect fit for accounting software, invoice generators, financial dashboards, banking systems, and educational applications.

💼 Built with production-grade code quality, a clean modular architecture, and a modern minimal UI — ready to drop into any commercial or personal project.

---

✨ Key Features

• 🔢 Huge Range — Supports numbers from 0 to 999,000,000,000 (nine hundred ninety-nine billion)
• 🌐 Tri-Lingual Output — Persian, English, and Finglish in one place
• 🎨 Modern UI — Clean, flat design with a custom color palette (#0ea480 brand accent)
• 🧩 Modular Code — Clean separation of logic and UI, easy to extend with new languages
• ↔️ Full RTL Support — Native right-to-left layout for Persian users
• 🎯 Radio-Based Language Selection — Switch between languages with a single click
• 🛡️ Smart Input Validation — Graceful handling of invalid input or oversized numbers
• 💻 Cross-Platform — Runs natively on Windows, macOS, and Linux
• 💼 Production-Ready — Designed for use in accounting, invoicing & fintech apps
• 🆓 Open Source — Free for personal, educational & non-commercial use

---

🎬 Live Examples

Input	Persian (فارسی)	English	Finglish
0	صفر	zero	sefr
12	دوازده	twelve	davazdah
1,234	یک هزار و دویست و سی و چهار	one thousand, two hundred and thirty-four	yek hezar o devist o si o chahar
1,000,000	یک میلیون	one million	yek milyoon
999,999,999,999	نهصد و نود و نه میلیارد و ...	nine hundred ninety-nine billion ...	nohsad o navad o noh milyard o ...

---

🛠️ Tech Stack

Technology	Purpose
🐍 Python 3.8+	Core programming language
🎨 PyQt5	Cross-platform desktop GUI framework
🔤 inflect	English number-to-word conversion engine
🧠 Custom Algorithm	Native Persian & Finglish conversion logic

---

🚀 Getting Started

📋 Prerequisites

Make sure you have Python 3.8 or higher installed:

python --version

📥 Installation

1. Clone the repository

   git clone https://github.com/samafzalidev/number-to-words-converter.git
   cd number-to-words-converter

2. (Recommended) Create a virtual environment

   python -m venv venv
   # On Windows
   venv\Scripts\activate
   # On macOS / Linux
   source venv/bin/activate

3. Install the required dependencies

   pip install PyQt5 inflect

   Or, if a requirements.txt is provided:

   pip install -r requirements.txt

4. Run the application

   python number_to_words_converter.py

---

🎮 Usage

1. Launch the app — a window titled «تبدیل عدد به حروف» will open.
2. Type or paste any integer up to 999,000,000,000 in the input field.
3. Select the output language — Persian, English, or Finglish.
4. Click the تبدیل (Convert) button.
5. The result instantly appears in the result box. ✨

💡 Tip: This app runs entirely offline — no internet connection required!

---

📁 Project Structure

number-to-words-converter/
├── 📄 number_to_words_converter.py    # Main application source code
├── 📄 README.md                       # English documentation (this file)
├── 📄 README.fa.md                    # Persian documentation
├── 📄 LICENSE                         # Custom non-commercial license

---

🗺️ Roadmap

Planned features for upcoming versions:

• 🔢 Decimal support (e.g. 1234.56 → «یک هزار و دویست و سی و چهار ممیز پنجاه و شش»)
• 💵 Currency mode (Rial / Toman / USD / EUR)
• 🌍 More languages (Arabic, French, German, Spanish)
• 📋 Copy-to-clipboard button for the result
• 🌙 Dark mode toggle
• 💾 Conversion history with export to CSV
• ⌨️ Keyboard shortcuts (Enter to convert, Esc to clear)
• 📦 Standalone Windows .exe build via PyInstaller
• 🐍 PyPI package for use as a Python library
• 🔌 REST API mode for integration into web apps

Have an idea? Open an issue to suggest a feature!

---

🤝 Contributing

Contributions, issues, and feature requests are warmly welcome! 🎉

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

⭐ If you like this project, please consider giving it a star — it really helps!

---

📜 License

This project is distributed under a Custom Non-Commercial License:

Copyright © 2025 Sam Afzali

Permission is granted to use, copy, and distribute this software for personal, educational, and non-commercial purposes, provided the original author is credited.

Commercial use, modification, resale, or claiming authorship is strictly prohibited without explicit written permission.

The software is provided "AS IS", without warranty of any kind.

📩 For commercial licensing or custom permissions, please contact the author (see below).

See the LICENSE file for full details.

---

👨‍💻 Author

Sam Afzali — Full-Stack Developer

🌐 Website: samafzali.ir 📧 Email: samafzalidev@gmail.com · info@samafzali.ir 🐙 GitHub: @samafzalidev

Designed & developed with ❤️ in Iran

💼 Available for hire — open to freelance projects, custom development, and commercial licensing.

---

🙏 Acknowledgments

• Qt / PyQt5 — the cross-platform GUI framework
• inflect — the English natural-language utility library
• All open-source contributors and the Python community 🐍❤️

---

If this project was helpful, don't forget to leave a ⭐ on GitHub!

Made with ❤️ by Sam Afzali