feat(core)!: separate currency from language, with a validated cross-language matrix

[forzagreen]

Pull Request

Status — split done, rebased onto both. The two pieces @TylerVigario asked for have
landed on main and this branch is rebased on top of them:

• fix: reject fractional amounts for currencies with no minor unit, and unbreak the docs generator #430 (merged) — the zero-subunit currency guard and the typescript@7 docs-generator
  fix. Both shipped as fix:, so the fractional-amount RangeError is no longer declared
  as a breaking change here — main already throws.
• build(esm): emit one bundle per form so a CDN page pays for what it uses #431 (merged) — per-form CDN bundles. This PR inherits them: dist/en/currency.js is
  5,255 B against dist/en.js's 9,253 B, and names any of the 22 currencies English
  has words for.

What remains is the language/currency separation itself, and one open design question —
see the sequencing comment.

What does this do?

A language and a currency are two different things. n2words was treating them as one, and this
PR separates them.

A language is spoken across many countries; a currency belongs to exactly one. But n2words gave
every country its own language file — 16 English files, identical numeral logic in 12 of them,
each one hardcoding a single currency's words and therefore able to name that one currency and
nothing else. Asking en-GB for Kenyan shillings was impossible, even though "forty-two
shillings and fifty cents" is plain English. You had to import en-KE — a 450-line duplicate of
en-GB whose only real difference was the word "shilling".

Currency words now live on their own axis, keyed by language, so every entry point of a
language can name every currency that language has words for:

                    WHICH CURRENCIES CAN THIS ENTRY POINT NAME?

  before — one file, one currency          after — one `en` matrix, shared by all 16
  ─────────────────────────────────        ────────────────────────────────────────
        USD CAD AUD GBP KES INR …                USD CAD AUD GBP KES INR …
  en-US  ●   ·   ·   ·   ·   ·             en-US  ●   ●   ●   ●   ●   ●
  en-CA  ·   ●   ·   ·   ·   ·             en-CA  ●   ●   ●   ●   ●   ●
  en-AU  ·   ·   ●   ·   ·   ·             en-AU  ●   ●   ●   ●   ●   ●
  en-GB  ·   ·   ·   ●   ·   ·             en-GB  ●   ●   ●   ●   ●   ●
  en-KE  ·   ·   ·   ·   ●   ·             en-KE  ●   ●   ●   ●   ●   ●
  en-IN  ·   ·   ·   ·   ·   ●             en-IN  ●   ●   ●   ●   ●   ●
    …                                        …
  16 locales × 1 currency = 16             16 locales × 24 currencies = 384

import { toCurrency } from 'n2words/en-GB'
toCurrency(42.50, { currency: 'KES' })  // before: TypeError — no such option
                                        // after:  'forty-two shillings and fifty cents'

Full detail, including the diagram and the two bugs this surfaced, in The core change:
currency and language are separate axes — the very next section. It's also written up
permanently in docs/language-layers.md.

Everything else in the PR is either what made that possible or what fell out of it:

• src/utils/currency-vocab.js — the new shared matrix, 54 exports keyed by language
  (not locale), covering 50 distinct currencies. Currency word-data moves out of the language
  files; pluralization rules stay per-file.
• toCurrency's currency option becomes a real validated enum, with its allowed set
  derived from the matrix rather than hand-typed. On main it was honored by exactly one of
  72 languages; the other 71 ignored or rejected it.
• 13 files stop being copies. en-AU, en-BD, en-GH, en-IE, en-KE, en-MY, en-NG,
  en-NZ, en-PH, en-PK, en-SG, en-ZA and es-MX were behavioural clones differing only
  in default currency; they become ~40-line locale profiles. ~6,400 lines deleted. en-CA
  looked like a clone too and isn't — see 14 clone files collapse into
  locale profiles, below.
• Two real bugs found and fixed, both previously unreachable, both reachable the moment a
  language can name a second currency: a grammatical-gender mismatch across every
  Slavic/Baltic/Romanian/Arabic/Spanish language, and an undefined-rendering bug for
  currencies whose noun doesn't pluralize (taka, ringgit, naira, rand).
• 1000-subunit currencies (millimes, fils) are nameable at last — the parser's fixed
  two-decimal precision previously ruled out TND, KWD, BHD, OMR, JOD, IQD and LYD entirely.
• 46 bare-tag alias files make import … from 'n2words/de' the primary import path.
  zh, pt, sr, am stay region/script-qualified only.
• Four new CI gates hold all of the above in place.
• Counts corrected: "70+ languages" → 50 languages, 72 regional variants (the old number
  counted variants as languages).

⚠️ This is a breaking release (v6.0.0) — one break, in three cases, all consequences of
the currency option becoming real. Full before/after under ⚠️ Breaking changes, further
down. The fractional-amount RangeError that an earlier revision of this description listed as
a second break shipped separately in #430 and is not re-declared here.

Rationale docs: docs/language-layers.md, docs/currency-vocab.md, docs/bare-tag-aliases.md.

---

The core change: currency and language are separate axes

Not breaking — verified directly against main; see Explicitly not affected, near the
end. This section is the evidence for the summary above.

The three layers

A BCP 47 code like en-KE was encoding three unrelated facts in one string. They don't vary
together — that's the whole point — so n2words now names each one separately:

flowchart TD
    E["What you import — 16 English entry points<br/>n2words/en-US · en-GB · en-AU · en-KE · en-IN · en-ZA · ..."]

    E --> L1
    E --> L2
    E --> L3

    subgraph S1["LAYER 1 — Numerals · varies by language VARIETY"]
        L1["4 full implementations<br/>en-US · en-GB · en-IN · en-CA<br/>16 entry points collapse to 4 behaviours"]
    end

    subgraph S2["LAYER 2 — Currency words · varies by LANGUAGE"]
        L2["1 shared matrix — en<br/>24 currencies · GBP KES AUD USD INR MYR ...<br/>16 entry points share 1 vocabulary"]
    end

    subgraph S3["LAYER 3 — Default currency · varies by COUNTRY"]
        L3["16 country defaults<br/>en-US → USD · en-KE → KES · en-AU → AUD ...<br/>16 entry points, 16 distinct values"]
    end

Loading

