i18n-number-parser

Converts numbers written out in words into their numeric value, in English, Dutch, German and Portuguese.

First relied on words-to-numbers and multilingual-number-parser. Added German language support and fixed a number of issues of the original packages.

Installation

npm install i18n-number-parser
# or
pnpm add i18n-number-parser

Usage

import wordsToNumbers, { Languages } from 'i18n-number-parser';

wordsToNumbers('two hundred thirty four');
// 234

wordsToNumbers('I bought twenty-two apples, and thirty pears!');
// 'I bought 22 apples, and 30 pears!'

wordsToNumbers('fünf Millionen vierhundertdreiundzwanzig', { language: Languages['de-de'] });
// 5000423

wordsToNumbers('tweehonderddrieëndertig', { language: Languages['nl-nl'] });
// 233

wordsToNumbers('duzentos e cinquenta e seis', { language: Languages['pt-br'] });
// 256

API

wordsToNumbers(text, options?)

| argument | type | description | | --------- | --------- | -------------------------------------------------- | | text | string | the text to convert | | options | Options | optional, see below. Defaults to {} (en-us). |

Return value:

• a number when the whole text is a single number ('five hundred' → 500)
• a number[] when numbersOnly is set
• otherwise the original text with every number replaced ('I have five apples' → 'I have 5 apples')

Options

| option | type | default | description | | ------------- | ----------- | --------- | ---------------------------------------------------------------------------------------- | | language | Languages | 'en-us' | language of the text | | numbersOnly | boolean | false | return every parsed number as a number[] instead of replacing them in the text | | oneNumber | boolean | false | glue all parsed numbers into one number, useful for years: 'nineteen ninety-eight' → 1998 | | debug | boolean | false | log the parsed regions |

Languages

| language | code | decimal separator words | joiner | | ---------- | --------- | ----------------------- | ------ | | English | en-us | point, dot | and | | Dutch | nl-nl | komma, punt | en | | German | de-de | komma | und | | Portuguese | pt-br | vírgula | e |

Behaviour

• Compound words are supported: twenty-five, fünfundzwanzig, vijfentwintig, duzentos. A written word is only treated as a number when it consists entirely of number words, in-word glue (-, und, en, ën, e) and — for German — a trailing declension (zweiundzwanzigste, fünfter). This keeps ordinary words such as alone, keine, rein or geen out of the parser.
• Ordinals are supported: the twenty-second of may → the 22 of may.
• Decimals work both as spelled out numbers and as digit sequences: five point five hundred twenty one → 5.521 and five point five two one → 5.521.
• Magnitudes are language specific: billion is 10^9 in English but 10^12 in German (Billion).
• Sentence punctuation ends a number, so 'Give me twenty. Two are broken.' becomes 'Give me 20. 2 are broken.'.
• Digits are not parsed; only words are converted.
• The English a and the Dutch een are worth 1 inside a sentence (a hundred → 100), but are left alone when they are the only word of the input.

Development

This repo uses pnpm, vitest for tests and tsup for the build.

pnpm install
pnpm test          # run the suite once
pnpm test:watch    # watch mode
pnpm run typecheck # tsc over src *and* test (vitest itself does not type check)
pnpm run build     # dist/index.js (cjs), dist/index.mjs (esm), dist/index.d.ts
pnpm run size      # size-limit

There is currently no linter. The previous tsdx lint was removed together with tsdx, whose 2020 toolchain no longer works with TypeScript 5 or with a modern dependency tree.