Skip to content

Commit 2832648

Browse files
rojcoderojcode
committed
update README.md
1 parent 0e4bb99 commit 2832648

1 file changed

Lines changed: 102 additions & 95 deletions

File tree

‎README.md‎

Lines changed: 102 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,180 +1,187 @@
11

22

3+
34
# Harfizer — Say Your Numbers, Dates, and Times Out Loud (in Any Language!)
45

5-
**Harfizer** is a powerful package for converting numbers, dates, and times into words. It supports multiple 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). By using language-specific plugins, Harfizer allows you to easily convert numeric and temporal values into their textual representations.
6-
If you prefer a language other than English, please check the respective documentation by clicking on the links provided above or at the end of this document.
6+
> **Convert numbers, dates, and times into words — in 7+ languages, with style.**
7+
8+
[![npm version](https://img.shields.io/npm/v/harfizer)](https://www.npmjs.com/package/harfizer)
9+
![Languages](https://img.shields.io/badge/Languages-7+-blueviolet)
10+
![TypeScript](https://img.shields.io/badge/Made%20with-TypeScript-3178c6)
11+
![License](https://img.shields.io/npm/l/harfizer)
12+
![npm](https://img.shields.io/npm/dt/harfizer)
13+
14+
**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).
15+
Built with a plugin-based architecture, Harfizer allows seamless internationalization and high configurability.
16+
17+
If you prefer a language other than English, see the respective documentation above or at the end of this document.
18+
19+
---
720

21+
## ✨ Features
22+
23+
- ✅ Convert numbers (integers, decimals, negatives)
24+
- ✅ Convert Gregorian or Jalali dates
25+
- ✅ Convert time (HH:mm) to natural text
26+
- ✅ Supports 66-digit numbers
27+
- ✅ 7+ language plugins — easily extendable
28+
- ✅ Customizable output with options
29+
30+
## 💡 Why Harfizer?
31+
32+
- 🌍 **Multilingual** support (7+ languages and growing)
33+
- 🔢 **Handles large numbers** (up to 66 digits, decimals, negatives)
34+
- 📅 **Date and time conversion** with natural phrasing
35+
- 🔌 **Plugin-based** and highly extensible
36+
- ⚙️ **Customizable** with `ConversionOptions`
37+
- ✅ Built with **TypeScript** — fully typed, safe, and modern
38+
39+
---
840

9-
## Table of Contents
10-
- [Harfizer — Say Your Numbers, Dates, and Times Out Loud (in Any Language!)](#harfizer--say-your-numbers-dates-and-times-out-loud-in-any-language)
11-
- [Table of Contents](#table-of-contents)
12-
- [Installation](#installation)
13-
- [Usage](#usage)
14-
- [Methods](#methods)
15-
- [`convertNumber(input: InputNumber, options?: ConversionOptions): string`](#convertnumberinput-inputnumber-options-conversionoptions-string)
16-
- [`convertTripleToWords(num: InputNumber, lexicon?: any, _separator?: string): string`](#converttripletowordsnum-inputnumber-lexicon-any-_separator-string-string)
17-
- [`convertDateToWords(dateStr: string, calendar?: "jalali" | "gregorian"): string`](#convertdatetowordsdatestr-string-calendar-jalali--gregorian-string)
18-
- [`convertTimeToWords(timeStr: string): string`](#converttimetowordstimestr-string-string)
19-
- [Examples](#examples)
20-
- [Additional Options](#additional-options)
21-
- [Other Language Plugins Documentation](#other-language-plugins-documentation)
22-
- [License](#license)
41+
## 🌐 Supported Languages
2342

24-
## Installation
43+
| Flag | Language | Plugin |
44+
|------|----------|--------|
45+
| 🇬🇧 | English | ✅ `EnglishLanguagePlugin` |
46+
| 🇮🇷 | Persian | ✅ `PersianLanguagePlugin` |
47+
| 🇫🇷 | French | ✅ `FrenchLanguagePlugin` |
48+
| 🇯🇵 | Japanese | ✅ `JapaneseLanguagePlugin` |
49+
| 🇨🇳 | Chinese | ✅ `ChineseLanguagePlugin` |
50+
| 🇷🇺 | Russian | ✅ `RussianLanguagePlugin` |
51+
| 🇩🇪 | German | ✅ `GermanLanguagePlugin` |
52+
| 🇪🇸 | Spanish | ✅ `SpanishLanguagePlugin` |
53+
54+
> More languages coming soon...
55+
56+
---
57+
58+
## 📦 Installation
2559

2660
Install Harfizer via npm:
2761

2862
```bash
2963
npm install harfizer
3064
```
3165

32-
## Usage
66+
---
67+
68+
## 🚀 Usage
3369

3470
Import the plugin and the `CoreConverter` from the package:
3571

36-
```typescript
72+
```ts
3773
import { CoreConverter, EnglishLanguagePlugin } from 'harfizer';
3874

3975
const englishPlugin = new EnglishLanguagePlugin();
4076
const converter = new CoreConverter(englishPlugin);
4177
```
4278

43-
## Methods
44-
45-
### `convertNumber(input: InputNumber, options?: ConversionOptions): string`
46-
Converts a given number (integer or decimal, possibly negative) into its English textual form. It handles the fractional part digit-by-digit using the word "point".
79+
---
4780

48-
**Parameters:**
49-
- **input:** A number, numeric string, or bigint.
50-
- **options (optional):** An object to customize conversion:
51-
- `customZeroWord` – overrides the default word for zero.
52-
- `customNegativeWord` – overrides the default negative word.
53-
- `customSeparator` – overrides the default token separator.
81+
## 🧠 Methods
5482

55-
**Returns:**
56-
A string representing the number in words.
83+
### `convertNumber(input: InputNumber, options?: ConversionOptions): string`
5784

58-
**Example:**
85+
Converts an integer, decimal, or negative number to words (digit-by-digit for decimals).
5986

60-
```typescript
61-
converter.convertNumber("123");
87+
```ts
88+
converter.convertNumber("123");
6289
// Output: "one hundred twenty-three"
6390

64-
converter.convertNumber("-456.78");
91+
converter.convertNumber("-456.78");
6592
// Output: "minus four hundred fifty-six point seven eight"
6693
```
6794

6895
---
6996

7097
### `convertTripleToWords(num: InputNumber, lexicon?: any, _separator?: string): string`
71-
Converts a three-digit (or fewer) number into its English textual representation.
7298

73-
**Parameters:**
74-
- **num:** A numeric value (up to 3 digits).
99+
Converts a number with up to 3 digits.
75100

76-
**Returns:**
77-
A string representing the three-digit number (e.g., "four hundred fifty-six").
78-
79-
**Example:**
80-
81-
```typescript
82-
converter.convertTripleToWords(789);
101+
```ts
102+
converter.convertTripleToWords(789);
83103
// Output: "seven hundred eighty-nine"
84104
```
85105

86106
---
87107

88108
### `convertDateToWords(dateStr: string, calendar?: "jalali" | "gregorian"): string`
89-
Converts a Gregorian date string (formatted as "YYYY/MM/DD" or "YYYY-MM-DD") into its English textual representation in the format "Month Day, Year".
90-
91-
**Parameters:**
92-
- **dateStr:** The date string.
93-
- **calendar (optional):** For English, use "gregorian" (default is "gregorian").
94109

95-
**Returns:**
96-
A string representing the date in words.
110+
Converts a date string to spoken form.
97111

98-
**Example:**
99-
100-
```typescript
101-
converter.convertDateToWords("2023/04/05");
112+
```ts
113+
converter.convertDateToWords("2023/04/05");
102114
// Output: "April 5, two thousand twenty-three"
103115
```
104116

105117
---
106118

107119
### `convertTimeToWords(timeStr: string): string`
108-
Converts a time string in "HH:mm" format into its English textual representation.
109-
If minutes are zero, returns "It is <hour> o'clock"; otherwise, returns "It is <hour> o'clock and <minute> minutes".
110-
111-
**Parameters:**
112-
- **timeStr:** A time string in "HH:mm" format.
113-
114-
**Returns:**
115-
A string representing the time in words.
116120

117-
**Example:**
121+
Converts a time string in "HH:mm" format to spoken form.
118122

119-
```typescript
120-
converter.convertTimeToWords("09:00");
123+
```ts
124+
converter.convertTimeToWords("09:00");
121125
// Output: "It is nine o'clock"
122126

123-
converter.convertTimeToWords("09:05");
127+
converter.convertTimeToWords("09:05");
124128
// Output: "It is nine o'clock and five minutes"
125129
```
126130

127-
## Examples
131+
---
128132

129-
Here is an example of using the `EnglishLanguagePlugin` with `CoreConverter`:
133+
## 📘 Examples
130134

131-
```typescript
135+
```ts
132136
import { CoreConverter, EnglishLanguagePlugin } from 'harfizer';
133137

134-
const englishPlugin = new EnglishLanguagePlugin();
135-
const converter = new CoreConverter(englishPlugin);
138+
const plugin = new EnglishLanguagePlugin();
139+
const converter = new CoreConverter(plugin);
136140

137141
console.log(converter.convertNumber("123"));
138-
// Output: "one hundred twenty-three"
139-
140142
console.log(converter.convertDateToWords("2023/04/05"));
141-
// Output: "April 5, two thousand twenty-three"
142-
143-
console.log(converter.convertTimeToWords("09:05"));
144-
// Output: "It is nine o'clock and five minutes"
143+
console.log(converter.convertTimeToWords("09:05"));
145144
```
146145

147-
## Additional Options
146+
---
147+
148+
## ⚙️ Additional Options
148149

149-
The `convertNumber` method accepts an optional `ConversionOptions` object for customizing conversion:
150+
Customize your number output:
150151

151-
```typescript
152+
```ts
152153
const options = {
153154
customZeroWord: "nil",
154155
customNegativeWord: "negative",
155156
customSeparator: " "
156157
};
157158

158-
console.log(converter.convertNumber("-123", options));
159+
converter.convertNumber("-123", options);
159160
// Output: "negative one hundred twenty-three"
160161
```
161162

162-
## Other Language Plugins Documentation
163+
---
164+
165+
## 🌍 Other Language Plugins Documentation
163166

164-
For documentation on other language plugins, please refer to the following files:
167+
- [🇬🇧 English](./README.md)
168+
- [🇮🇷 Persian](./docs/persian.md)
169+
- [🇫🇷 French](./docs/french.md)
170+
- [🇯🇵 Japanese](./docs/japanese.md)
171+
- [🇨🇳 Chinese](./docs/chinese.md)
172+
- [🇷🇺 Russian](./docs/russian.md)
173+
- [🇩🇪 German](./docs/german.md)
174+
- [🇪🇸 Spanish](./docs/spanish.md)
165175

166-
- [🇬🇧 EnglishLanguagePlugin Documentation](./README.md)
167-
- [🇮🇷 PersianLanguagePlugin Documentation](./docs/persian.md)
168-
- [🇫🇷 FrenchLanguagePlugin Documentation](./docs/french.md)
169-
- [🇯🇵 JapaneseLanguagePlugin Documentation](./docs/japanese.md)
170-
- [🇨🇳 ChineseLanguagePlugin Documentation](./docs/chinese.md)
171-
- [🇷🇺 RussianLanguagePlugin Documentation](./docs/russian.md)
172-
- [🇩🇪 GermanLanguagePlugin Documentation](./docs/german.md)
173-
- [🇪🇸 SpanishLanguagePlugin Documentation](./docs/spanish.md)
176+
---
174177

178+
## 📄 License
175179

180+
MIT
181+
182+
---
176183

177-
## License
184+
### 💬 Have suggestions or want to contribute?
178185

179-
This package is licensed under the MIT License.
186+
Open an issue or PR on [GitHub](https://github.com/rojcode/harfizer)! Contributions welcome 🌟
180187

0 commit comments

Comments
 (0)