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.