n2words

Convert numbers to words in 52 languages with zero dependencies.

Why n2words?

• 52 Languages — European, Asian, Middle Eastern, and regional variants
• Zero Dependencies — Pure JavaScript, works everywhere (Node.js, browsers, bundlers)
• Type-Safe — Full TypeScript support with generated .d.ts declarations
• BigInt Support — Handle arbitrarily large numbers without precision loss
• High Performance — 1M+ ops/sec, ~1.4 KB gzipped per language

Quick Start

npm install n2words

import { en, es, ar } from 'n2words'

en(123)                       // 'one hundred and twenty-three'
es(123)                       // 'ciento veintitrés'
ar(1, { gender: 'feminine' }) // 'واحدة' (with options)

Usage

ESM (Node.js, modern bundlers):

// Named imports (tree-shakable)
import { en, es } from 'n2words'

// Subpath imports (smallest bundle, recommended for single language)
import { toWords } from 'n2words/en'
import { toWords as esWords } from 'n2words/es'

CommonJS (Node.js):

n2words is an ES module. For CommonJS environments, use dynamic import:

// Promise-based
import('n2words').then(({ en }) => {
  console.log(en(42))  // 'forty-two'
})

// Subpath import (smallest bundle)
import('n2words/en').then(({ toWords }) => {
  console.log(toWords(42))  // 'forty-two'
})

Browser (UMD via CDN):

<!-- All languages -->
<script src="https://cdn.jsdelivr.net/npm/n2words/dist/n2words.js"></script>
<script>
  n2words.en(42)  // 'forty-two'
  n2words.es(123) // 'ciento veintitrés'
</script>

<!-- Single language (smallest, ~1.4 KB gzipped) -->
<script src="https://cdn.jsdelivr.net/npm/n2words/dist/languages/en.js"></script>
<script>
  n2words.en(42)  // 'forty-two'
</script>

<!-- Multiple single-language bundles (no conflicts) -->
<script src="https://cdn.jsdelivr.net/npm/n2words/dist/languages/en.js"></script>
<script src="https://cdn.jsdelivr.net/npm/n2words/dist/languages/es.js"></script>
<script>
  n2words.en(42)   // 'forty-two'
  n2words.es(42)   // 'cuarenta y dos'
</script>

Supported Languages (52)

Language codes follow IETF BCP 47 standards.

Code	Language	Options	Code	Language	Options
am	Amharic		am-Latn	Amharic Latin
ar	Arabic	✓	az	Azerbaijani
bn	Bengali		cs	Czech
da	Danish		de	German
el	Greek		en	English
es	Spanish	✓	fa	Persian
fi	Finnish		fil	Filipino
fr	French	✓	fr-BE	Belgian French	✓
gu	Gujarati		ha	Hausa
hbo	Biblical Hebrew	✓	he	Modern Hebrew	✓
hi	Hindi		hr	Croatian	✓
hu	Hungarian		id	Indonesian
it	Italian		ja	Japanese
kn	Kannada		ko	Korean
lt	Lithuanian	✓	lv	Latvian	✓
mr	Marathi		ms	Malay
nb	Norwegian Bokmål		nl	Dutch	✓
pa	Punjabi		pl	Polish	✓
pt	Portuguese		ro	Romanian	✓
ru	Russian	✓	sr-Cyrl	Serbian Cyrillic	✓
sr-Latn	Serbian Latin	✓	sv	Swedish
sw	Swahili		ta	Tamil
te	Telugu		th	Thai
tr	Turkish	✓	uk	Ukrainian	✓
ur	Urdu		vi	Vietnamese
zh-Hans	Chinese Simplified	✓	zh-Hant	Chinese Traditional	✓

Language Options

19 languages support additional options. Common options include:

gender ('masculine' | 'feminine') - 12 languages Arabic, Biblical Hebrew, Croatian, Latvian, Lithuanian, Polish, Romanian, Russian, Serbian (both scripts), Spanish, Ukrainian

formal (boolean) - 2 languages Simplified Chinese, Traditional Chinese - Toggle between formal/financial and common numerals

Other options:

• Dutch: includeOptionalAnd, accentOne, noHundredPairing
• French/Belgian French: withHyphenSeparator
• Hebrew (Modern & Biblical): andWord
• Turkish: dropSpaces
• Arabic: negativeWord (custom negative word)

Browser Compatibility

Minimum Requirements (due to BigInt):

• Node.js: 20 or above
• Browsers: Chrome 67+, Firefox 68+, Safari 14+, Edge 79+ (desktop + mobile)
• Global Coverage: ~86% of all users worldwide

Note: BigInt is a hard requirement and cannot be polyfilled. Older browsers are not supported.

Build options:

• Browser CDN: Use dist/n2words.js (pre-built UMD, tested in real browsers)
• Node.js/Bundlers: Use lib/ source (ES modules, tree-shakable)

See detailed compatibility guide →

Performance & Bundle Size

Bundle Size Comparison

Import Strategy	Bundle Size	Gzipped	Languages
All languages (UMD)	~116 KB	~28 KB	All 52
Single language (UMD)	~3-5 KB	~1.4-2 KB	1
Subpath import (ESM) ⭐	~3 KB	~1.4 KB	1
Named imports (ESM, 1 lang)	~3-5 KB	~1.4-2 KB	1
Named imports (ESM, 3 langs)	~9-15 KB	~4-6 KB	3
Named imports (ESM, 10 langs)	~30-50 KB	~10-15 KB	10

Performance Characteristics

• 1M+ ops/sec: Most languages exceed 1 million conversions per second
• Sub-millisecond: Typical conversion takes < 1 microsecond
• Low memory: ~500-800 bytes per conversion (no allocations for small numbers)
• BigInt optimized: Uses BigInt modulo instead of string manipulation
• Precomputed tables: Common segments (0-999) precomputed at module load

Subpath imports (recommended for single language):

// Smallest possible bundle - no barrel file overhead
import { toWords } from 'n2words/en'
toWords(42)  // 'forty-two'
// Final bundle: ~1.4 KB gzipped

Named imports (for multiple languages):

// Bundler tree-shakes unused languages
import { en, es } from 'n2words'
// Final bundle: ~3-4 KB gzipped (English + Spanish)

Run benchmarks:

npm run bench:perf    # Performance benchmarks (ops/sec)
npm run bench:memory  # Memory usage benchmarks

Examples

import { en, es, ar, zhHans } from 'n2words'

// Basic conversions
en(42)           // 'forty-two'
en(3.14)         // 'three point one four'
en(-1000000)     // 'minus one million'

// Input types: number, string, or BigInt
en('42')         // 'forty-two'
en(42n)          // 'forty-two'
en(999999999999999999999999n)  // Works with arbitrarily large integers

// Gender agreement (12 languages)
es(1)                          // 'uno' (masculine, default)
es(1, { gender: 'feminine' })  // 'una'
ar(1, { gender: 'feminine' })  // 'واحدة'

// Chinese: formal (financial) vs common numerals
zhHans(123)                    // '壹佰贰拾叁' (formal, default)
zhHans(123, { formal: false }) // '一百二十三' (common)

Documentation

• Compatibility Guide - Browser and Node.js compatibility
• Contributing Guide - How to contribute and add languages
• Code of Conduct - Community standards

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, documentation improvements, and language enhancements.

Please read our Code of Conduct before contributing.

See full contributing guide →

License

MIT © Wael TELLAT, Tyler Vigario & contributors