number-2-letters

Convert numbers to words - their written form.

This module extends the written-number's module. He adds it the conversion of a number in Belgian French by respecting the Belgian's grammatical rules.

Install with npm

npm i --save number-2-letters

Install with bower

bower install number-2-letters

Usage

var numberToLetters = require('number-2-letters');
numberToLetters(1234); // => 'one thousand two hundred and thirty-four'

Options

• noAnd - Defaults to false. Determines whether to use a separator. The separator is internationalized.
• lang - Could be string or object. Defaults to 'en'. Determines which language to use. An i18n configuration object may be passed to support external language definitions.

Internationalization

Currently supported languages are:

• English lang = "en"
• Portuguese lang = "pt"
• Spanish lang = "es"
• French lang = "fr"
• Esperanto lang = "eo"
• Vietnamese lang = "vi"
• Belgium lang = "bl"

Spanish Example

var numberToLetters = require('number-2-letters');
numberToLetters(1234, { lang: 'es' }); // => 'mil doscientos treinta y cuatro'

var numberToLetters = require('number-2-letters');
numberToLetters.defaults.lang = 'es';
numberToLetters(4758); // => 'cuatro mil setecientos cincuenta y ocho'

Portuguese Example

var numberToLetters = require('number-2-letters');
numberToLetters(1234, { lang: 'pt' }); // => 'mil duzentos e trinta e quatro'

French Example

var numberToLetters = require('number-2-letters');
numberToLetters(1234, { lang: 'fr' }); // => 'mille deux cent trente-quatre'

Esperanto Example

var numberToLetters = require('number-2-letters');
numberToLetters(1234, { lang: 'eo' }); // => 'mil ducent tridek kvar'

Vietnamese Example

var numberToLetters = require('number-2-letters');
numberToLetters(1234, { lang: 'vi' }); // => 'một ngàn hai trăm và ba mươi bốn'

Belgium Example

var numberToLetters = require('number-2-letters');
numberToLetters(90, { lang: 'bl' }); // => 'nonante'

Options

Property | Value -------------- | ------------- noAnd | false lang | 'en'

Configure your own language

Each language has it's own unique grammar exceptions. You can create your own language.json file in the folder "i18n" and give writtenNumber support for it. I don't think the current scheme and logic cover all the cases, but may be cover some.

useLongScale:

'Boolean' that indicates if it use long or short scale. This differs the meaning of the words billion, trillion and so on.

baseSeparator:

'String' that separates the base cardinal numbers. Example: 29 -> twenty-eight. Spanish uses the conector " y ".

unitSeparator:

'String' that separates the units from the last base cardinal numbers. Example: 1234 -> one thousand two hundred and thirty-four

base:

Base cardinals numbers. Numbers that have unique names and are used to build others.

units:

Number units. It can be:

• String

• Object normal flow. Give support to singular and plural units. English does not need this, but spanish does.

{
  "singular": "millón",
  "plural": "millones"
}

• Object with useBaseInstead exception. In some languages like spanish, specific units like "ciento", use the base cardinal number instead.

With useBaseException you can also specify with which unit (1 to 9) you don't want use the base cardinal instead and use the regular behaviour.

{
  "singular": "ciento",
  "useBaseInstead": true,
  "useBaseException": [1]
}

• Object with avoidPrefixException exception.

In some languages like spanish, specific units like "mil" does not use the base cardinal number prefix for unit 1.

{
  "singular": "mil",
  "avoidPrefixException": [1]
}

• Object with avoidInNumberPlural exception.

In some languages like french, specific units like "cent" does not use the plural form inside of numbers wioth trailing numbers other than 0, for example "deux cents" and "deux cent trois".

{
  "singular": "cent",
  "plural": "cents",
  "avoidInNumberPlural": true
}

unitExceptions:

Sometimes grammar exceptions affect the base cardinal joined to the unit. You can set specific exceptions to any base cardinal number.

Spanish example:

Without Exception (Wrong): 1232000 -> **uno** millón doscientos treinta y dos mil

With Exception: 1232000 -> **un** millón doscientos treinta y dos mil

English configuration example

{
  "useLongScale": false,
  "baseSeparator": "-",
  "unitSeparator": "and ",
  "base": {
    "0": "zero",
    "1": "one",
    "2": "two",
    "3": "three",
    ...
    "90": "ninety"
  },
  "units" : [
    "hundred",
    "thousand",
    "million",
    "billion",
    "trillion",
    ...
    "quindecillion"
  ],
  "unitExceptions": []
}

Spanish configuration example

{
  "useLongScale": true,
  "baseSeparator": " y ",
  "unitSeparator": "",
  "base": {
    "0": "cero",
    "1": "uno",
    "2": "dos",
    "3": "tres",
    ...
    "1000": "mil"
  },
  "unitExceptions": {
    "1": "un"
  },
  "units" : [
    {
      "singular": "ciento",
      "useBaseInstead": true,
      "useBaseException": [1]
    },
    {
      "singular": "mil",
      "avoidPrefixException": [1]
    },
    {
      "singular": "millón",
      "plural": "millones"
    },
    ...
  ]
}

Contributing

Do your changes and submit a PR. If you've write access and want to bump the version, run mversion [major|minor|patch] -m. That'll bump both bower.json and package.json.

License

This code is licensed under the MIT license for Pedro Tacla Yamada. For more information, please refer to the LICENSE file. This library is available under the [MIT] (https://opensource.org/licenses/mit-license.php) license.