The cardinalities are the argument. Across the same 16 entry points the three layers have
4, 1 and 16 distinct values. One filename cannot encode three facts with three
different arities without duplicating something — and what got duplicated was layer 1, the
numeral logic, which is the hard part and the part you least want copied 16 times.

Layer	Varies by	Lives in	Distinct values across English
1 · Numerals	language variety	a full src/{code}.js implementation	4
2 · Currency words	language	src/utils/currency-vocab.js, keyed by language	1 (en, 24 currencies)
3 · Default currency	country	a thin src/{code}.js with variantOf	16

The measurement that started this

Running every English variant over ~1,300 probe values and grouping by identical output:

	Files	Distinct behaviours
Numerals (toCardinal/toOrdinal)	16	3 under default options — Commonwealth (×12), South Asian (×3), en-US
Currency reachability (on main)	16	16 — each locale knew its own currency and no other

en-AU vs en-SG differed by zero lines of logic — the entire diff between the two files
was doc comments. The file count was tracking currency, not language.

(Layer 1 ends up with 4 implementations rather than 3 because en-CA exposes an option the
others don't; see 14 clone files collapse into locale profiles, below.)

It generalizes past English

English is where the duplication was worst, but the model is language-agnostic:

Language	Entry points	Layer 1 — numeral impls	Layer 2 — currency matrix	Layer 3 — profiles
English	16	4 — en-US, en-GB, en-IN, en-CA	en — 24 currencies	12
Spanish	3	2 — es-ES, es-US	es — 3	1 (es-MX)
French	2	2 — fr-FR, fr-BE	fr — 3	0
Arabic	1	1 — ar-SA	ar — 9	0
Portuguese	2	2 — pt-BR, pt-PT	ptBR / ptPT — kept split	0

Arabic is the clearest demonstration that layer 2 does the work on its own. One entry point,
zero new files, and it now names nine Arab-world currencies:

import { toCurrency } from 'n2words/ar'
toCurrency('3.003', { currency: 'KWD' })  // 'ثلاثة دنانير وثلاثة فلوس'
toCurrency(42.50,   { currency: 'MAD' })  // 'اثنان وأربعون درهماً وخمسون سنتيماً'

Arabic numerals don't change between Riyadh and Casablanca, so there is no ar-MA file and no
reason for one — the currency was never a property of the language. Portuguese is the
counterexample that proves layer 2 is keyed correctly: pt-BR and pt-PT name the same EUR
cent with genuinely different words (centavo vs cêntimo), so their matrices stay split, as
do the zh/sr/am script pairs — the same set docs/bare-tag-aliases.md's "very different"
test already excludes from a bare-tag alias.

What it unlocks

Every one of these throws TypeError: Unknown option "currency" on main:

import { toCurrency as gb } from 'n2words/en-GB'
import { toCurrency as ke } from 'n2words/en-KE'

gb(42.50, { currency: 'KES' })  // 'forty-two shillings and fifty cents'
ke(42.50, { currency: 'GBP' })  // 'forty-two pounds and fifty pence'
//                                             ^^^^^ note: pence, not cents —
//                                 the minor unit follows the currency, not the locale

// an invariable-noun currency, from any English entry point
toCurrency(2, { currency: 'NGN' })   // en-US: 'two naira'    (not 'two nairas')
toCurrency(2, { currency: 'MYR' })   // en-CA: 'two ringgit'
toCurrency('1.500', { currency: 'TND' })  // en-ZA: 'one dinar and five hundred millimes'

An app rendering two currencies in English used to have to import two behaviourally-identical
450-line modules. Now it imports one and passes an option.

Every <form>Values currency union is keyof typeof <language> instead of a hand-typed literal
(EnCurrency, EsCurrency, …), so widening a language's map widens every file referencing it
in the same edit, and a typo in either place fails typecheck.

14 clone files collapse into locale profiles — 13 did, one didn't

en-AU, en-BD, en-GH, en-IE, en-KE, en-MY, en-NG, en-NZ, en-PH, en-PK,
en-SG, en-ZA, and es-MX turned out to be behavioural clones of a base (en-GB, en-IN,
or es-ES) under default options. Each becomes a locale profile — export * from its base plus
a toCurrency wrapper applying just its own default:

// src/en-AU.js — the entire currency-relevant part
import { resolveOptions } from './utils/resolve-options.js'
import { toCurrency as toCurrencyBase, currencyValues } from './en-GB.js'

export * from './en-GB.js'
export const variantOf = 'en-GB'

export const currencyDefaults = { and: true, currency: 'AUD' }

function toCurrency(value, options) {
  return toCurrencyBase(value, resolveOptions(options, currencyDefaults, currencyValues))
}
export { toCurrency }

en-CA looked like the same clone by every default-value probe — until a second check (does
this file export any options the others don't) found hundredPairing ("fifteen hundred" vs
"one thousand five hundred"), an option no other English variant exposes. Collapsing it would
have silently deleted a documented feature. en-CA stays a full implementation; everything else
listed above became a profile. Net: ~6,400 lines of duplicated numeral logic removed.

Two real bugs the widening surfaced

Both were latent, not shipped — unreachable before this PR, reachable the moment a language
could name more than one currency, which is exactly what this PR does. Both are fixed here.

Grammatical gender. ru-RU, uk-UA, pl-PL, hr-HR, lt-LT, lv-LV, ro-RO,
sr-Cyrl-RS, sr-Latn-RS, es-*, and ar-SA each hardcoded their single currency's noun
gender as a literal in toCurrency (integerToWords(rubles, 'masculine')). That was already
wrong the instant a second, differently-gendered currency became nameable:

// ru-RU, gender read from the currency's own data instead of hardcoded
toCurrency(2)                        // 'два рубля'   — рубль is masculine, два is correct
toCurrency(2, { currency: 'UAH' })   // 'дві гривні'  — гривня is feminine, дві is correct
//                                       (a hardcoded 'masculine' would have produced
//                                        'два гривня' — well-formed, wrong gender)

majorGender/minorGender move into the matrix next to the word forms they describe; ar-SA's
own MINOR_GENDER table folds into this and is deleted. New gate:
currency-vocab-contract.test.js now checks each gender field independently — if any entry for
a language declares majorGender, every entry must (same for minorGender and any entry with a
minor unit) — so a currency added without one fails CI instead of shipping a mismatch.

Invariable-noun currencies. taka (BDT), ringgit/sen (MYR), naira/kobo (NGN), and
rand (ZAR) don't pluralize — a one-element word-form array, not the usual
[singular, plural] pair. The English bases indexed major[1] for any count past 1
unconditionally:

// before the fix, reachable the moment en's matrix included an invariable-noun currency
toCurrency(2, { currency: 'BDT' })  // 'two undefined'   ← major[1] doesn't exist
// after
toCurrency(2, { currency: 'BDT' })  // 'two taka'        ← major.length < 2, so major[0]

Fixed by checking array length before assuming a plural form exists
(count === 1n || major.length < 2 ? major[0] : major[1]), applied in en-US, en-GB,
en-IN, and en-CA — the four files with real currency-building logic; every profile
delegating to one of the first three inherits the fix automatically.

The trap a naive collapse would have shipped

A profile that only shadowed currencyDefaults via export *, without the toCurrency
wrapper, would be silently wrong: the base's toCurrency closes over the base's own
module-scope currencyDefaults, so en-AU would report currencyDefaults.currency === 'AUD'
while every call with no options still returned pounds. Verified this is real (not theoretical)
with a minimal ES-module reproduction before writing the profiles. New gate,
variant-profile-contract.test.js, exists specifically to catch a regression to that shape: for
every profile, it asserts profile.toCurrency(v) with no options equals
base.toCurrency(v, { currency: profileDefault }) called explicitly, across a probe set
including 0/1/2 (the singular/dual boundary) and a fraction.

Updated gates

• bare-tag-contract.test.js — a profile (variantOf) is now excluded from counting as a
  family's "canonical" variant, same as an alias (aliasOf) already was, so a bare tag can
  never resolve to a profile instead of the real implementation it delegates to.
• currency-vocab-contract.test.js — the expected matrix export name is now derived from
  the code's primary subtag (en-KE → en) instead of the old full-locale camelCase
  (enKE), with a small override list for the languages that stay split
  (pt-BR→ptBR, zh-Hans-CN→zhHans, ...). Profiles are skipped for the same reason
  aliases already were — their currencyValues is a re-export, not a separate declaration.

LANGUAGES.md's currency table, before it would have gotten worse

Widening en's reachability turns "72 variants name 50 currencies across 96 pairs" into
462 pairs — accurate, but a naive table would repeat "en-AU, en-BD, en-CA, ...,
en-ZA" (16 near-identical entries) in nearly every row. The generator now collapses a
family's contribution to its bare primary subtag whenever every variant reaches a currency
together:

-|`EUR`|`de-DE`, ...|`en-AU`, `en-BD`, `en-CA`, `en-GB`, `en-GH`, `en-IE`, `en-IN`, `en-KE`,
-       `en-MY`, `en-NG`, `en-NZ`, `en-PH`, `en-PK`, `en-SG`, `en-US`, `en-ZA`, `es-MX`,
-       `es-US`, `pt-BR`|
+|`EUR`|`de-DE`, ...|`en`, `es`, `pt`|

Bundle-size honesty

Widening en's matrix has a real, measured cost — every English bundle now carries every
currency any English locale names, not just its own. Built dist/ with rollup to measure it
rather than estimate, against main directly (abd02f2) — this is the number that matters
to a consumer upgrading, since it's the entire cost of this PR's currency-matrix work, not just
the layering step on top of it. Re-checked after the rebase onto 1fe4e02: every figure below
is unchanged, since #430 touches only the five zero-exponent languages and #431 adds files
without altering the combined bundles:

	main	this branch	Delta
en-US.js	7,778 B	9,227 B	+1,449 B
en-GB.js	7,434 B	8,886 B	+1,452 B
en-AU.js (profile)	7,435 B	8,974 B	+1,539 B
en-KE.js (profile)	7,439 B	8,974 B	+1,535 B
es-ES.js	8,483 B	9,211 B	+728 B
es-MX.js (profile)	8,481 B	9,296 B	+815 B

main has no currency-vocab.js at all — toCurrency on main hardcodes its own words inline
— so this delta is the full cost of gaining a validated, cross-currency-capable currency
option, not a layering-specific regression. Isolated one level further, just the language-layers
step on top of the rest of this PR's already-landed currency-matrix work (i.e. its own before/after,
measured the same way against the pre-layering commit within this branch, 9503e01) costs far
less — rekeying the matrix from locale to language, alone:

	before layering (9503e01)	after (this branch)	Delta
