full-numbers

full-numbers

A nice JS package to convert numbers to words.

Multilanguage and currency support

Usage

First things first - install the package using npm or yarn:

# using npm
npm i full-numbers

# using yarn
yarn add full-numbers

After that, import the helper wherever you want to use it:

// es-modules
import fullNumbers from 'full-numbers';

// commonjs
const fullNumbers = require('full-numbers');

Then, you'll be able to use it:

const words = fullNumbers(1234); // "one thousand, two hundred thirty-four"

// or

const words = fullNumbers({
  value: 1234,
  lang: 'pt-BR',
}); // "um mil, duzentos e trinta e quatro"

To use with currency support:

// "simple" values
const words = fullNumbers({
  value: 1234,
  lang: 'pt-BR',
  currency: {
    name: {
      singular: 'real',
      plural: 'reais'
    },
    decimals: {
      singular: 'centavo',
      plural: 'centavos'
    }
  }
}); // "um mil, duzentos e trinta e quatro reais"

// with decimals
const words = fullNumbers({
  value: 1234.5,
  lang: 'pt-BR',
  currency: {
    name: {
      singular: 'real',
      plural: 'reais'
    },
    decimals: {
      singular: 'centavo',
      plural: 'centavos'
    }
  }
}); // "um mil, duzentos e trinta e quatro reais e cinquenta centavos"

Avaliable Options

Name	Type	Description	Example
value	number	The value	123
lang	string	The output language	pt-BR
currency	object	The output currency	See below

The currency object should look like this:

{
  name: {
    singular: 'real',
    plural: 'reais'
  },
  decimals: {
    singular: 'centavo',
    plural: 'centavos'
  }
}

The singular/plural keys are important to avoid mismatch of grammar rules.

Developing

First, fork the project. After it, install the dependencies (preferably using npm - since the project is using it) and do the work.

Also, take a look at the contributing guide!

Adding a new language

To add a new language, follow the steps below:

• Create a new .json file within src/languages directory. The name of this file should be a valid language code (i.e. en, pt-BR...)
• The file must have the following keys:
  • PUNCTUATION: an object of punctuations used between dozens, hundreds and decimals - if the language doesn't use them, leave the values blank;
  • LESS_THAN_TWENTY: an array of numbers' names between 0 and 19.
  • DOZENS: an array of dozens' names bewteen 0 and 90;
  • HUNDREDS: an object with the singular/plural names of hundreds between 100 and 900 - if the names are equal, leave the two keys with the same value;
  • SHORT_SCALE_NAME: an object with the short scale name from 100 (hundred) to 1000000000000000 (quadrillion).

You can follow the en.json file as an example to follow, and see the supported languages here.

License

Licensed under the MIT.