0
# Localization
1

2
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.
3

4
## Capabilities
5

6
### Locale Management
7

8
```javascript { .api }
9
/**
10
 * Get or set the current locale
11
 * @param key - Optional locale code to set as current locale
12
 * @returns Current locale code (lowercase)
13
 */
14
numeral.locale(key?: string): string;
15

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

24
/**
25
 * Register a new locale definition
26
 * @param type - Must be 'locale' for locale registration
27
 * @param name - Unique locale code (will be converted to lowercase)
28
 * @param definition - Locale configuration object
29
 * @returns The registered locale definition
30
 * @throws TypeError if locale with same name already exists
31
 */
32
numeral.register(type: 'locale', name: string, definition: LocaleData): LocaleData;
33
```
34

35
**Usage Examples:**
36

37
```javascript
38
const numeral = require('numeral');
39

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

43
// Set locale
44
numeral.locale('fr');
45
console.log(numeral.locale()); // "fr"
46

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

53
// Get current locale data
54
const currentData = numeral.localeData();
55
console.log(currentData.currency.symbol); // "€" (if French is current)
56
```
57

58
### Locale Data Structure
59

60
```javascript { .api }
61
interface LocaleData {
62
  delimiters: {
63
    thousands: string;    // Thousands separator character
64
    decimal: string;      // Decimal point character
65
  };
66
  abbreviations: {
67
    thousand: string;     // Abbreviation for thousands (k, т, etc.)
68
    million: string;      // Abbreviation for millions (m, млн, etc.)
69
    billion: string;      // Abbreviation for billions (b, млрд, etc.)  
70
    trillion: string;     // Abbreviation for trillions (t, трлн, etc.)
71
  };
72
  ordinal: (number: number) => string;  // Function to generate ordinal suffix
73
  currency: {
74
    symbol: string;       // Currency symbol ($, €, £, etc.)
75
  };
76
}
77
```
78

79
### Built-in Locales
80

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

83
#### European Locales
84

85
```javascript { .api }
86
// English variants
87
'en'    // English (default) - $, comma thousands, dot decimal
88
'en-au' // English Australia - $, comma thousands, dot decimal  
89
'en-gb' // English Great Britain - £, comma thousands, dot decimal
90
'en-za' // English South Africa - R, space thousands, dot decimal
91

92
// Western European
93
'fr'    // French - €, space thousands, comma decimal
94
'fr-ca' // French Canada - $, space thousands, comma decimal
95
'fr-ch' // French Switzerland - CHF, apostrophe thousands, dot decimal
96
'de'    // German - €, dot thousands, comma decimal  
97
'de-ch' // German Switzerland - CHF, apostrophe thousands, dot decimal
98
'it'    // Italian - €, dot thousands, comma decimal
99
'es'    // Spanish - €, dot thousands, comma decimal
100
'es-es' // Spanish Spain - €, dot thousands, comma decimal
101
'nl-nl' // Dutch Netherlands - €, dot thousands, comma decimal
102
'nl-be' // Dutch Belgium - €, dot thousands, comma decimal
103

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

109
// Eastern European  
110
'cs'    // Czech - Kč, space thousands, comma decimal
111
'sk'    // Slovak - €, space thousands, comma decimal
112
'sl'    // Slovenian - €, dot thousands, comma decimal
113
'pl'    // Polish - zł, space thousands, comma decimal
114
'hu'    // Hungarian - Ft, space thousands, comma decimal
115
'bg'    // Bulgarian - лв, space thousands, comma decimal
116
'ru'    // Russian - руб, space thousands, comma decimal
117
'ru-ua' // Russian Ukraine - грн, space thousands, comma decimal
118
'uk-ua' // Ukrainian Ukraine - грн, space thousands, comma decimal
119
'et'    // Estonian - €, space thousands, comma decimal
120
'lv'    // Latvian - €, space thousands, comma decimal
121

122
// Portuguese  
123
'pt-br' // Portuguese Brazil - R$, dot thousands, comma decimal
124
'pt-pt' // Portuguese Portugal - €, space thousands, comma decimal
125
```
126

127
#### Asian Locales
128

129
```javascript { .api }
130
'ja'  // Japanese - ¥, comma thousands, dot decimal
131
'chs' // Chinese Simplified - ¥, comma thousands, dot decimal  
132
'th'  // Thai - ฿, comma thousands, dot decimal
133
'vi'  // Vietnamese - ₫, dot thousands, comma decimal
134
'tr'  // Turkish - TL, dot thousands, comma decimal
135
```
136

137
**Usage Examples:**
138

139
```javascript
140
// European formatting
141
numeral.locale('fr');
142
console.log(numeral(1234.56).format('0,0.00')); // "1 234,56"
143
console.log(numeral(1234.56).format('$0,0.00')); // "€1 234,56"
144

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

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

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

155
// Reset to default
156
numeral.locale('en');
157
console.log(numeral(1234.56).format('$0,0.00')); // "$1,234.56"
158
```
159

160
### Locale-Specific Features
161

162
#### Currency Symbols
163

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

166
```javascript
167
// Currency symbols by locale
168
'en': '$'      // US Dollar
169
'en-gb': '£'   // British Pound  
170
'fr': '€'      // Euro
171
'de': '€'      // Euro
172
'ja': '¥'      // Japanese Yen
173
'ru': 'руб'    // Russian Ruble
174
'pt-br': 'R$'  // Brazilian Real
175
'en-za': 'R'   // South African Rand
176
// ... and many more
177
```
178

