Working with Locales

Numeral.js has robust support for internationalization, allowing you to format numbers according to different language and country conventions.

Setting the Locale

You can set the active locale globally using numeral.locale(). All subsequent calls to .format() will use this locale's rules.

// Load a locale (in a real app, you would include the locale file)
numeral.register('locale', 'fr', {
    delimiters: {
        thousands: ' ',
        decimal: ','
    },
    abbreviations: {
        thousand: 'k',
        million: 'm',
        billion: 'b',
        trillion: 't'
    },
    ordinal : function (number) {
        return number === 1 ? 'er' : 'e';
    },
    currency: {
        symbol: '€'
    }
});

// Switch to the French locale
numeral.locale('fr');

var number = numeral(1234.56);

// Format using French rules
console.log(number.format('0,0.00 $')); // '1 234,56 €'

Registering Locales

To make a locale available, you must first register it using numeral.register('locale', ...). The library comes with many pre-built locale files in the /locales directory.

In a browser environment, you would include the desired locale file after numeral.js:

<script src="numeral.min.js"></script>
<script src="locales/fr.min.js"></script>
<script>
  numeral.locale('fr');
</script>

Creating a Custom Locale

If you need a format not provided by the library, you can easily define your own locale.

A locale definition is an object with the following properties:

  • delimiters: An object with thousands and decimal separator characters.
  • abbreviations: An object with strings for thousand, million, billion, and trillion.
  • ordinal: A function that takes a number and returns the appropriate ordinal suffix.
  • currency: An object containing the currency symbol.

Here is the structure for a fictional 'numland' locale:

var numlandLocale = {
    delimiters: {
        thousands: '|',
        decimal: '^'
    },
    abbreviations: {
        thousand: 'k',
        million: 'm',
        billion: 'b',
        trillion: 't'
    },
    ordinal: function (number) {
        return 'th';
    },
    currency: {
        symbol: 'N$'
    }
};

// register your custom locale
numeral.register('locale', 'numland', numlandLocale);

// use it
numeral.locale('numland');
numeral(1234.56).format('$0,0.00'); // 'N$1|234^56'

Available Locales

Numeral.js comes with the following locales built-in or available as separate files:

  • bg (Bulgarian)
  • chs (Chinese, Simplified)
  • cs (Czech)
  • da-dk (Danish - Denmark)
  • de-ch (German - Switzerland)
  • de (German)
  • en-au (English - Australia)
  • en-gb (English - Great Britain)
  • en-za (English - South Africa)
  • en (English - US, default)
  • es-es (Spanish - Spain)
  • es (Spanish)
  • et (Estonian)
  • fi (Finnish)
  • fr-ca (French - Canada)
  • fr-ch (French - Switzerland)
  • fr (French)
  • hu (Hungarian)
  • it (Italian)
  • ja (Japanese)
  • lv (Latvian)
  • nl-be (Dutch - Belgium)
  • nl-nl (Dutch - Netherlands)
  • no (Norwegian)
  • pl (Polish)
  • pt-br (Portuguese - Brazil)
  • pt-pt (Portuguese - Portugal)
  • ru-ua (Russian - Ukraine)
  • ru (Russian)
  • sk (Slovak)
  • sl (Slovenian)
  • th (Thai)
  • tr (Turkish)
  • uk-ua (Ukrainian)
  • vi (Vietnamese)