n2words

Convert numbers to words in 55 languages with zero dependencies.

Why n2words?

• 55 Languages — European, Asian, Middle Eastern, African, and regional variants
• Functional API — Each language is a standalone pure function, no classes or configuration
• Zero Dependencies — Works everywhere: Node.js, browsers, Deno, Bun
• 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 { enUS, es, ar } from 'n2words'

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

// Input types: number, string, or BigInt
enUS(999999999999999999999999n) // Works with arbitrarily large integers

Usage

ESM (Node.js, modern bundlers):

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

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

Browser (CDN):

Individual language bundles are recommended for browsers (~1.4 KB gzipped each).

<!-- ESM (recommended) -->
<script type="module">
  import { toCardinal } from 'https://cdn.jsdelivr.net/npm/n2words/dist/en-US.js'
  import { toCardinal as es } from 'https://cdn.jsdelivr.net/npm/n2words/dist/es.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 src="https://cdn.jsdelivr.net/npm/n2words/dist/es.umd.js"></script>
<script>
  n2words.enUS(42)  // 'forty-two'
  n2words.es(42)    // 'cuarenta y dos'
</script>

Supported Languages (55)

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

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

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

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

Performance & Bundle Size

Import Strategy	Gzipped	Use Case
Subpath import ⭐	~1.4 KB	Single language
Named import (1 lang)	~1.4-2 KB	Single language with barrel
Named imports (3 langs)	~4-6 KB	Multiple languages
UMD bundle	~1.4-2 KB	Legacy browser support

Performance characteristics:

• 1M+ ops/sec for most languages
• Sub-millisecond conversion time
• ~90-800 bytes memory per conversion
• BigInt modulo operations (no string manipulation)

Run benchmarks:

npm run bench              # Performance and memory benchmarks
npm run bench -- --full    # Full mode (more iterations, slower)

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