Ideas for v4, toCurrency, language codes...

[forzagreen]

I'm creating this discussion for brainstorming ideas and designing the future v4 of n2words.

Main features:

• Language codes with BCP 47 standard
• Add ordinal numbers
• Add currencies
• Add more languages and more variants

Refs: #228, #261 (comment)

[TylerVigario]

One thing that bugged me was the per-function web importing, but I eventually realized it would require another major ground-up refactor — splitting the language files into individual function/method files and sharing helpers across them. Definitely not impossible, but I felt the current language file size was good enough for release. Still something I'd like to revisit though.

[forzagreen]

Concerning language codes and currencies

Currencies

In my opinion, we must completely separate currencies from languages. Currencies apply to countries, not to languages.

We should have a matrix of countries and their official currencies, their name in the country's official language, and in other languages.

For example: the United Kingdom (country code: GB) has the currency Sterling (symbol: £; currency code: GBP). The country's main language is English (code: en). The currency name in English is pound sterling. We should (optionally?) also have the currency name in other languages: fr:livre sterling, ar:جنيه إسترليني, es:libra esterlina...

With this matrix of countries/currencies names in the country language and other languages, an amount of money from any country can be expressed in any language.

Language codes

The BCP 47 standard is composed of 2 documents:

• RFC 5646 defines the syntax for building language tags (like fr, ar-MA or zh-Hant-TW);
• RFC 4647 defines how to match and filter those tags against a user's language preferences.

Regarding language codes, we should prefer generic tags like en/fr/ar. They are totally correct BCP 47 tags. The differences between countries are minor and don't justify making the region/country code mandatory.

Moreover, we should not consider variants of a language (en-GB, en-US...) as different languages. For example, English is an official language in ~60 countries; we could not claim that we support ~60 more languages. The same applies to all major languages like French, Spanish and Arabic. (NB: I saw some similar libraries inflating the number of supported languages by counting variants).
Also, in most cases, there are no differences between the variants. In the rare case where there is a difference, I tend to prefer using the country code as an option rather than an independent language (I hesitated when fr-BE was added here).

[TylerVigario]

Thanks for the thoughtful write-up on this — always appreciate you taking the time to think through the design.

On currencies

I see the appeal of a country/currency/language matrix, but I think it's solving a real problem with too heavy an abstraction. Currency naming is inherently linguistic — how you pluralize "dollar," where you place the amount, how you join dollars and cents — that's all grammar, not geography. Building a full CLDR-style matrix is well outside the scope of what n2words should be. For the cross-locale case (e.g. expressing GBP in French), I think that's better handled as an optional currency override rather than a fundamental redesign.

On language codes

I agree that bare tags like en and fr are valid BCP 47 — but so are our region-specific tags. en-US, fr-BE, zh-Hans-CN — these aren't some custom convention we invented. They're fully valid, widely recognized BCP 47 tags used everywhere from HTTP Accept-Language headers to Intl APIs to every major i18n framework (ICU, CLDR, gettext, you name it). When a browser sends Accept-Language: fr-BE, it's not being redundant — it's being precise. We're just following the same standard the rest of the ecosystem uses.

And that precision matters here. Regional variants aren't cosmetic — fr-FR vs fr-BE have fundamentally different vocabulary (soixante-dix vs septante), pt-BR vs pt-PT diverge significantly, and zh-Hans-CN vs zh-Hant-TW are different scripts entirely. These aren't inflated language counts, they're genuinely distinct implementations. Collapsing them into a single fr or zh would mean losing correctness.

That said, supporting bare tags like en or fr as aliases that resolve to a sensible default variant is something we could consider. And there is a fair criticism to be made about duplication across regional variants that share most of their logic (e.g. the en-* family). That's a real maintenance cost we're aware of, and something we can address at the implementation level — shared internals, base modules, that sort of thing — without needing to restructure the public API.

[forzagreen]

Thank you too for the ideas.

