n2words

Numbers to words. 70+ languages. Zero dependencies.

Why n2words?

• Pure Functions — Each language exports standalone functions. No classes, no configuration, no side effects.
• Tree-Shakeable — Import only what you need. Unused exports are eliminated by modern bundlers.
• Tiny Bundles — ~2 KB gzipped per language (with all forms). No bloat.
• Multiple Forms — Cardinal ("forty-two"), ordinal ("forty-second"), and currency ("forty-two dollars")
• 70+ Languages — European, Asian, Middle Eastern, African, and regional variants
• Zero Dependencies — Works everywhere: Node.js, browsers, Deno, Bun
• BigInt Support — Accepts bigint (and numeric-string) input, so large values keep full precision
• Type-Safe — Full TypeScript support with generated .d.ts declarations

Quick Start

npm install n2words

import { toCardinal } from 'n2words/en-US'
import { toCardinal as es } from 'n2words/es-ES'

toCardinal(42)   // 'forty-two'
es(42)           // 'cuarenta y dos'

Forms

n2words converts numbers to words in multiple forms:

Form	Function	Example
Cardinal	toCardinal(42)	"forty-two"
Ordinal	toOrdinal(42)	"forty-second"
Currency	toCurrency(42.50)	"forty-two dollars and fifty cents"

import { toCardinal, toOrdinal, toCurrency } from 'n2words/en-US'

toCardinal(1234)      // 'one thousand two hundred thirty-four'
toOrdinal(1234)       // 'one thousand two hundred thirty-fourth'
toCurrency(1234.56)   // 'one thousand two hundred thirty-four dollars and fifty-six cents'

Each language implements one or more of these forms — see LANGUAGES.md for per-language coverage.

Range: each form spells values up to the largest scale word it knows, then throws a RangeError rather than inventing vocabulary — and the ceiling varies by language and form (e.g. es-ES cardinals reach 10^30 − 1, ordinals only 10^9 − 1). Cardinal and currency accept negatives and decimals; ordinal is positive integers only.

Usage

ESM (Node.js, modern bundlers):

import { toCardinal } from 'n2words/en-US'            // Single form
import { toCardinal, toOrdinal } from 'n2words/en-US' // Multiple forms
import { toCardinal as fr } from 'n2words/fr-FR'       // Aliased import

Browser (CDN):

<!-- ESM (recommended) -->
<script type="module">
  import { toCardinal } from 'https://cdn.jsdelivr.net/npm/n2words/dist/en-US.js'
  console.log(toCardinal(42))  // 'forty-two'
</script>

<!-- UMD (legacy script tags) -->
<script src="https://cdn.jsdelivr.net/npm/n2words/dist/en-US.umd.js"></script>
<script>
  n2words.enUS(42)              // 'forty-two'
  n2words.ordinal.enUS(42)      // 'forty-second'
  n2words.currency.enUS(42.50)  // 'forty-two dollars and fifty cents'
</script>

dist/{code}.js carries all three forms. A page that needs only one can fetch just that form from dist/{code}/{form}.js — cardinal, ordinal or currency:

<script type="module">
  import { toCurrency } from 'https://cdn.jsdelivr.net/npm/n2words/dist/en-US/currency.js'
  console.log(toCurrency(42.50))  // 'forty-two dollars and fifty cents'
</script>

Roughly half the bytes, since the other two forms and everything only they reach are never in the file:

en-US	bytes
dist/en-US.js (all three forms)	7,778
dist/en-US/cardinal.js	4,293
dist/en-US/ordinal.js	3,815
dist/en-US/currency.js	3,827

This is for CDN consumers only. If you install from npm and use a bundler, import { toCurrency } from 'n2words/en-US' already drops the forms you don't import — the package is sideEffects-free and each form is an independent export, so there is nothing to opt into.

See LANGUAGES.md for all language codes and available forms.

Supported Languages

See LANGUAGES.md for the complete list with codes and options.

Highlights: Arabic, Chinese (Simplified/Traditional), English, French, German, Hindi, Japanese, Korean, Portuguese, Russian, Spanish, and many more.

Compatibility

• Node.js: 22+
• Browsers: Chrome 67+, Firefox 68+, Safari 14+, Edge 79+ — any browser with BigInt support
• Runtimes: Deno, Bun, Cloudflare Workers

Requires BigInt support (cannot be polyfilled).

Performance

n2words is optimized for both size and speed:

• ~2 KB gzipped per language (includes all forms)
• Individual language imports enable tree-shaking
• No runtime dependencies
• BigInt modulo operations (no string manipulation)
• Pure functions with no shared state
• Minimal memory allocation per conversion

Run npm run bench to measure on your hardware.

Contributing

We welcome contributions! Add a new language or improve existing ones:

npm run lang:add -- <code>   # Scaffold a new language (BCP 47 code)
npm test                     # Run full test suite

Also welcome: bug reports, feature requests, and documentation improvements.

• Contributing Guide — How to contribute and add languages
• Code of Conduct — Community standards

License

MIT © Wael TELLAT, Tyler Vigario & contributors