en-US.js	8,628 B	9,227 B	+599 B
en-GB.js	7,970 B	8,886 B	+916 B
en-AU.js (profile)	7,971 B	8,974 B	+1,003 B
es-ES.js	8,864 B	9,211 B	+347 B

Note en-AU.js and en-KE.js land at the same 8,974 B in the main-relative table — both
profiles bundle the identical en matrix, differing only in which default-currency string is
embedded. A profile's bundle is not smaller than its base's either way — rollup.config.js
produces self-contained bundles with no runtime cross-file imports, so a profile pays the same
matrix cost plus a ~60–90 B wrapper. The win from collapsing 14 files into profiles is
source-side (~6,400 lines deleted), not bundle-side; docs/currency-vocab.md's "Why keyed by
language, not by currency" section has the full accounting.

Verification

Two different comparisons answer two different questions, and this section keeps them separate
on purpose:

Against main directly (1fe4e02, after #430 and #431 merged) — is any of this breaking,
full stop:

• toCardinal/toOrdinal: 0 differences, every one of main's 72 codes, ~1,300 probe
  values each.
• toCurrency under default options: 0 diffs. An earlier revision reported 40, all in the
  five zero-exponent languages; fix: reject fractional amounts for currencies with no minor unit, and unbreak the docs generator #430 landed that guard on main, so main and this branch now
  agree. Re-measured after the rebase, not carried over: 90 comparisons across ja-JP, ko-KR,
  vi-VN, fa-IR, id-ID, zero differences.
• toCurrency under the currency option: exactly the 1,136 diffs already declared in §1
  below — nothing new, and unchanged by the rebase (fix: reject fractional amounts for currencies with no minor unit, and unbreak the docs generator #430 added no options to those five
  files). Together with the line above this is the same sweep described in How was this
  tested?, confirming the language-layers work didn't introduce a break it would have
  caught.
• Cross-currency capability spot-checked directly against main's absence of the feature
  entirely (en-GB+KES, en-KE+GBP, en-CA+NGN, and every invariable-noun currency named above).

Step-by-step within the branch (matrix rekey, exponent/arity fixes, gender migration, profile
collapse) — re-run after each structural step, not just once at the end, because this is how
regressions were actually caught during development, not by inspection:

• toCardinal/toOrdinal: 0 differences at every step.
• toCurrency under each entry point's own default options: 0 differences at every step. The
  only diffs across the whole sequence are the 13 new variantOf metadata lines the profiles
  introduce — not observable through any public function.
• This is specifically what caught the en-CA/hundredPairing and invariable-noun bugs: a
  diff against main alone wouldn't isolate which of this PR's several structural steps
  introduced a given regression, so the granular replay is what made them findable at all.

npm test → 762 tests passed on this branch, vs. 453 on main (+309) — measured on both,
not estimated:

Test file	main	this branch	Δ
contract.test.js	72	72	0
conversions.test.js	76	122	+46
options-contract.test.js	41	72	+31
range-contract.test.js	72	72	0
test/utils/*.test.js (5 files)	192	192	0
bare-tag-contract.test.js	—	89	+89
currency-vocab-contract.test.js	—	129	+129
variant-profile-contract.test.js	—	14	+14
Total	453	762	+309

The three new files are the three new gates this PR adds; conversions.test.js and
options-contract.test.js grew because every currency-exporting language now has real
currency-option coverage main never had. Isolated one level further (just the language-layers
step, measured the same way against the pre-layering commit 9503e01 within this branch, the
number quoted earlier in this PR's history): 771 → 762, a −9 net — 13 profile files no longer
re-verify a currency matrix already proven by the base they delegate to
(currency-vocab-contract.test.js alone: 152 → 129), offset by the +14 new
variant-profile-contract.test.js adds. That −9 is real but it's a statement about one step
within this PR, not about this PR versus main — the table above is the number that matters to
someone deciding whether to merge this. npm run lint clean on both.

---

⚠️ Breaking changes

Every before/after below was produced by running the actual code on main (1fe4e02, current
as of this writing, after #430 and #431 merged) and on this branch, not from memory. There is
one break, in three cases, all declared in the BREAKING CHANGE: footer on the
feat(core)! commit so they reach the generated release notes — see Release-notes footer at
the bottom for a parser bug that was truncating that footer.

The fractional-amount RangeError for zero-exponent currencies (JPY, KRW, VND, IRR, IDR) was
listed here as a second break in an earlier revision. It shipped in #430 as a fix: and is
already on main, so this PR no longer introduces it and it is not re-declared. What this PR
still adds is the cross-language reach of that same guard — see Non-breaking improvements
below.

At a glance

#	Change	Blast radius	Old result	New result
1a	currency option silently ignored	41 languages	option discarded, local currency returned	RangeError
1b	currency option unknown	30 languages	TypeError	RangeError (or now works, if it's the language's own currency)
1c	pt-BR currency free-form → enum	pt-BR only	code echoed / auto-detected	RangeError

---

1. currency is now a validated enum

On main the currency option was honored by exactly one language (pt-BR). The other 71
either ignored it or rejected it as unknown. It is now a real, validated enum everywhere,
which changes the behavior of all three groups.

1a. 41 languages silently ignored the option — now RangeError

On main these declared function toCurrency(value) — no options parameter at all — so JS
discarded the second argument without a word. You got your local currency back and no
indication that your request was dropped:

import { toCurrency } from 'n2words/hi-IN'

toCurrency(5, { currency: 'USD' })
// main:        'पाँच रुपये'   ← "five rupees". Asked for dollars, got rupees, no error.
// this branch: throws RangeError: Option "currency" must be one of: INR — got "USD"

// same shape everywhere:
'n2words/ur-PK'  toCurrency(5, { currency: 'USD' })  // main 'پانچ روپے'    (five rupees)
'n2words/pl-PL'  toCurrency(5, { currency: 'USD' })  // main 'pięć złotych' (five zloty)
'n2words/ja-JP'  toCurrency(5, { currency: 'USD' })  // main '五円'          (five yen)
// all four now throw RangeError naming the one code they accept

All 41 languages (click to expand)

am-ET, am-Latn-ET, ar-SA, az-AZ, bn-BD, cs-CZ, da-DK, el-GR, fa-IR, fi-FI,
fil-PH, gu-IN, ha-NG, hbo-IL, he-IL, hi-IN, hr-HR, hu-HU, id-ID, ja-JP,
ka-GE, kn-IN, ko-KR, lt-LT, lv-LV, mr-IN, ms-MY, nb-NO, pa-IN, pl-PL,
ro-RO, sv-SE, sw-KE, ta-IN, te-IN, th-TH, tr-TR, uk-UA, ur-PK, vi-VN,
yo-NG

This break only fires on code that was already broken — the option never did anything in
these languages, so any caller passing it was already getting the wrong currency silently.

1b. 30 languages threw TypeError — now RangeError, or succeed

These already took an options object (for and / formal), so an unknown currency key was
a TypeError. Two outcomes now, depending on the code you pass:

import { toCurrency } from 'n2words/en-US'

toCurrency(5, { currency: 'EUR' })
// main:        throws TypeError: Unknown option "currency" — expected one of: and
// this branch: throws RangeError: Option "currency" must be one of: USD — got "EUR"
//              ^^^^^^^^^^ error TYPE changed — `catch (e) { if (e instanceof TypeError) … }` breaks

toCurrency(5, { currency: 'USD' })
// main:        throws TypeError
// this branch: 'five dollars'     ← now works ✅ (its own currency is in the enum)

import { toCurrency } from 'n2words/fr-FR'
toCurrency(5, { currency: 'EUR' })
// main:        throws TypeError: Unknown option "currency" — expected one of: and
// this branch: 'cinq euros'       ← now works ✅

The only genuinely breaking part here is the error type: TypeError → RangeError. This
is deliberate and consistent with the rest of the options contract — resolveOptions throws
TypeError for a malformed option (unknown key, wrong type) and RangeError for a
well-formed but out-of-set value. currency is now a known key, so an unsupported value is
a range problem, not a type problem.

All 30 languages (click to expand)

de-DE, en-AU, en-BD, en-CA, en-GB, en-GH, en-IE, en-IN, en-KE, en-MY,
en-NG, en-NZ, en-PH, en-PK, en-SG, en-US, en-ZA, es-ES, es-MX, es-US,
fr-BE, fr-FR, it-IT, nl-NL, pt-PT, ru-RU, sr-Cyrl-RS, sr-Latn-RS,
zh-Hans-CN, zh-Hant-TW

1c. pt-BR: free-form string → validated enum

pt-BR is the one language where currency actually worked, so it's the one with real
migration work. Three previously-accepted inputs now throw:

import { toCurrency } from 'n2words/pt-BR'

// (i) the PREVIOUS DOCUMENTED DEFAULT — '' auto-detected BRL
toCurrency(5,    { currency: '' })     // main 'cinco reais'                   → RangeError
toCurrency(5.50, { currency: '' })     // main 'cinco reais e cinquenta centavos' → RangeError
toCurrency(5)                          // 'cinco reais' — unchanged ✅ (default is now 'BRL')
toCurrency(5,    { currency: 'BRL' })  // 'cinco reais' — the explicit spelling ✅

// (ii) lowercase codes were uppercased for you
toCurrency(5, { currency: 'brl' })     // main 'cinco reais'                   → RangeError

// (iii) an unknown code echoed itself as the major word
toCurrency(5,    { currency: 'CAD' })  // main 'cinco CAD'                     → RangeError
toCurrency(5.50, { currency: 'CAD' })  // main 'cinco CAD e cinquenta centavos' → RangeError
toCurrency(1,    { currency: 'XYZ' })  // main 'um XYZ'                        → RangeError

That last one is the reason the enum exists: main would cheerfully emit 'um XYZ' for any
three letters you handed it, mixing an ISO code into spelled-out Portuguese.

Still works, unchanged — the currencies pt-BR genuinely has words for:

toCurrency(42.50, { currency: 'USD' })  // 'quarenta e dois dólares e cinquenta centavos' ✅
toCurrency(42.50, { currency: 'EUR' })  // 'quarenta e dois euros e cinquenta centavos'   ✅
toCurrency(5,     { currency: 'GBP' })  // 'cinco libras'                                 ✅
toCurrency(100,   { currency: 'JPY' })  // 'cem ienes'                                    ✅

The authoritative set is exported: currencyValues.currency is
['BRL', 'USD', 'EUR', 'GBP', 'JPY'].

Migrating (all of §1)

The allowed set is introspectable at runtime, so you never have to guess:

import { toCurrency, currencyValues, currencyDefaults } from 'n2words/pt-BR'

currencyDefaults.currency          // 'BRL'
currencyValues.currency            // ['BRL', 'USD', 'EUR', 'GBP', 'JPY']

if (currencyValues.currency.includes(code)) {
  toCurrency(amount, { currency: code })
} else {
  // this language has no words for `code` — pick another language or omit the option
}

• Passing { currency: '' } → drop the option, or pass the explicit code.
• Passing a lowercase code → .toUpperCase() it.
• Catching TypeError around toCurrency → catch RangeError too (or just Error).

---

New currencies: millimes, fils, and the Moroccan dirham

Not breaking — additive, and a direct consequence of the layer-2 matrix above:
parseCurrencyValue's new digit-count argument defaults to 2, so
every existing call is unchanged.

Most currencies divide into 100; a few divide into 1000, and the fixed two-decimal parser ruled
all of them out. Naming one at two digits isn't a partial answer, it's a wrong one:

// what a 2-digit parse would have produced
toCurrency('1.500', { currency: 'TND' })  // 'one dinar and fifty millimes'
                                          //  ...for an amount meaning five hundred

Now supported: TND (millime), KWD/BHD/JOD/IQD (fils), OMR (baisa), LYD (dirham).

import { toCurrency } from 'n2words/en'

toCurrency('1.500',  { currency: 'TND' })  // 'one dinar and five hundred millimes'
toCurrency('1.050',  { currency: 'TND' })  // 'one dinar and fifty millimes'
toCurrency('0.001',  { currency: 'TND' })  // 'one millime'
toCurrency('42.750', { currency: 'KWD' })  // 'forty-two dinars and seven hundred fifty fils'
toCurrency('2.002',  { currency: 'OMR' })  // 'two rials and two baisas'
toCurrency('1.500',  { currency: 'USD' })  // 'one dollar and fifty cents'  ← still 2 digits

import { toCurrency } from 'n2words/fr'
toCurrency('42.750', { currency: 'TND' })  // 'quarante-deux dinars et sept cent cinquante millimes'

How it works

CURRENCY_EXPONENTS now holds 3 alongside 0 (2 stays the implicit default for anything
absent), and minorUnitDigits(currency) derives the parser argument from it. Because the digit
count depends on the resolved currency, a language naming one of these resolves options
before parsing:

const { currency } = resolveOptions(options, currencyDefaults, currencyValues)
const { isNegative, dollars, cents } = parseCurrencyValue(value, minorUnitDigits(currency))

minorUnitDigits deliberately returns 2, not 0, for a zero-exponent currency like JPY —
parsing those at 0 digits would silently turn 1.5 yen into 1 yen, exactly the truncation
assertCurrencyExponent exists to refuse.

Coverage

Arabic number words are variant-independent while currency is country-specific, so arSA is
the single home for the whole Arab-world set.

Language	Currencies added
en-US (so also n2words/en)	all seven + MAD — English is where these are quoted internationally
fr-FR, fr-BE	TND + MAD — francophone Maghreb
ar-SA	all seven + MAD

MAD is not one of them

The Moroccan dirham divides into 100 santim, not 1000 — so despite sitting among the
dinars it's an ordinary 2-decimal currency: no CURRENCY_EXPONENTS entry, parsed at the
default precision. Flagged at both definition sites, since landing it beside the 1000-subunit
work invites exactly the wrong assumption.

toCurrency(42.50, { currency: 'MAD' })  // en  'forty-two dirhams and fifty centimes'
                                        // fr  'quarante-deux dirhams et cinquante centimes'
                                        // ar  'اثنان وأربعون درهماً وخمسون سنتيماً'

درهم is reused rather than duplicated — it's Libya's minor unit and Morocco's major one,
the same word in two roles. Its Arabic minor unit سنتيم is masculine, so MINOR_GENDER carries
it and 3 santim renders ثلاثة سنتيمات, not the feminine ثلاث.

LANGUAGES.md regenerated: 50 distinct currencies (was 42) across 96 language/currency
pairs (was 76).

An Arabic grammar bug this surfaced

ar-SA hardcoded its minor unit as feminine — correct for هللة, wrong for مليم, فلس and درهم.
Arabic inverts numeral gender for 3–10, so a masculine noun takes the ة-marked numeral:

3.003 KWD   before: ثلاثة دنانير وثلاث فلوس     ← ثلاث, feminine — wrong for فلس
            after:  ثلاثة دنانير وثلاثة فلوس    ← ثلاثة, masculine
11.011 KWD  after:  أحد عشر ديناراً وأحد عشر فلساً
3.003 OMR   after:  ثلاثة ريالات وثلاث بيسات     ← بيسة is feminine, so ثلاث is right here

A new MINOR_GENDER map drives the selection per currency. This is grammar, so it lives in
ar-SA.js, not the shared matrix. SAR output is unchanged — it was already feminine.

The bug was unreachable before this PR (ar-SA named only SAR), so nothing shipped wrong.

The gate

currency-vocab-contract.test.js proves the round trip behaviorally rather than trusting the
declaration: for every 3-decimal currency a language advertises, '1.500' and '1.050' must
not render alike — which they do the instant a language forgets to pass the digit count. A
language can't declare one of these currencies and quietly mis-parse it.

---

Bare-tag aliases

Purely additive — no existing specifier changes meaning. n2words/en-GB and every other
region/script-qualified import keeps working exactly as before.

What ships

46 alias files, one per language that can safely have a default variant:

// src/de.js — the entire file, modulo its header comment
export * from './de-DE.js'
export const aliasOf = 'de-DE'

No package.json change was needed: the exports map is already a wildcard
("./*" → "./src/*.js"), so n2words/de resolves the moment src/de.js exists. Types come
along the same way via typesVersions. ./utils/* stays walled off (null).

The 50 languages break down as:

	Count	Alias?
Single-variant families	43	✅ all 43 — nothing to be ambiguous among
Multi-variant families that pass the test	3 — en (16 variants), es (3), fr (2)	✅ en→en-US, es→es-ES, fr→fr-FR
Multi-variant families that fail it	4 — zh, sr, am, pt	❌ region/script-qualified only

43 + 3 = 46 aliases, 72 variant files, 50 languages.

The rule: what makes a family "very different"

The interesting design question is why en gets an alias when its variants disagree wildly,
while pt — only two variants — doesn't. The test is deliberately narrow: would defaulting
silently change the shape of the output, not "do these variants differ a lot".

Two things fail it, and I verified both by running the code:

Different script — same grammar, same words, different Unicode:

zh-Hans-CN(42)  '肆拾贰'   ·  zh-Hant-TW(42)  '肆拾貳'    // identical structure
sr-Cyrl-RS(1)   'један'   ·  sr-Latn-RS(1)   'jedan'    // literally the same word
am-ET(11)       'አስራ አንድ' ·  am-Latn-ET(11)  'asra and'

For zh, 4 of 7 sampled values render byte-identically; the pairs diverge only where a
character has a distinct traditional form (万/萬, 亿/億). A bare zh would be picking
a script on the caller's behalf, invisibly.

Different core numbering system — this is the one that would actually corrupt numbers:

pt-BR(1e9)   'um bilhão'        ·  pt-PT(1e9)   'um mil milhões'
pt-BR(1e12)  'um trilhão'       ·  pt-PT(1e12)  'um bilião'
pt-BR(16)    'dezesseis'        ·  pt-PT(16)    'dezasseis'

Brazil is short-scale, Portugal is long-scale. Note that bilhão and bilião are the same
word to the eye and differ by a factor of 1000 — a bare pt defaulting either way wouldn't
produce awkward output, it would produce confidently wrong numbers. That's why pt is
excluded even though it has only two variants, while 16-variant en is fine.

Why en passes anyway

Because an alias is a fixed pointer to one variant, not a dispatcher. en → en-US makes
no claim about its siblings, several of which genuinely diverge:

en(1e7)     'ten million'   ·  en-IN(1e7)  'one crore'   // Indian lakh/crore grouping
es-ES        EUR, max 10³⁰  ·  es-MX  MXN, max 10³⁰  ·  es-US  USD, max 10²¹

Those differences are real, but they're differences between variants you asked for by name —
not something the bare tag silently resolves.

The gate: test/bare-tag-contract.test.js

Two mechanical properties (the "very different" judgment stays human, as it must):

• Completeness — every primary subtag with exactly one variant in src/ must have an
  alias. This is what stops the backfill from being a one-time cleanup that rots.
• Fidelity — every re-exported binding is reference-identical (===) to its target's,
  proving export * forwards live bindings rather than a stale copy.

Because fidelity is proven here, the four other contract gates skip alias files outright
(if (mod.aliasOf !== undefined) continue) rather than re-fuzzing functions already known to
be the same object.

I verified independently of the gate: all 46 aliases have a valid in-family aliasOf, all 46
are reference-identical across every exported binding, all 46 match the two-line shape, and
alias/target form coverage agrees in all 46 cases. Zero deviations.

Tooling and bundles

• npm run lang:add -- de is refused — bare codes are reserved, so a typo can't scaffold
  a full implementation where the gate expects a re-export (add-language.js:682).
• First variant in a family → alias scaffolded automatically. Joining an existing family →
  prints a note instead, because repointing an alias is a human call.
• dist/ gets a real bundle per alias, not a stub. Deliberate: a UMD bundle has no module
  loader to follow a re-export, so dist/en.umd.js must be self-contained — and it isn't even
  byte-equal to en-US.umd.js, since it exposes the documented n2words.en global. src/
  consumers never pay for this; it costs npm tarball size only.

---

Explicitly not affected

Verified by differential sweep against main, not by assertion:

• toCardinal and toOrdinal: 0 differences. Every language, over 0, 1, 7, 42, 100, 1000, 1234567, -5, 3.14, 999999999n. This PR touches currency only.
• Every language's default-currency output is unchanged — the vocabulary extraction into
  the matrix is a pure move, and against current main the default-options sweep finds 0
  differences in every language, fractional amounts included (the 40 fractional cases an
  earlier revision listed here are on main now, via fix: reject fractional amounts for currencies with no minor unit, and unbreak the docs generator #430).
• No option was removed or renamed anywhere, in any form. Across all 72 languages × 3
  forms the only changed default value is pt-BR's currency: '' → 'BRL'; every other change
  is a new currency key added to an existing defaults object (e.g. en-US {and: true} →
  {and: true, currency: 'USD'}).
• Bare-tag aliases are non-breaking — purely additive, and no package.json exports
  change was required. See the bare-tag section above for the full verification.
• The language-layers restructuring (matrix rekey, 13 files becoming profiles, the two bugs
  it surfaced) is non-breaking and output-neutral — every existing import specifier, every
  default currency, and every toCardinal/toOrdinal/toCurrency(defaults) output is
  unchanged, verified directly against main: the only toCurrency diffs found are the
  same 1,136 (currency option) already declared in §1 above, with 0 under default options,
  nothing attributable to the layering step specifically. It was additionally verified step-by-step
  within the branch, re-run after each structural change rather than once at the end — see its
  own Verification subsection for both comparisons and why they're kept separate.

Non-breaking improvements that come with this

• The zero-subunit guard now reaches cross-language. fix: reject fractional amounts for currencies with no minor unit, and unbreak the docs generator #430 made a fractional JPY/KRW/VND/
  IRR/IDR amount throw in the five languages whose own currency it is. Because the check is on
  the currency rather than the language, the matrix extends it to any language naming one
  through the currency option — previously unreachable, since no other language could name
  those currencies at all:

  import { toCurrency } from 'n2words/pt-BR'
  
  toCurrency(100,   { currency: 'JPY' })  // 'cem ienes'  → unchanged ✅
  toCurrency(42.50, { currency: 'JPY' })  // was 'quarenta e dois ienes e cinquenta sen'
                                          //   — a Portuguese-language "sen", invented
                                          //   → now RangeError

  This one is reachable on main today — pt-BR accepted a free-form currency and has real
  Japanese vocabulary, so the call above genuinely returns that string on 5.1.2. It is listed
  here rather than under Breaking changes for the same reason fix: reject fractional amounts for currencies with no minor unit, and unbreak the docs generator #430 shipped as a fix:: spelling
  a subunit that hasn't existed since 1953 is a defect, not behaviour to preserve. If you call
  pt-BR with a fractional JPY/KRW/VND/IRR/IDR amount, round first.

• pt-BR can now name JPY ('cem ienes'), and the 30 languages in §1b now accept their own
  currency code explicitly instead of throwing.

• Every currency-exporting language now exports currencyDefaults.currency and
  currencyValues.currency, so the supported set is machine-readable per language.

• LANGUAGES.md gained a generated currency-coverage table.

---

How was this tested?

• npm test → 762 tests passed vs. 453 on main (+309 — see the Verification
  subsection under The core change for the file-by-file breakdown; three
  brand-new gate files account for most of it).
• npm run lint → clean (eslint + markdownlint)
• Differential sweep against main in a scratch worktree: every language × every exported
  form × a value battery, plus 8 currency-option probes per currency language. All 1,176
  behavioral differences were triaged against main as it stood at abd02f2; every one falls
  into §1 above or into the guard fix: reject fractional amounts for currencies with no minor unit, and unbreak the docs generator #430 has since landed. The sweep is how §1a/§1b were found —
  neither was in the original commit footer. The language-layers work
  re-ran this exact sweep against main again on its own (same 1,176, nothing new), and
  separately re-ran a step-by-step version within the branch after each structural change; see
  its own verification section for both.
• Release-notes render — git-cliff --bump --unreleased run against the amended history
  to confirm the breaking section comes out complete (see below).

New gates specifically:

• currency-vocab-contract.test.js — every code in a language's currencyValues.currency
  must have a matrix entry, every advertised currency's minor-unit rendering is exercised,
  every 1000-subunit currency survives the three-decimal round trip, and (added with the
  language-layers work) a gender-sensitive language's majorGender/minorGender fields are
  present on every entry, not just the one that happened to need it first.
• bare-tag-contract.test.js — single-variant families must have an alias; aliases must be
  reference-identical to their target and point inside their own family; a locale profile
  (variantOf) is excluded from counting as a family's canonical variant, so a bare tag can't
  resolve to one.
• variant-profile-contract.test.js — a locale profile's toCurrency with no options must
  match calling its base explicitly with the profile's own default currency, the specific trap
  a profile that regressed to a pure export * would fall into.

Docs audited against the source, not just re-read. Every structural and behavioral claim in
docs/bare-tag-aliases.md was re-derived by script (counts, family split, alias targets,
reference identity, file shape, form parity) and every rationale claim re-run (zh/sr/am
script pairs, pt-BR vs pt-PT scale systems, en-IN lakh/crore, es-* divergence). One
error found and fixed in 8dbba06: the doc credited es-MX and es-US with diverging from
es-ES in cardinal ceiling, but es-MX carries the same 10³⁰ ceiling — only es-US stops
lower, at 10²¹. Everything else in both currency and alias docs verified accurate.

Release-notes footer

Resolved. The BREAKING CHANGE: footer on the feat(core)! commit declares the three
cases above. Two problems were fixed there:

1. It was silently truncated. The old footer's fourth line began zero-exponent: ja-JP (JPY), … — and the conventional-commit parser reads a line starting with word: as the
   start of a new footer. Everything from that line on was dropped. The generated
   BREAKING CHANGES section literally ended mid-sentence at "whose own currency is", with
   no warning from git-cliff or commitlint. Confirmed with a probe commit: blank lines and
   - bullets survive the parser; a line-initial token: does not.
2. It under-declared the surface — only the zero-exponent guard and §1c were described.
   §1a and §1b were found by the differential sweep, after that footer was written.

The footer's first item described the zero-exponent guard. That shipped in #430 as a fix: and
is on main, so it has been dropped from the footer rather than declared twice; what remains of
it there is the cross-language reach noted under Non-breaking improvements.

Verified on the amended history: git-cliff --bumped-version → v6.0.0 (the ! in
feat(core)!: carries it; see below), and git-cliff --bump --unreleased renders the remaining
cases in full.

One thing this leaves open: if v5.1.3 is cut from main before this lands, #430's guard
reaches users in that release. If v6.0.0 is the next release instead, it carries both, and the
guard appears in the changelog under Bug Fixes rather than Breaking Changes.

One correction to something I said earlier in this PR's history: the footer is not what
triggers the major bump — the ! in feat(core)!: does that on its own. The footer only
supplies the description text. So the truncation was never going to ship a wrong version
number; it was going to ship an accurate 6.0.0 with a changelog that stopped mid-sentence.

Related Issue

📚 Adding a language or a breaking change? See CONTRIBUTING.md.

[TylerVigario]

Pushed proto/form-split — worth a diff.

A page that spells prices, one language one currency:

main    7,608 B
#428    9,033 B
branch  4,135 B

Less than half. Two reasons. Forms are separate modules, so importing toCurrency can't drag cardinals and ordinals along. And currencies are named exports rather than object properties, so you ship dollar, cent instead of all fifteen — Terser drops unused bindings, never unused properties. A second currency costs 81 bytes.

Same change collapsed the thirteen western English files into one. The and-flag as an option instead of variantOf inheritance: 1,014 comparisons against main, zero differences, en-CA included.

node bench/shape-compare.js builds all three and prints it.

Caveat: one language of fifty, gates fail, thirteen fixtures orphaned. Numbers to check, not code to merge.

[TylerVigario]

Separately — the parts I'd merge on sight: the zero-exponent guard, the three-decimal currency support, and the TypeScript 7 generator fix. The guard especially; toCurrency(0.99) returning "zero won" on 5.1.2 is real data loss and I reproduced it in four languages.

Only wish is they'd come in separately. At 191 files the good bits end up waiting on the parts still being argued about.

[forzagreen]

Tyler — you're right about the split, and I've done it. Both are merged and this PR is rebased on them.

• fix: reject fractional amounts for currencies with no minor unit, and unbreak the docs generator #430 — zero-subunit currency guard + the typescript@7 generator fix. 8 files, +139/−131. The guard especially: I reproduced all five, and ja-JP was worse than the four you found — it spells 銭, demonetised in 1953, so it's wrong rather than merely lossy.
• build(esm): emit one bundle per form so a CDN page pays for what it uses #431 — per-form CDN bundles, against main, independent of this PR.

On proto/form-split

I rebuilt all three trees with your harness settings. Your numbers reproduce exactly — main 7,608, this PR 9,033, your branch 3,919 (your comment says 4,135; the commit message's 3,919 is the one that reproduces). So the disagreement is about what to do, not about the measurement.

What made me split it in two is where the saving actually comes from:

#428, all three forms, one file      9,033 B
#428, pruned to toCurrency           5,169 B   ← −3,864 B: per-form split
proto/form-split toCurrency          3,919 B   ← −1,250 B: named-export currencies
main, pruned to toCurrency           3,742 B

76% of it is the per-form split, which has nothing to do with how currency is represented. That's #431, and it's yours — it stands on main today without any of this PR. Measured off a real npm run build: en-US 7,778 → 4,293 / 3,815 / 3,827, so −45% / −51% / −51%.

With #431 in, the two branches land here:

form	this PR + #431	proto/form-split	gap
cardinal	4,291 B	~4,239 B	52 B
ordinal	3,815 B	~3,775 B	40 B
currency	5,252 B	~4,011 B	1,241 B

Two of three forms are within noise. The whole argument is one cell — and it isn't machinery. I stubbed the matrix down to a single currency, keeping this PR's exact code shape and string API: 4,069 B. So the option plumbing costs ~327 B against your ~177 B, and the other ~1,100 B is data — the 21 English currency vocabularies a caller didn't ask for.

Where I still disagree

You're right that CURRENCY_VOCAB[currency] plus Object.keys(...) pins the object, and that Terser drops bindings but never properties. That's real and I'm not arguing it.

But string-keyed selection and per-currency tree-shaking are mutually exclusive, and the string is doing work your benchmark doesn't measure. An invoicing app picks currency from data — row.currency is 'KES', not an identifier it can import. With named exports that needs a code → binding map, which pins everything again, so the advantage disappears in exactly the multi-currency case this PR exists to serve. Intl.NumberFormat(locale, { currency: 'KES' }) takes a string for the same reason.

One thing your numbers don't price: your branch deletes en-KE, en-AU and eight other public entry points that this PR keeps working as profiles. Some of the win is deleted API, and that's a separate decision with its own migration cost.

Where this leaves us

#430 and #431 are on main; this PR is rebased onto both and green. The fractional-amount
RangeError is no longer declared as a breaking change here — it shipped in #430 as a fix:,
so main already throws and re-declaring it would double-count. This PR's BREAKING CHANGE:
footer is down to the three currency-option cases.

Release plan: cut v5.1.3 from main first so the guard reaches everyone on ^5 without
waiting on this, then merge this and cut v6.0.0.

On the last 1,100 B

One correction to what I wrote above — I said "strings keep working", and that was too
generous to my own proposal. In a shape that actually tree-shakes, { currency: 'KES' } has to
stop working: a bare string as the option value is precisely what pins the table. Strings would
only survive one level out, at byCode['KES']. So that isn't a middle path, it's your design
with a string escape hatch, and I should have said so.

Which makes it worth measuring rather than arguing. What I'd want to see before committing
either way: the three bundle sizes, and what happens to currencyValues — the allowed-set enum
is what makes a typo'd 'KSE' throw RangeError listing valid codes, and it's documented as
introspectable API. With vocab objects there's no set to validate against, so that contract
changes shape and currency-vocab-contract.test.js goes with it.

If the numbers land near the 4,069 B floor and the enum survives in some form, I'll take it.
If preserving it costs the saving, I'd rather keep the string API and the validation and pay the
1,100 B. Either way this PR can land first — it's a non-breaking change afterwards.

Happy for you to own that follow-up if you'd prefer.