179
#### Number Separators
180

181
Different locales use different characters for thousands and decimal separators:
182

183
```javascript
184
// Common separator patterns
185
'en': { thousands: ',', decimal: '.' }     // 1,234.56
186
'fr': { thousands: ' ', decimal: ',' }     // 1 234,56  
187
'de': { thousands: '.', decimal: ',' }     // 1.234,56
188
'ch': { thousands: "'", decimal: '.' }     // 1'234.56 (Swiss)
189
```
190

191
#### Abbreviations
192

193
Localized abbreviations for thousands, millions, billions, trillions:
194

195
```javascript
196
// English abbreviations
197
'en': { thousand: 'k', million: 'm', billion: 'b', trillion: 't' }
198

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

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

206
#### Ordinal Functions
207

208
Each locale provides culture-specific ordinal number generation:
209

210
```javascript
211
// English ordinals: 1st, 2nd, 3rd, 4th, 21st, 22nd...
212
'en': function(number) {
213
  var b = number % 10;
214
  return (~~(number % 100 / 10) === 1) ? 'th' :
215
    (b === 1) ? 'st' :
216
    (b === 2) ? 'nd' :  
217
    (b === 3) ? 'rd' : 'th';
218
}
219

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

225
// Some locales don't use ordinals
226
'bg': function(number) {
227
  return ''; // Bulgarian doesn't commonly use ordinal suffixes
228
}
229
```
230

231
### Loading External Locales
232

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

235
#### Individual Locale Files
236

237
```javascript
238
// Browser (after loading numeral.js)
239
// <script src="locales/fr.js"></script>
240

241
// Node.js - individual locale
242
require('numeral/locales/fr');
243
numeral.locale('fr');
244

245
// ES modules
246
import 'numeral/locales/fr';
247
```
248

249
#### Consolidated Locales File
250

251
```javascript
252
// Browser - all locales at once
253
// <script src="locales.js"></script>
254

255
// Node.js - all locales
256
require('numeral/locales');
257
numeral.locale('fr'); // Any locale now available
258
```
259

260
### Custom Locale Registration
261

262
Create custom locales for specific formatting needs:
263

264
```javascript { .api }
265
// Register custom locale
266
numeral.register('locale', 'custom', {
267
  delimiters: {
268
    thousands: '_',
269
    decimal: ':'
270
  },
271
  abbreviations: {
272
    thousand: 'K',
273
    million: 'M', 
274
    billion: 'B',
275
    trillion: 'T'
276
  },
277
  ordinal: function(number) {
278
    return number === 1 ? 'st' : 'th';
279
  },
280
  currency: {
281
    symbol: '¤'  // Generic currency symbol
282
  }
283
});
284
```
285

286
**Usage Examples:**
287

288
```javascript
289
// Create and use custom locale
290
numeral.register('locale', 'custom', {
291
  delimiters: { thousands: '_', decimal: ':' },
292
  abbreviations: { thousand: 'K', million: 'M', billion: 'B', trillion: 'T' },
293
  ordinal: (n) => n === 1 ? 'st' : 'th',
294
  currency: { symbol: '¤' }
295
});
296

297
numeral.locale('custom');
298
console.log(numeral(1234.56).format('0,0.00')); // "1_234:56"
299
console.log(numeral(1234.56).format('$0,0.00')); // "¤1_234:56"
300
console.log(numeral(1000).format('0a')); // "1K"
301
console.log(numeral(1).format('0o')); // "1st"
302
```
303

304
### Locale Validation and Error Handling
305

306
```javascript { .api }
307
// Error handling for invalid locales
308
try {
309
  numeral.localeData('invalid-locale');
310
} catch (error) {
311
  console.log(error.message); // "Unknown locale : invalid-locale"
312
}
313

314
// Check if locale exists before setting
315
if (numeral.locales['de']) {
316
  numeral.locale('de');
317
}
318

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

323
### Locale Impact on Number Parsing
324

325
Locales affect how strings are parsed back to numbers:
326

327
```javascript
328
// Set German locale (uses comma for decimal)
329
numeral.locale('de');
330

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

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

339
// French locale (space for thousands, comma for decimal)
340
numeral.locale('fr');
341
console.log(numeral('1 234,56').value()); // 1234.56
342
console.log(numeral.validate('1 234,56', 'fr')); // true
343
```
344

345
### Default English Locale
346

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

349
```javascript { .api }
350
// Default English locale configuration
351
{
352
  delimiters: {
353
    thousands: ',',
354
    decimal: '.'
355
  },
356
  abbreviations: {
357
    thousand: 'k',
358
    million: 'm', 
359
    billion: 'b',
360
    trillion: 't'
361
  },
362
  ordinal: function(number) {
363
    var b = number % 10;
364
    return (~~(number % 100 / 10) === 1) ? 'th' :
365
      (b === 1) ? 'st' :
366
      (b === 2) ? 'nd' :
367
      (b === 3) ? 'rd' : 'th';
368
  },
369
  currency: {
370
    symbol: '$'
371
  }
372
}
373
```
374

375
This locale is always available and requires no additional loading.