5.14. The numbertext FreeMarker function (for advanced users)

The numbertext function is a custom FreeMarker function implemented in Fanurio that allows you to write numbers and money amounts in words. It's useful when the total of an invoice must also be written in words, as some tax offices require. It works as a wrapper around the libnumbertext library, the same library used by the NUMBERTEXT and MONEYTEXT functions of LibreOffice Calc.

You can try libnumbertext online to see how a number or a money amount is written in words before using it in a template.

The text returned by the function can be changed further with FreeMarker built-ins like ?cap_first, ?upper_case or ?replace.

${numbertext(42)}
${numbertext(invoice.total)}

For an invoice with a total of €1,500.60 and an English client, the above placeholders produce the following texts:

forty-two
one thousand five hundred euro and sixty cents

5.14.1. Parameters

The numbertext function has the following parameters. Only the first one is mandatory:

${numbertext(value)}
${numbertext(value, language)}
${numbertext(value, language, currency)}

Value

The value parameter is mandatory and it specifies the number or the money amount that is written in words. A number is written as a number. A money amount like invoice.total or invoice.balance is written with its currency, both the units and the subunits (e.g. euros and cents).

The following examples assume an invoice with a total of €1,500.60 and an English client:
```
${numbertext(42)} → forty-two
${numbertext(1.5)} → one point five
${numbertext(invoice.total)} → one thousand five hundred euro and sixty cents
```
Language

The language parameter is optional and it specifies the language of the text. By default, it's the language of the template, which for invoices is the client's locale. The language is a language code like en, es, fr, de or lt, optionally followed by a country code like en_GB, which writes "one hundred and twenty" instead of "one hundred twenty".

The following examples write an invoice total of €1,500.60 in Lithuanian, Spanish and French:
```
${numbertext(invoice.total, "lt")} → vienas tūkstantis penki šimtai eurų ir šešiasdešimt euro centų
${numbertext(invoice.total, "es")} → mil quinientos euros con sesenta céntimos
${numbertext(invoice.total, "fr")} → mille-cinq-cents euros et soixante centimes
```
All the languages supported by libnumbertext can be used. Fanurio is tested in English, Spanish, French and Lithuanian. The other languages are written as libnumbertext writes them. You can find them in the list of libnumbertext languages.
Currency

The currency parameter is optional and it specifies a currency as an ISO 4217 code (e.g. EUR, USD, MXN). If the value is a number, the currency writes it as a money amount. If the value is a money amount, the currency must be the same as its currency.
```
${numbertext(1500, "en", "EUR")} → one thousand five hundred euro
```

5.14.2. Writing the invoice total in words

By default, a money amount is written entirely in words, both the units and the subunits. If you need the subunits as digits (e.g. "60 ct" or "60/100"), write the whole part of the amount in words and add the subunits yourself:

amount?int is the whole part of the amount (1500 for 1,500.60). Write it in words with numbertext and the currency of the amount.
(amount?abs * 100 % 100)?string("00") is the subunits as two digits (60 for 1,500.60).

The following example writes the total of an invoice in Lithuanian with a capital first letter and the cents as digits:

[#assign amount = invoice.total.amount]
${numbertext(amount?int, "lt", "EUR")?cap_first}, ${(amount?abs * 100 % 100)?string("00")} ct

For an invoice total of €1,500.60 it produces the following text:

Vienas tūkstantis penki šimtai eurų, 60 ct

The following example writes the total of an invoice in Mexican Spanish in upper case, as it's done on many Mexican invoices. libnumbertext writes the full name of the currency (pesos mexicanos) to distinguish it from other pesos so the ?replace built-in is used to shorten it:

[#assign amount = invoice.total.amount]
${numbertext(amount?int, "es", "MXN")?replace(" mexicanos", "")?replace(" mexicano", "")?upper_case} ${(amount?abs * 100 % 100)?string("00")}/100 M.N.

For an invoice total of MX$5,600.00 it produces the following text:

CINCO MIL SEISCIENTOS PESOS 00/100 M.N.

For a credit note, the whole part is negative and it's written with the language's word for minus (e.g. "minus penki eurai" in Lithuanian). The subunits stay positive. For a currency without subunits (e.g. JPY), leave the subunits out.

5.14.3. Errors

If a value can't be written in words, the function stops the template with an error message that starts with "numbertext:". For example:

the language isn't supported by libnumbertext
the currency isn't supported in that language (e.g. the French rules don't have the Mexican peso)
the currency parameter doesn't match the currency of the money amount
the number is too large for the language

If a number or a currency is written incorrectly in your language, please contact us.