On currencies, I agree that handling all languages is overkill (or maybe not — probably it's one prompt away :D) and indeed we must focus on the country's main language.

On language codes, we may consider a mix:

1. en-* family (respectively ar-* family): same logic => cardinal and ordinal functions accept en, en-US, en-GB, and any valid en-* code (resp. ar, ar-*).

2. zh-* family (respectively pt-* family): very different => we reject zh (resp. pt) with an explicit error. We only accept codes zh-Hans-CN and zh-Hant-TW (resp. pt-BR and pt-PT).

3. fr-* family: this is a grey area. My personal opinion is that fr should default to fr-FR since this is the most used variant in the world, and I don't think this would be contested. Forcing regions as fr-FR and fr-BE is also fine and has valid arguments.

What do you think @TylerVigario ?

[TylerVigario]

I like the tiered approach in theory, but I think it has a fundamental blind spot: none of the tiers account for toCurrency.

Tier 1 (en-*): Cardinal and ordinal are identical across regions, sure. But toCurrency is completely different — en-US gives you dollars, en-GB gives you pounds, en-IE gives you euros. So what does toCurrency('en') return?

Tier 2 (zh-*, pt-*): You reject the bare tag, which is correct — but the reason isn't just cardinal/ordinal differences. zh-Hans-CN uses CNY, zh-Hant-TW uses TWD. pt-BR uses BRL, pt-PT uses EUR. The region is required regardless.

Tier 3 (fr-*): Defaulting fr → fr-FR sounds reasonable until you realize you're silently defaulting to EUR. A fr-CH user gets Swiss francs, fr-CA gets Canadian dollars. Picking a default currency on their behalf is a bug, not a feature.

So across all three tiers, the region is required for toCurrency to produce correct output. At that point, what are we actually gaining by making it optional for cardinal and ordinal? An inconsistent API where the region is "optional, except when it isn't." That's more confusing for users, not less.

I think we're going in circles a bit here — every shortcut we look at runs into the same wall. The region code is the region code because it encodes information we actually need. On the duplication side though, totally agree that's worth addressing with shared internals between variants.

[forzagreen]

First, a clarification: the 3 options I suggested apply only to cardinal and ordinal functions, not to currencies.

I'd like to emphasise a fundamental point: currencies must be handled separately from cardinal/ordinal functions. Unlike cardinal/ordinal, which depend only on a language in most of the cases, currencies depend on both a country and a language. toCurrency('en') would logically return an error because a language doesn't have a currency. toCurrency('fr') should fail and not default to EUR.

Having a distinct API for toCurrency is not a problem.

Let's remember that the core purpose of n2words is to convert numbers to words. With that in mind, I have doubts about the relevance of adding currency support to the package at all. It's a nice-to-have feature, but it's more of a convenience function that uses n2words capabilities rather than a core feature. It should not drive the design of the main API.

[TylerVigario]

Just to circle back — the three tier examples in my previous reply weren't only about toCurrency. Regional differences exist in cardinal and ordinal too. fr-BE uses septante/nonante where fr-FR uses soixante-dix/quatre-vingt-dix — that's toCardinal, not currency. So even scoping bare tags to cardinal/ordinal only, the region still matters for correctness in some language families.

You mentioned "having a distinct API for toCurrency is not a problem" — I'd genuinely like to understand what that looks like. A separate function signature? A different import path? Something else entirely? It's hard for me to evaluate the idea without seeing what you have in mind.

On whether toCurrency belongs in the library — I really think it does. Converting numbers to words is what we do, and "one hundred dollars and fifty cents" is exactly that. The most popular number-to-words libraries — num2words (Python), number-to-words (PHP) — all include currency support and use region-specific locale codes. It's standard for the category. It's already implemented across all 71 languages and working. I'm absolutely open to discussing the how, but at this point removing it would mean undoing a significant amount of tested, working code without a clear reason to.

I think we're closer than it feels. But to move forward I need something concrete to work with — what does your ideal v4 API actually look like? Even rough code examples or pseudocode would go a long way. If there's a better approach that holds up under the edge cases, I'm genuinely all for it. I just need to see it.

[forzagreen]

Indeed, we are closer than it feels. I suggest we release v4 as it is today, in order to make all its great features available. For the implementation details concerning currency and language codes, I'll take time to come up with a design and a pull request to be released later. Sounds good ?