harfizer
Version:
> **Convert numbers, dates, and times into words — in 7+ languages, with style.**
188 lines (123 loc) • 5.01 kB
Markdown
# Harfizer — Say Your Numbers, Dates, and Times Out Loud (in Any Language!)
> **Convert numbers, dates, and times into words — in 7+ languages, with style.**
[](https://www.npmjs.com/package/harfizer)
**Harfizer** is a powerful and extensible package for converting numbers, dates, and times into human-readable words — now supporting 7+ languages including [🇮🇷 Persian](./docs/persian.md), [🇫🇷 French](./docs/french.md), [🇯🇵 Japanese](./docs/japanese.md), [🇨🇳 Chinese](./docs/chinese.md), [🇷🇺 Russian](./docs/russian.md), [🇩🇪 German](./docs/german.md), and [🇪🇸 Spanish](./docs/spanish.md).
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:
```bash
npm install harfizer
```
## 🚀 Usage
Import the plugin and the `CoreConverter` from the package:
```ts
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).
```ts
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.
```ts
converter.convertTripleToWords(789);
// Output: "seven hundred eighty-nine"
```
### `convertDateToWords(dateStr: string, calendar?: "jalali" | "gregorian"): string`
Converts a date string to spoken form.
```ts
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.
```ts
converter.convertTimeToWords("09:00");
// Output: "It is nine o'clock"
converter.convertTimeToWords("09:05");
// Output: "It is nine o'clock and five minutes"
```
## 📘 Examples
```ts
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:
```ts
const options = {
customZeroWord: "nil",
customNegativeWord: "negative",
customSeparator: " "
};
converter.convertNumber("-123", options);
// Output: "negative one hundred twenty-three"
```
## 🌍 Other Language Plugins Documentation
- [🇬🇧 English](./README.md)
- [🇮🇷 Persian](./docs/persian.md)
- [🇫🇷 French](./docs/french.md)
- [🇯🇵 Japanese](./docs/japanese.md)
- [🇨🇳 Chinese](./docs/chinese.md)
- [🇷🇺 Russian](./docs/russian.md)
- [🇩🇪 German](./docs/german.md)
- [🇪🇸 Spanish](./docs/spanish.md)
## 📄 License
MIT
### 💬 Have suggestions or want to contribute?
Open an issue or PR on [GitHub](https://github.com/rojcode/harfizer)! Contributions welcome 🌟