TIP NumberPlugin is not installed on Foswiki.org.


Localized Number Formatter and Currency Converter

This plugin allows to format

  • numbers,
  • currencies and
  • percentages

in a localized way using the Unicode CLDR.

It also allows to convert currencies using an online exchange rates service. Supported services are:

All of these services require an API key/id to be downloaded by registering for an appropriate service level. Up-to-date exchange rates will then be downloaded and cached for a specific time, e.g. refreshing rates once a day.


For example, a number such as 1234 is formatted differently depending on the locales

Number Type Locale Parameter Output
1234.00 number en_US   1,234
    de_DE   1.234
    ar   ١٬٢٣٤
    es   1234
1234.00 currency en_US currency="USD" $1,234.00
  currency de_DE currency="EUR" 1.234,00 €
  currency ar currency="AED" د.إ.‏ ١٬٢٣٤٫٠٠
  currency ar currency="USD" US$ ١٬٢٣٤٫٠٠
  currency es currency="EUR" 1234,00 €
0.1234 percent en_US   12%
    de_DE   12 %
    ar   ١٢٪
    es   12 %
    en_US minimum_fraction_digits="1" 12.3%
12.34 currency de_DE currency="EUR" from="USD" 10,32 €



By default, numbers are formatted by the %NUMBER{"value" param="..."}% macro

Parameter Description Default
type specifies what kind of number this is and will use the related formatter for it, can be number, currency, percent or bytes number
locale unicode locale identifiers, for example es (Spanish), es_ES (European Spanish), es_419 (Latin American Spanish), zh_Hant (Traditional Chinese), zh_Hans (Simplified Chinese), chr (Cherokee) current locale of the user's session
decimal_sign delimiter of fraction see current locale
group_sign delimiter every three digits in large numbers see current locale
plus_sign example + see current locale
minus_sign - see current locale
infinity see current locale
nan NaN see current locale
pattern pattern how to format a number, for example #,##0.### see current locale
minimum_integer_digits   see current locale
Parameters for currency:
currency / currency_code / to this parameter is required when the type is set to currency; possible values are any 3-letter digits according to ISO 4217, such as EUR or USD  
currency_sign the sign that is used to identify the currency see current locale
cash for boolean switch to enable rendering of "cash money" which may be formatted differently for some locales off
from specify the source currency which is converted to the target currency as specified in the currency parameter using an online exchange rates service same as source currency
Parameters for percent:
permil   0
percent_sign   %

Further documentation is available at CLDR::Number, the perl library being used underneath.

In addition to the %NUMBER macro you may specify a list of currency codes as a shortcut for the given type of number. The configuration setting stored in $Foswiki::cfg{NumberPlugin}{Currencies} will specify the list of those which a macro should be created for. For example a setting such as

$Foswiki::cfg{NumberPlugin}{Currencies} = "EUR, USD";

will create the macros %EUR{...}% and %USD{...}% as a shortcut for

%NUMBER{"..." type="currency" currency="<code>"}%


This macro lists all available currencies as well as their exchange rate using an online exchange rates service.

Parameter Description Default
"..." / total the total amount that the rates are computed for 1
base base currency to with all rates are calculated base rate of the currency provider
header format string preceeding the output list  
footer format string appended to the output list  
separator list separator ,
format format string used for every item in the list of available currencies $code
include regular expression that a currency code must match to be included in the output  
exclude regular expression that a currency code must not match to be included in the output  

The format parameter accepts a couple of variables that are expanded accordingly:

  • $code the international currency code (USD, EUR, ...)
  • $rate exchange rate vs the base currency
  • $total total value of the currency converted to the current currency in the loop

Formfield types

This plugin defines three additional formfield types that may be used defining DataForms.

  • currency
  • number
  • percent

Parameters are specified in the Values column of the formfield, i.e. the formfield type "currency" requires a currency="..." parameter such as in:

| *Name*           | *Type*   | *Size* | *Values*            | *Description* | *Attributes* | *Default* |
| Advance Payments | currency | 30     | currency="EUR" |               |              | 0         |

Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. "Extensions Operation and Maintenance" Tab -> "Install, Update or Remove extensions" Tab. Click the "Search for Extensions" button. Enter part of the extension name or description and press search. Select the desired extension(s) and click install. If an extension is already installed, it will not show up in the search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)
cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See https://foswiki.org/Support/ManuallyInstallingExtensions for more help.



Change History

05 May 2022 reimplement caching using Foswiki:Extensions/CacheContrib; default to no currency provider for exchange rates; load currencies lazily for better init performace; improved number format "bytes"
15 Mar 2021 added back {Currencies} setting as documented
05 Mar 2018 added support for CurrencyLayer
18 Sep 2017 added support for exchange rates; made compatible with SpreadsheetPlugin
03 Jan 2017 initial release

PackageForm edit

Author Michael Daum
Version 6.00
Release 05 May 2022
Description Localized Number Formatter and Currency Converter
Copyright 2017-2022 Michael Daum
License GPL (GNU General Public License)
Home https://foswiki.org/Extensions/NumberPlugin
Support https://foswiki.org/Support/NumberPlugin
Repository https://github.com/foswiki/NumberPlugin
ExtensionClassification Multilingual and Locality
ExtensionType PluginPackage
DemoUrl http://
SupportUrl NumberPlugin
ModificationPolicy CoordinateWithAuthor
I Attachment Action Size Date Who Comment
NumberPlugin.md5md5 NumberPlugin.md5 manage 159 bytes 05 May 2022 - 12:52 MichaelDaum  
NumberPlugin.sha1sha1 NumberPlugin.sha1 manage 183 bytes 05 May 2022 - 12:52 MichaelDaum  
NumberPlugin.tgztgz NumberPlugin.tgz manage 10 K 05 May 2022 - 12:52 MichaelDaum  
NumberPlugin.zipzip NumberPlugin.zip manage 17 K 05 May 2022 - 12:52 MichaelDaum  
NumberPlugin_installerEXT NumberPlugin_installer manage 4 K 05 May 2022 - 12:52 MichaelDaum  
Topic revision: r4 - 05 May 2022, MichaelDaum
The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License    Legal Imprint    Privacy Policy