Harfizer — Say Your Numbers, Dates, and Times Out Loud (in Any Language!)

Convert numbers, dates, and times into words — in 7+ languages, with style.

Harfizer is a powerful and extensible package for converting numbers, dates, and times into human-readable words — now supporting 7+ languages including 🇮🇷 Persian, 🇫🇷 French, 🇯🇵 Japanese, 🇨🇳 Chinese, 🇷🇺 Russian, 🇩🇪 German, and 🇪🇸 Spanish.
Built with a plugin-based architecture, Harfizer allows seamless internationalization and high configurability.

If you prefer a language other than English, see the respective documentation above or at the end of this document.

✨ Features

• ✅ Convert numbers (integers, decimals, negatives)
• ✅ Convert Gregorian or Jalali dates
• ✅ Convert time (HH:mm) to natural text
• ✅ Supports 66-digit numbers
• ✅ 7+ language plugins — easily extendable
• ✅ Customizable output with options

💡 Why Harfizer?

• 🌍 Multilingual support (7+ languages and growing)
• 🔢 Handles large numbers (up to 66 digits, decimals, negatives)
• 📅 Date and time conversion with natural phrasing
• 🔌 Plugin-based and highly extensible
• ⚙️ Customizable with ConversionOptions
• ✅ Built with TypeScript — fully typed, safe, and modern

🌐 Supported Languages

| Flag | Language | Plugin | |------|----------|--------| | 🇬🇧 | English | ✅ EnglishLanguagePlugin | | 🇮🇷 | Persian | ✅ PersianLanguagePlugin | | 🇫🇷 | French | ✅ FrenchLanguagePlugin | | 🇯🇵 | Japanese | ✅ JapaneseLanguagePlugin | | 🇨🇳 | Chinese | ✅ ChineseLanguagePlugin | | 🇷🇺 | Russian | ✅ RussianLanguagePlugin | | 🇩🇪 | German | ✅ GermanLanguagePlugin | | 🇪🇸 | Spanish | ✅ SpanishLanguagePlugin |

More languages coming soon...

📦 Installation

Install Harfizer via npm:

npm install harfizer

🚀 Usage

Import the plugin and the CoreConverter from the package:

import { CoreConverter, EnglishLanguagePlugin } from 'harfizer';

const englishPlugin = new EnglishLanguagePlugin();
const converter = new CoreConverter(englishPlugin);

🧠 Methods

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

Converts an integer, decimal, or negative number to words (digit-by-digit for decimals).

converter.convertNumber("123");
// Output: "one hundred twenty-three"

converter.convertNumber("-456.78");
// Output: "minus four hundred fifty-six point seven eight"

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

Converts a number with up to 3 digits.

converter.convertTripleToWords(789);
// Output: "seven hundred eighty-nine"

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

Converts a date string to spoken form.

converter.convertDateToWords("2023/04/05");
// Output: "April 5, two thousand twenty-three"

convertTimeToWords(timeStr: string): string

Converts a time string in "HH:mm" format to spoken form.

converter.convertTimeToWords("09:00");
// Output: "It is nine o'clock"

converter.convertTimeToWords("09:05");
// Output: "It is nine o'clock and five minutes"

📘 Examples

import { CoreConverter, EnglishLanguagePlugin } from 'harfizer';

const plugin = new EnglishLanguagePlugin();
const converter = new CoreConverter(plugin);

console.log(converter.convertNumber("123")); 
console.log(converter.convertDateToWords("2023/04/05")); 
console.log(converter.convertTimeToWords("09:05"));

⚙️ Additional Options

Customize your number output:

const options = {
  customZeroWord: "nil",
  customNegativeWord: "negative",
  customSeparator: " "
};

converter.convertNumber("-123", options);
// Output: "negative one hundred twenty-three"

🌍 Other Language Plugins Documentation

• 🇬🇧 English
• 🇮🇷 Persian
• 🇫🇷 French
• 🇯🇵 Japanese
• 🇨🇳 Chinese
• 🇷🇺 Russian
• 🇩🇪 German
• 🇪🇸 Spanish

📄 License

MIT

💬 Have suggestions or want to contribute?

Open an issue or PR on GitHub! Contributions welcome 🌟