CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-numeral

A javascript library for formatting and manipulating numbers.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

localization.mddocs/

Localization

Multi-locale support with 35 built-in locales and customizable number formatting rules including thousands separators, decimal points, currency symbols, and abbreviations. Each locale defines how numbers should be formatted and provides culture-specific currency and ordinal rules.

Capabilities

Locale Management

/**
 * Get or set the current locale
 * @param key - Optional locale code to set as current locale
 * @returns Current locale code (lowercase)
 */
numeral.locale(key?: string): string;

/**
 * Get locale data for current or specified locale
 * @param key - Optional locale code to get data for
 * @returns Locale configuration object
 * @throws Error if specified locale is not registered
 */
numeral.localeData(key?: string): LocaleData;

/**
 * Register a new locale definition
 * @param type - Must be 'locale' for locale registration
 * @param name - Unique locale code (will be converted to lowercase)
 * @param definition - Locale configuration object
 * @returns The registered locale definition
 * @throws TypeError if locale with same name already exists
 */
numeral.register(type: 'locale', name: string, definition: LocaleData): LocaleData;

Usage Examples:

const numeral = require('numeral');

// Get current locale
console.log(numeral.locale()); // "en" (default)

// Set locale
numeral.locale('fr');
console.log(numeral.locale()); // "fr"

// Get locale data
const frenchData = numeral.localeData('fr');
console.log(frenchData.currency.symbol); // "€"
console.log(frenchData.delimiters.thousands); // " "
console.log(frenchData.delimiters.decimal); // ","

// Get current locale data
const currentData = numeral.localeData();
console.log(currentData.currency.symbol); // "€" (if French is current)

Locale Data Structure

interface LocaleData {
  delimiters: {
    thousands: string;    // Thousands separator character
    decimal: string;      // Decimal point character
  };
  abbreviations: {
    thousand: string;     // Abbreviation for thousands (k, т, etc.)
    million: string;      // Abbreviation for millions (m, млн, etc.)
    billion: string;      // Abbreviation for billions (b, млрд, etc.)  
    trillion: string;     // Abbreviation for trillions (t, трлн, etc.)
  };
  ordinal: (number: number) => string;  // Function to generate ordinal suffix
  currency: {
    symbol: string;       // Currency symbol ($, €, £, etc.)
  };
}

Built-in Locales

Numeral.js includes comprehensive locale support for 35 languages and regions (34 external locale files plus the default English locale):

European Locales

// English variants
'en'    // English (default) - $, comma thousands, dot decimal
'en-au' // English Australia - $, comma thousands, dot decimal  
'en-gb' // English Great Britain - £, comma thousands, dot decimal
'en-za' // English South Africa - R, space thousands, dot decimal

// Western European
'fr'    // French - €, space thousands, comma decimal
'fr-ca' // French Canada - $, space thousands, comma decimal
'fr-ch' // French Switzerland - CHF, apostrophe thousands, dot decimal
'de'    // German - €, dot thousands, comma decimal  
'de-ch' // German Switzerland - CHF, apostrophe thousands, dot decimal
'it'    // Italian - €, dot thousands, comma decimal
'es'    // Spanish - €, dot thousands, comma decimal
'es-es' // Spanish Spain - €, dot thousands, comma decimal
'nl-nl' // Dutch Netherlands - €, dot thousands, comma decimal
'nl-be' // Dutch Belgium - €, dot thousands, comma decimal

// Nordic
'da-dk' // Danish Denmark - kr, dot thousands, comma decimal
'no'    // Norwegian - kr, space thousands, comma decimal
'fi'    // Finnish - €, space thousands, comma decimal

// Eastern European  
'cs'    // Czech - Kč, space thousands, comma decimal
'sk'    // Slovak - €, space thousands, comma decimal
'sl'    // Slovenian - €, dot thousands, comma decimal
'pl'    // Polish - zł, space thousands, comma decimal
'hu'    // Hungarian - Ft, space thousands, comma decimal
'bg'    // Bulgarian - лв, space thousands, comma decimal
'ru'    // Russian - руб, space thousands, comma decimal
'ru-ua' // Russian Ukraine - грн, space thousands, comma decimal
'uk-ua' // Ukrainian Ukraine - грн, space thousands, comma decimal
'et'    // Estonian - €, space thousands, comma decimal
'lv'    // Latvian - €, space thousands, comma decimal

// Portuguese  
'pt-br' // Portuguese Brazil - R$, dot thousands, comma decimal
'pt-pt' // Portuguese Portugal - €, space thousands, comma decimal

Asian Locales

'ja'  // Japanese - ¥, comma thousands, dot decimal
'chs' // Chinese Simplified - ¥, comma thousands, dot decimal  
'th'  // Thai - ฿, comma thousands, dot decimal
'vi'  // Vietnamese - ₫, dot thousands, comma decimal
'tr'  // Turkish - TL, dot thousands, comma decimal

Usage Examples:

// European formatting
numeral.locale('fr');
console.log(numeral(1234.56).format('0,0.00')); // "1 234,56"
console.log(numeral(1234.56).format('$0,0.00')); // "€1 234,56"

numeral.locale('de');  
console.log(numeral(1234.56).format('0,0.00')); // "1.234,56"

numeral.locale('en-gb');
console.log(numeral(1234.56).format('$0,0.00')); // "£1,234.56"

// Asian formatting
numeral.locale('ja');
console.log(numeral(1234.56).format('$0,0.00')); // "¥1,234.56"

