core-written-number

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-number

Usage

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 to false. 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 a string representing the language code (like 'en', 'es', or 'pt') or an i18n configuration object. 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.