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.