// Reset to default
numeral.locale('en');
console.log(numeral(1234.56).format('$0,0.00')); // "$1,234.56"

Locale-Specific Features

Currency Symbols

Each locale defines its own currency symbol used in $ format patterns:

// Currency symbols by locale
'en': '$'      // US Dollar
'en-gb': '£'   // British Pound  
'fr': '€'      // Euro
'de': '€'      // Euro
'ja': '¥'      // Japanese Yen
'ru': 'руб'    // Russian Ruble
'pt-br': 'R$'  // Brazilian Real
'en-za': 'R'   // South African Rand
// ... and many more

Number Separators

Different locales use different characters for thousands and decimal separators:

// Common separator patterns
'en': { thousands: ',', decimal: '.' }     // 1,234.56
'fr': { thousands: ' ', decimal: ',' }     // 1 234,56  
'de': { thousands: '.', decimal: ',' }     // 1.234,56
'ch': { thousands: "'", decimal: '.' }     // 1'234.56 (Swiss)

Abbreviations

Localized abbreviations for thousands, millions, billions, trillions:

// English abbreviations
'en': { thousand: 'k', million: 'm', billion: 'b', trillion: 't' }

// Russian abbreviations  
'ru': { thousand: 'тыс', million: 'млн', billion: 'млрд', trillion: 'трлн' }

// Bulgarian abbreviations
'bg': { thousand: 'хил', million: 'млн', billion: 'млрд', trillion: 'трлн' }

Ordinal Functions

Each locale provides culture-specific ordinal number generation:

// English ordinals: 1st, 2nd, 3rd, 4th, 21st, 22nd...
'en': function(number) {
  var b = number % 10;
  return (~~(number % 100 / 10) === 1) ? 'th' :
    (b === 1) ? 'st' :
    (b === 2) ? 'nd' :  
    (b === 3) ? 'rd' : 'th';
}

// French ordinals: 1er, 2e, 3e...
'fr': function(number) {
  return number === 1 ? 'er' : 'e';
}

// Some locales don't use ordinals
'bg': function(number) {
  return ''; // Bulgarian doesn't commonly use ordinal suffixes
}

Loading External Locales

Locales can be loaded individually or via the consolidated locales file:

Individual Locale Files

// Browser (after loading numeral.js)
// <script src="locales/fr.js"></script>

// Node.js - individual locale
require('numeral/locales/fr');
numeral.locale('fr');

// ES modules
import 'numeral/locales/fr';

Consolidated Locales File

// Browser - all locales at once
// <script src="locales.js"></script>

// Node.js - all locales
require('numeral/locales');
numeral.locale('fr'); // Any locale now available

Custom Locale Registration

Create custom locales for specific formatting needs:

// Register custom locale
numeral.register('locale', 'custom', {
  delimiters: {
    thousands: '_',
    decimal: ':'
  },
  abbreviations: {
    thousand: 'K',
    million: 'M', 
    billion: 'B',
    trillion: 'T'
  },
  ordinal: function(number) {
    return number === 1 ? 'st' : 'th';
  },
  currency: {
    symbol: '¤'  // Generic currency symbol
  }
});

Usage Examples:

// Create and use custom locale
numeral.register('locale', 'custom', {
  delimiters: { thousands: '_', decimal: ':' },
  abbreviations: { thousand: 'K', million: 'M', billion: 'B', trillion: 'T' },
  ordinal: (n) => n === 1 ? 'st' : 'th',
  currency: { symbol: '¤' }
});

numeral.locale('custom');
console.log(numeral(1234.56).format('0,0.00')); // "1_234:56"
console.log(numeral(1234.56).format('$0,0.00')); // "¤1_234:56"
console.log(numeral(1000).format('0a')); // "1K"
console.log(numeral(1).format('0o')); // "1st"

Locale Validation and Error Handling

// Error handling for invalid locales
try {
  numeral.localeData('invalid-locale');
} catch (error) {
  console.log(error.message); // "Unknown locale : invalid-locale"
}

// Check if locale exists before setting
if (numeral.locales['de']) {
  numeral.locale('de');
}

// List available locales
console.log(Object.keys(numeral.locales)); // ['en', 'fr', 'de', ...]

Locale Impact on Number Parsing

Locales affect how strings are parsed back to numbers:

// Set German locale (uses comma for decimal)
numeral.locale('de');

// Parse German-formatted number
console.log(numeral('1.234,56').value()); // 1234.56
console.log(numeral('1,56').value()); // 1.56

// Validation respects locale
console.log(numeral.validate('1.234,56', 'de')); // true
console.log(numeral.validate('1,234.56', 'de')); // false

// French locale (space for thousands, comma for decimal)
numeral.locale('fr');
console.log(numeral('1 234,56').value()); // 1234.56
console.log(numeral.validate('1 234,56', 'fr')); // true

Default English Locale

The built-in English locale serves as the default and fallback:

// Default English locale configuration
{
  delimiters: {
    thousands: ',',
    decimal: '.'
  },
  abbreviations: {
    thousand: 'k',
    million: 'm', 
    billion: 'b',
    trillion: 't'
  },
  ordinal: function(number) {
    var b = number % 10;
    return (~~(number % 100 / 10) === 1) ? 'th' :
      (b === 1) ? 'st' :
      (b === 2) ? 'nd' :
      (b === 3) ? 'rd' : 'th';
  },
  currency: {
    symbol: '$'
  }
}

This locale is always available and requires no additional loading.

Install with Tessl CLI

npx tessl i tessl/npm-numeral

docs

core.md

formatting.md

index.md

localization.md

tile.json