to - words
Overview
The to-words used to convert numbers into words with currency formatting enabled. This configuration is particularly useful for financial applications where amounts need to be represented in words.
Documentation
Typical usage scenario
To Words turns a number into the words a person would write by hand — and, in currency mode, into a properly formed amount in words for the locale you choose. Give it 9876.45 with locale en-GB and currency mode on, and it returns "Nine Thousand Eight Hundred Seventy Six Pounds And Forty Five Pence Only". Hand the same kind of figure to en-IN and it counts in lakh and crore: 12345678.99 becomes "One Crore Twenty Three Lakh Forty Five Thousand Six Hundred Seventy Eight Rupees And Ninety Nine Paise Only".
Use it wherever a figure has to appear as text as well as digits:
• Amount in words on cheques and payment instructions. Banking and payables screens almost always need the written form beside the numeric one, complete with the trailing "Only" that makes the amount tamper-evident.
• Invoices, purchase orders and credit notes. Render the total in words in the document header or footer, in the buyer's locale, without hard-coding a currency name.
• Legal and contractual documents. Contracts, deeds, promissory notes and loan agreements conventionally spell out sums; generate that text from the same value the rest of the document uses.
• Receipts and order confirmations. Show the paid amount in words on a printed receipt or in a confirmation email body.
• Read-aloud and accessibility contexts. A written-out amount is unambiguous for a screen reader or a text-to-speech step, where "1,234.56" can be read in several ways.
• Indian-numbering and multilingual apps. The lakh/crore grouping and the Hindi, Marathi, Gujarati, Urdu, Persian, Korean, Turkish, Spanish, Portuguese, French, Dutch (Suriname) and Estonian locales all come out of the same action — a parameter change, not a second implementation.
Features and limitations
• Client-side only. It runs in a nanoflow and cannot be called from a server-side microflow.
• Currency mode rounds to two decimals. 1.999 becomes "Two Pounds Only". Rounding happens before conversion, so the words can differ from the stored value.
• Plain mode wording differs from currency mode. In plain mode 123.45 reads "One Hundred Twenty Three Point Forty Five"; in currency mode "One Hundred Twenty Three Pounds And Forty Five Pence Only". Pick the mode that matches the document.
• Double-precision limits apply. The value passes through a JavaScript number, so integers beyond roughly 9,007,199,254,740,992 lose precision.
• Locale codes are exact and case-sensitive. en-in and nl-NL both raise Unknown Locale. There is no fallback and no matching on language alone.
• The symbol parameters have no effect on the output. They are accepted but never reach the generated words. Since 2.1 the name values are used as the singular forms.
• Custom currency naming needs all four names. Supply the currency name, its plural, the fractional-unit name and its plural, or the override is ignored and the locale defaults apply.
• fa-IR, tr-TR and ko-KR are sparse. fa-IR and tr-TR define no plural or singular major-unit name and ko-KR defines no fractional unit, so their currency output is terser than the English locales'.
• One direction only. Numbers to words — no words-to-number parsing, no ordinals, no digit grouping, no currency symbol formatting.
Dependencies
• Mendix Studio Pro 10.24.17 or higher.
• No Marketplace module dependencies.
Installation
1. In Studio Pro 10.24.17 or higher, open App Explorer > Import module package and select to_words.mpk.
2. Run Update project directory if prompted.
3. In a nanoflow, add a JavaScript action activity and choose to_words from the module.
4. Open the Example nanoflow to see a working call — add a Show message to see its output.
Configuration
Locale. Pass an exact code from the table above. Prefer an explicit locale: an empty string now falls back to en-IN rather than throwing, but relying on that is fragile — pass a literal, a constant or a profile attribute you know is populated.
Currency mode and decimals. For any monetary figure, use currency = true — it routes the value through toFixed(2) and applies the locale currency naming.
Custom currency naming. Set currencyOptions to true only when the locale's own currency is wrong for your case — for instance an English-language app invoicing in a currency the bundled locales do not carry. Then fill at least the four name strings — currency name, currency plural, fractional-unit name and fractional-unit plural. If any of those is left empty the override is ignored and the locale defaults apply, rather than blanking the names as it did before 2.1. Since 2.1 the name values also serve as the singular forms, so a value of 1 reads "One Pound Only". The symbol parameters are accepted but never reach the words.
Recommended pattern
1. Wrap the action in a small nanoflow, AmountToWords, taking a Decimal and returning a String.
2. Inside it, pass the locale from a constant and fix currency = true, ignoreDecimal = false, ignoreZeroCurrency = false, doNotAddOnly = false, currencyOptions = false and six empty strings.
3. Call that nanoflow from your page, or from a microflow via the nanoflow, and store the result on the invoice or payment entity so the printed document and the audit trail agree.
4. If the words must match a rounded total exactly, round the Decimal to two places in your own logic first rather than relying on the converter's rounding.
Known bugs
None
Frequently Asked Questions
Can I call it from a microflow?
No. It is a JavaScript action, so it runs client-side in a nanoflow. Call that nanoflow from your microflow.
Can I add a locale that is not on the list?
Not through the action. Codes are matched exactly against the bundled set and an unknown code throws Unknown Locale. Adding one means adding a locale file to the bundled library and rebuilding the module.
Can I use my own currency name?
Yes, with currencyOptions = true. Supply at least the currency name, its plural, the fractional-unit name and its plural; since 2.1 the names double as the singular forms, so a value of 1 reads "One Pound Only". The symbol parameters are accepted but never appear in the words.
How are decimals handled?
In currency mode the value is rounded to two decimals and the fraction is read as the sub-unit ("And Thirty Six Pence"). In plain mode it is read as digits ("Point Thirty Six"). Both work correctly from 2.1 onward.
Which Studio Pro versions are supported?
10.24.17 and higher. Converted from 9.24.22 for the 10.24.17 LTS line.
Issues, suggestions and feature requests:
Releases
**To Words** — Studio Pro **10.24.17**
### Fixed
**Decimals were dropped from positive numbers in non-currency mode.** `123.45` returned "One Hundred Twenty Three" and `0.45` returned "Zero". Mendix passes Decimal parameters as `big.js` objects, and the library decides whether a number has a fractional part with `Number(n) === n`, which is false for an object. The value is now coerced to a primitive before conversion.
Verified against the bundled library:
| Input | Before | After |
|---|---|---|
| 123.45 | One Hundred Twenty Three | One Hundred Twenty Three Point Forty Five |
| 0.45 | Zero | Zero Point Forty Five |
Negative values and currency mode were unaffected and behave as before.
**Custom currency names read as plural at a value of 1.** The action never set `singular`, so a custom-named currency produced "One Pounds Only". `singular` is now derived from the name, giving "One Pound Only".
**Blank custom currency names produced malformed output.** Enabling custom names with fields left empty overwrote the locale's own names with empty strings, giving output such as "Four Hundred Fifty Two And Thirty Six Only". The override is now applied only when the currency name, plural, fractional-unit name and fractional-unit plural are all supplied; otherwise the locale defaults apply. This also avoids a crash, since the library reads `currencyOptions.fractionalUnit.plural` unconditionally.
**An empty locale code threw "Unknown Locale".** Required String parameters arrive as `""` rather than unset. An empty locale now falls back to `en-IN`.
These defects predate the 10.24.17 upgrade. **Upgrading is recommended.**
### Known remaining behaviour
- Locale codes are case-sensitive — `en-in` throws, `en-IN` works.
- Currency mode rounds to two decimal places.
- Values above 2^53 lose precision.
### Notes
27 locales bundled. Studio Pro 10.24.17, imports with 0 errors. Import `to_words.mpk` via *App Explorer > Import module package*.