v4.0.0

4.0.0 (2026-03-05)

⚠ BREAKING CHANGES

• rename all generic language codes to BCP 47 locale-specific codes (#242)
• es: split Spanish into locale-specific variants (#241)
• remove index.js barrel, use subpath exports only (#235)
• rename toWords to toCardinal, form-agnostic architecture (#234)
• lang: split English into en-GB and en-US with extended scales and options (#232)
• ESM-first browser bundles (#225)

Features

• add 14 English locale variants (#255) (1b87dd9)
• add toOrdinal and toCurrency to 44 languages (#256) (35bdc9b)
• de-DE: add toOrdinal and toCurrency functions (#245) (59d13fb)
• en-GB: add toOrdinal and toCurrency functions (#243) (c651780)
• en-US: add toCurrency function for currency words (#237) (44243b7)
• en-US: add toOrdinal function for ordinal number words (#233) (4db67bf)
• ESM-first browser bundles (#225) (e97d895)
• es: split Spanish into locale-specific variants (#241) (d301733)
• fr-FR: add toOrdinal and toCurrency functions (#246) (b95e513)
• it-IT: add toOrdinal and toCurrency functions (#247) (93ea3eb)
• lang: split English into en-GB and en-US with extended scales and options (#232) (8e4a0df)
• nl-NL: add toOrdinal and toCurrency functions (#249) (abcac65)
• pt-PT: add toOrdinal and toCurrency functions (#248) (0d7d972)
• ru-RU: add toOrdinal and toCurrency functions (#244) (86ad7a3)

Bug Fixes

• core: pre-v4 audit fixes for parsers and exports (#262) (33d257b)
• core: pre-v4 audit fixes for parsers and exports (#264) (0268988)
• deps-dev: update dependencies to resolve tar vulnerability (#230) (1f86240)
• es-MX,fa-IR: correct number scale implementations (#250) (ab05310)

Code Refactoring

• remove index.js barrel, use subpath exports only (#235) (782768b)
• rename all generic language codes to BCP 47 locale-specific codes (#242) (8a8328d)
• rename toWords to toCardinal, form-agnostic architecture (#234) (1648e1a)

v3.1.0

3.1.0 (2026-01-08)

Features

• ka: add Georgian language support (#218) (a7c5142)
• yo: add Yoruba language support (#221) (60680b0)

Bug Fixes

• lang: remove precomputed lookup tables from all languages (#224) (fbe0c7b)

v3.0.0 - Functional Architecture

Complete rewrite from class-based to functional architecture with major performance improvements.

⚠ BREAKING CHANGES

Migration required - API has changed:

From v1.x (default export)

Note: v1 bundled all languages into a single wrapper function with runtime language selection via { lang: 'es' }. v3 requires explicit language imports for tree-shaking—only the languages you import are included in your bundle.

Context	v1	v3
Import (all)	import n2words from 'n2words'	import { en, es } from 'n2words'
Import (single)	import es from 'n2words/languages/es'	import { toWords } from 'n2words/es'
Usage	n2words(42, { lang: 'es' })	es(42) or toWords(42)
Browser	n2words(42, { lang: 'es' })	n2words.es(42)
CDN (single)	.../dist/languages/es.js	.../dist/languages/es.js (unchanged)

From v2.x (class-based)

Context	v2	v3
Import (all)	import { EnglishConverter } from 'n2words'	import { en } from 'n2words'
Import (single)	import { EnglishConverter } from 'n2words/en'	import { toWords } from 'n2words/en'
Usage	EnglishConverter(42)	en(42) or toWords(42)
Browser	n2words.EnglishConverter(42)	n2words.en(42)
CDN (single)	.../dist/EnglishConverter.js	.../dist/languages/en.js

Highlights

• 3x-85x faster conversion across languages
• 70-96% less memory per conversion
• 75-92% smaller per-language bundles
• 52 languages - all self-contained, tree-shakeable modules

New Languages

am (Amharic), am-Latn (Amharic Latin), fi (Finnish), ha (Hausa), hbo (Biblical Hebrew), sr-Cyrl (Serbian Cyrillic), zh-Hant (Traditional Chinese)

Performance Improvements

• Precomputed lookup tables (en, pt, he, hbo)
• BigInt modulo instead of string slicing (ja, sw)
• Eliminated class instantiation overhead

---

See #206 for full details.

v2.0.0

What's Changed

• merge(release): integrate v2 changes into main by @TylerVigario in #180
• Fix norwegian support by @GNUGradyn in #179
• chore(ci): remove redundant branches from push triggers by @TylerVigario in #181
• ci(deps): bump amannn/action-semantic-pull-request from 5 to 6 by @dependabot[bot] in #182
• chore: remove commitizen and related configurations from package.json by @TylerVigario in #183
• chore: relax issue templates by @TylerVigario in #184
• chore: relax pull request template by @TylerVigario in #185
• chore: improve config & tooling by @TylerVigario in #186
• ci: fix publish workflow by @TylerVigario in #187
• chore: remove unused schema reference and npm script explorer setting by @TylerVigario in #188
• chore: remove performance regression tests by @TylerVigario in #189
• chore(ci): improve workflow reliability and update action versions by @TylerVigario in #190
• chore(ci): enhance CI workflow and npm publish process by @TylerVigario in #191
• fix: refactor input handling and validation in language converters by @TylerVigario in #192
• chore: update integration scripts and improve documentation by @TylerVigario in #193
• refactor!: improve naming consistency and documentation accuracy by @TylerVigario in #194
• ci: optimize pipeline structure and npm scripts by @TylerVigario in #195
• docs: optimize documentation structure and reduce redundancy by @TylerVigario in #196

New Contributors

• @GNUGradyn made their first contribution in #179
• @dependabot[bot] made their first contribution in #182

Full Changelog: v1.24.0...v2.0.0

v1.24.0

What's Changed

• Fix: coverage badge by @forzagreen in #164
• Simplify & improve development by @TylerVigario in #165
• Fix README.md by @TylerVigario in #166
• Improve CI, local scripts, Dutch and add Swedish by @TylerVigario in #167
• Language fixes & additions by @TylerVigario in #168
• Cleanup and further language development improvements by @TylerVigario in #169
• New languages by @TylerVigario in #170
• JSDoc base classes quality pass by @TylerVigario in #171
• Structure changes by @TylerVigario in #172
• Further IETF BCP 47 conformance by @TylerVigario in #173
• Update version to 1.24.0 in package.json and package-lock.json by @TylerVigario in #175

Full Changelog: v1.23.1...v1.24.0

v1.23.1

What's Changed

• Persian number one million bug fix by @Master-Arash in #162
• CI: use OIDC, fix badge, pack --dry-run, add node 25 by @forzagreen in #163

New Contributors

• @Master-Arash made their first contribution in #162

Full Changelog: v1.23.0...v1.23.1

v1.23.0

What's Changed

• Add separator option for fr by @jmvie5 in #159
• Bump version to 1.23.0 by @forzagreen in #160

New Contributors

• @jmvie5 made their first contribution in #159

Full Changelog: v1.22.0...v1.23.0

v1.22.0

What's Changed

• Lint markdown & bump dependencies by @TylerVigario in #147
• Improvements to local scripts and generated code docs by @TylerVigario in #148
• Move library structure to single entry-point dynamical loading by @TylerVigario in #149
• Add Romanian language support to n2words (#149) by @mulgerehircum in #154
• Node 24, drop Node 18, bump dependencies by @forzagreen in #155
• Fix/drop node 18 by @forzagreen in #156

New Contributors

• @mulgerehircum made their first contribution in #154

Full Changelog: v1.21.0...v1.22.0

v1.21.0

What's Changed

• Node 22, bump dependencies, & ESLint upgrade by @TylerVigario in #139
• ESLint pass by @TylerVigario in #140
• Small fixes by @TylerVigario in #142
• ESLint second pass by @TylerVigario in #143
• Allow selecting individual languages for jsDelivr by @TylerVigario in #144
• Drop Node 21 & benchmark workflow by @TylerVigario in #145

Full Changelog: v1.20.0...v1.21.0

v1.20.0

What's Changed

• Fix: fix & improve AR by @forzagreen in #137
• Bump to 1.20.0 by @forzagreen in #138

Full Changelog: v1.19.1...v1.20.0