core-written-number v0.1.1
core-written-number
Convert numbers to their written form.
The core-written-number library allows converting numeric values into their word equivalents, supporting multiple languages. Ideal for applications that require number-to-word transformations, such as financial applications, educational tools, or document generation.
Features
- Supports multiple languages with unique grammar rules for each.
- Provides detailed customization options to fit different linguistic structures.
- Developed with TypeScript for better type safety and integration.
Installation
With npm:
npm install --save core-written-numberUsage
import writtenNumber from 'core-written-number';
// Default usage in English
console.log(writtenNumber(1234)); // => 'one thousand two hundred and thirty-four'
// Change default language to Spanish
writtenNumber.defaults.lang = 'es';
console.log(writtenNumber(4758)); // => 'cuatro mil setecientos cincuenta y ocho'
// Specifying a language using options
console.log(writtenNumber(1234, { lang: 'pt' })); // => 'mil duzentos e trinta e quatro'
console.log(writtenNumber(1234, { lang: 'en' })); // => 'one thousand two hundred and thirty-four'
console.log(writtenNumber(2580000000, { lang: 'pt' })); // => 'dois bilhões quinhentos e oitenta milhões'Options
noAnd- Defaults tofalse. Determines whether to use the separator "and" for English and other languages where applicable. This separator is internationalized based on the chosen language.lang- Could be astringrepresenting the language code (like'en','es', or'pt') or an i18n configurationobject. Defaults to'en'. Determines which language to use.
Supported Languages
| Language | lang |
|---|---|
| English | en |
| Portuguese (BR) | pt |
| Spanish | es |
Adding New Languages
If your language is not yet supported, you can configure your own! Each language has its own unique grammar exceptions and rules. To add support for a new language, create a new JSON file in the i18n folder and follow the parameters described below.
Language Parameters
Below are the parameters used in the current supported languages:
| Parameter | Type | Description | Examples |
|---|---|---|---|
useLongScale | boolean | Determines if the language uses the long or short scale. | Affects the meaning of words like billion and trillion. |
baseSeparator | string | Separates the base cardinal numbers. | e.g., twenty-eight or in Spanish " y " |
unitSeparator | string | Separates the unit from the base cardinal numbers. | e.g., one thousand two hundred **and** thirty-four |
allSeparator | string | Optional: Separates all cardinals, not just the last one. | Arabic example: ألف ومائة وخمسة وعشرون |
base | Object | Defines base cardinal numbers that have unique names. | |
alternativeBase | Object | Defines alternative versions of base cardinal numbers, specific to units or grammatical rules. | "alternativeBase": {"feminine": {"1": "una", "2": "dos"}} |
units | Array | Defines a list of number units (string or Object). Supports singular, dual, and plural units. | |
unitExceptions | Object | Grammar exceptions affecting the base cardinal numbers combined with units. | Example: "1232000": "un millón doscientos mil" |
Here’s the corrected section of the README that only includes examples for English, Portuguese (pt), and Spanish (es):
Unit Parameters
A unit can be:
- A simple string, e.g.,
"hundred" - An object with specific parameters:
| Unit Parameter | Description | Example Languages |
|---|---|---|
singular | Used for one element. | All (en, es, pt) |
plural | Used for two or more elements (or 3 or more, depending on the language). | All (en, es, pt) |
useBaseInstead | Uses the base cardinal number instead of the unit in certain cases. | es, pt |
useBaseException | Specifies which units should not use the base cardinal number. | es, pt |
avoidPrefixException | Units not using the base cardinal number as a prefix for specific units or numbers. | pt |
useSingularEnding | Uses the singular form for numbers ending with 1. | pt, es |
restrictedPlural | Specifies when to use the plural form in a restricted range (e.g., in specific grammatical cases). | pt, es |
TypeScript Support
This library is fully written in TypeScript, ensuring better type safety and developer experience. You can import and use it in TypeScript projects seamlessly:
import writtenNumber from 'core-written-number';
const result: string = writtenNumber(1234, { lang: 'pt' });
console.log(result); // => 'mil duzentos e trinta e quatro'Contributing
We welcome contributions! If you want to add a new language or improve an existing feature, feel free to submit a pull request. Before submitting, make sure to write and run tests to verify your changes.
Versioning
If you have write access and want to bump the version, run mversion [major|minor|patch] -m. This will bump both bower.json and package.json.
License
This library is licensed under the MIT License for Core Platform. For more information, please refer to the LICENSE file.