0
# Localization Module
1

2
Comprehensive internationalization system providing date and number formatting, locale management, and multilingual support with 18 built-in locales.
3

4
## Core Imports
5

6
```javascript
7
// Import Sugar namespace
8
import Sugar from "sugar";
9
// Locale methods available via Sugar.Date namespace
10
```
11

12
CommonJS:
13
```javascript
14
const Sugar = require("sugar");
15
// Access locale methods via Date namespace
16
Sugar.Date.setLocale('fr');
17
Sugar.Date.getLocale();
18
```
19

20
## Capabilities
21

22
### Locale Management
23

24
Core functions for managing and configuring locales in the Sugar environment.
25

26
#### Add Locale
27

28
Registers a new custom locale or updates an existing one with specific formatting rules.
29

30
```javascript { .api }
31
/**
32
 * Registers a new custom locale or updates an existing one
33
 * @param localeCode - ISO language code for the locale
34
 * @param def - Locale definition object with formatting rules
35
 */
36
function addLocale(localeCode: string, def: LocaleDefinition): void;
37
```
38

39
**Usage Example:**
40
```javascript
41
import Sugar from "sugar";
42

43
// Add a custom locale
44
Sugar.Date.addLocale('custom', {
45
  'months': ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
46
             'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
47
  'weekdays': ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
48
  'numerals': ['zero', 'one', 'two', 'three', 'four', 'five'],
49
  'tokens': ['the', 'of', 'a'],
50
  'short': '{Month} {d}',
51
  'medium': '{Month} {d}, {yyyy}',
52
  'long': '{Weekday} {Month} {d}, {yyyy}',
53
  'full': '{Weekday}, {Month} {d}, {yyyy}',
54
  'stamp': '{Weekday} {Month} {d} {yyyy} {H}:{mm}:{ss}',
55
  'time': '{H}:{mm}',
56
  'past': '{num} {unit} ago',
57
  'future': 'in {num} {unit}',
58
  'duration': '{num} {unit}',
59
  'modifiers': [
60
    { 'name': 'day', 'src': 'yesterday', 'value': -1 },
61
    { 'name': 'day', 'src': 'today', 'value': 0 },
62
    { 'name': 'day', 'src': 'tomorrow', 'value': 1 }
63
  ]
64
});
65
```
66

67
#### Set Locale
68

69
Sets the active locale for date parsing and formatting operations.
70

71
```javascript { .api }
72
/**
73
 * Sets the active locale for date parsing and formatting operations
74
 * @param localeCode - ISO language code to set as active
75
 */
76
function setLocale(localeCode: string): void;
77
```
78

79
**Usage Example:**
80
```javascript
81
import Sugar from "sugar";
82

83
// Set German locale
84
Sugar.Date.setLocale('de');
85
const date = Sugar.Date.create('15. März 2023');
86
Sugar.Date.format(date, 'full'); // "Mittwoch, 15. März 2023"
87

88
// Switch to French locale
89
Sugar.Date.setLocale('fr');
90
Sugar.Date.format(date, 'full'); // "mercredi 15 mars 2023"
91
```
92

93
#### Get Locale
94

95
Retrieves a specific locale object or the currently active locale.
96

97
```javascript { .api }
98
/**
99
 * Retrieves a specific locale object or the currently active locale
100
 * @param localeCode - ISO language code (optional, defaults to current locale)
101
 * @returns Locale object with formatting methods and properties
102
 */
103
function getLocale(localeCode?: string): Locale;
104
```
105

106
**Usage Example:**
107
```javascript
108
import Sugar from "sugar";
109

110
Sugar.Date.setLocale('ja');
111
const currentLocale = Sugar.Date.getLocale(); // Japanese locale object
112
const frenchLocale = Sugar.Date.getLocale('fr'); // French locale object
113

114
// Access locale methods
115
currentLocale.getMonthName(0); // "1月" (January in Japanese)
116
frenchLocale.getMonthName(0);  // "janvier"
117
```
118

119
#### Get All Locale Codes
120

121
Returns an array of all available locale codes.
122

123
```javascript { .api }
124
/**
125
 * Returns an array of all available locale codes
126
 * @returns Array of ISO language codes for all registered locales
127
 */
128
function getAllLocaleCodes(): string[];
129
```
130

131
**Usage Example:**
132
```javascript
133
import Sugar from "sugar";
134

135
const codes = Sugar.Date.getAllLocaleCodes();
136
// Returns: ['ca', 'da', 'de', 'es', 'fi', 'fr', 'it', 'ja', 'ko', 'nl', 'no', 'pl', 'pt', 'ru', 'sv', 'zh-CN', 'zh-TW']
137

138
// Use for building locale selection UI
139
codes.forEach(code => {
140
  console.log(`Available locale: ${code}`);
141
});
142
```
143

144
#### Get All Locales
145

146
Returns an object containing all registered locale objects.
147

148
```javascript { .api }
149
/**
150
 * Returns an object containing all registered locale objects
151
 * @returns Object mapping locale codes to their locale objects
152
 */
153
function getAllLocales(): { [localeCode: string]: Locale };
154
```
155

156
**Usage Example:**
157
```javascript
158
import Sugar from "sugar";
159

160
const allLocales = Sugar.Date.getAllLocales();
161
const germanLocale = allLocales.de;
162
const japaneseLocale = allLocales.ja;
163

164
// Access properties of specific locales
165
Object.keys(allLocales).forEach(code => {
166
  const locale = allLocales[code];
167
  console.log(`${code}: ${locale.getMonthName(0)}`);
168
});
169
```
170

171
#### Remove Locale
172

173
Removes a custom locale from the system (built-in locales cannot be removed).
174

175
```javascript { .api }
176
/**
177
 * Removes a custom locale from the system
178
 * @param localeCode - ISO language code of locale to remove
179
 */
180
function removeLocale(localeCode: string): void;
181
```
182

183
**Usage Example:**
184
```javascript
185
import Sugar from "sugar";
186

187
// Add a custom locale
188
Sugar.Date.addLocale('test', { /* locale definition */ });
189

190
// Later remove it
191
Sugar.Date.removeLocale('test');
192

193
// Note: Built-in locales cannot be removed
194
// Sugar.Date.removeLocale('en'); // This would have no effect
195
```
196

197
### Built-in Locales
198

199
Sugar includes 18 pre-configured locales with complete date and number formatting support.
200

201
#### Available Locales
202

203
```javascript { .api }
204
/**
205
 * Built-in locale codes available in Sugar
206
 */
207
type BuiltInLocaleCodes = 
208
  | 'ca'     // Catalan
209
  | 'da'     // Danish  
210
  | 'de'     // German
211
  | 'es'     // Spanish
212
  | 'fi'     // Finnish
213
  | 'fr'     // French
214
  | 'it'     // Italian
215
  | 'ja'     // Japanese
216
  | 'ko'     // Korean
217
  | 'nl'     // Dutch
218
  | 'no'     // Norwegian
219
  | 'pl'     // Polish
220
  | 'pt'     // Portuguese
221
  | 'ru'     // Russian
222
  | 'sv'     // Swedish
223
  | 'zh-CN'  // Chinese (Simplified)
224
  | 'zh-TW'; // Chinese (Traditional)
225
```
226

227
**Usage Example:**
228
```javascript
229
import Sugar from "sugar";
230

231
// Demonstrate different locales
232
const date = Sugar.Date.create('March 15, 2023');
233

234
Sugar.Date.setLocale('de');
235
Sugar.Date.format(date, 'long'); // "Mittwoch, 15. März 2023"
236

237
Sugar.Date.setLocale('fr'); 
238
Sugar.Date.format(date, 'long'); // "mercredi 15 mars 2023"
239

240
Sugar.Date.setLocale('ja');
241
Sugar.Date.format(date, 'long'); // "2023年3月15日水曜日"
242

243
Sugar.Date.setLocale('zh-CN');
244
Sugar.Date.format(date, 'long'); // "2023年3月15日星期三"
245
```
246

247
### Locale Interface
248

249
Each locale object provides methods for accessing localized formatting information.
250

251
#### Add Format
252

253
Adds a custom date format pattern to the locale.
254

255
```javascript { .api }
256
/**
257
 * Adds a custom date format pattern to the locale
258
 * @param src - Format pattern string using Sugar tokens
259
 * @param to - Array of alternative format strings (optional)
260
 */
261
addFormat(src: string, to?: string[]): void;
262
```
263

264
**Usage Example:**
265
```javascript
266
import Sugar from "sugar";
267

268
const locale = Sugar.Date.getLocale('en');
269
locale.addFormat('{dd}/{MM}/{yyyy}', ['DD/MM/YYYY']);
270
locale.addFormat('{Weekday} the {do}', ['dddd the Do']);
271
```
272

273
#### Get Duration
274

275
Formats a duration in milliseconds according to locale rules.
276

277
```javascript { .api }
278
/**
279
 * Formats a duration in milliseconds according to locale rules
280
 * @param ms - Duration in milliseconds
281
 * @returns Localized duration string
282
 */
283
getDuration(ms: number): string;
284
```
285

286
**Usage Example:**
287
```javascript
288
import Sugar from "sugar";
289

290
Sugar.Date.setLocale('en');
291
const enLocale = Sugar.Date.getLocale();
292
enLocale.getDuration(3661000); // "1 hour"
293

294
Sugar.Date.setLocale('de');  
295
const deLocale = Sugar.Date.getLocale();
296
deLocale.getDuration(3661000); // "1 Stunde"
297

298
Sugar.Date.setLocale('fr');
299
const frLocale = Sugar.Date.getLocale();
300
frLocale.getDuration(3661000); // "1 heure"
301
```
302

303
#### Get First Day Of Week
304

305
Returns the first day of the week for the locale (0 = Sunday, 1 = Monday, etc.).
306

307
```javascript { .api }
308
/**
309
 * Returns the first day of the week for the locale
310
 * @returns Number representing first day (0 = Sunday, 1 = Monday, etc.)
311
 */
312
getFirstDayOfWeek(): number;
313
```
314

315
**Usage Example:**
316
```javascript
317
import Sugar from "sugar";
318

319
const usLocale = Sugar.Date.getLocale('en');
320
usLocale.getFirstDayOfWeek(); // 0 (Sunday)
321

322
const germanLocale = Sugar.Date.getLocale('de');
323
germanLocale.getFirstDayOfWeek(); // 1 (Monday)
324

325
const frenchLocale = Sugar.Date.getLocale('fr');
326
frenchLocale.getFirstDayOfWeek(); // 1 (Monday)
327
```
328

329
#### Get First Day Of Week Year
330

331
Returns the first day of the week year for ISO week calculations.
332

333
```javascript { .api }
334
/**
335
 * Returns the first day of the week year for ISO week calculations
336
 * @returns Number representing first day of week year
337
 */
338
getFirstDayOfWeekYear(): number;
339
```
340

341
#### Get Month Name
342

343
Returns the localized name of a month.
344

345
```javascript { .api }
346
/**
347
 * Returns the localized name of a month
348
 * @param n - Month number (0-11, where 0 = January)
349
 * @returns Localized month name
350
 */
351
getMonthName(n: number): string;
352
```
353

354
**Usage Example:**
355
```javascript
356
import Sugar from "sugar";
357

358
const frenchLocale = Sugar.Date.getLocale('fr');
359
frenchLocale.getMonthName(0);  // "janvier"
360
frenchLocale.getMonthName(11); // "décembre"
361

362
const germanLocale = Sugar.Date.getLocale('de');
363
germanLocale.getMonthName(2);  // "März"
364

365
const japaneseLocale = Sugar.Date.getLocale('ja');
366
japaneseLocale.getMonthName(5); // "6月"
367
```
368

369
#### Get Weekday Name
370

371
Returns the localized name of a weekday.
372

373
```javascript { .api }
374
/**
375
 * Returns the localized name of a weekday
376
 * @param n - Weekday number (0-6, where 0 = Sunday)
377
 * @returns Localized weekday name
378
 */
379
getWeekdayName(n: number): string;
380
```
381

382
**Usage Example:**
383
```javascript
384
import Sugar from "sugar";
385

386
const spanishLocale = Sugar.Date.getLocale('es');
387
spanishLocale.getWeekdayName(0); // "domingo"
388
spanishLocale.getWeekdayName(1); // "lunes"
389

390
const koreanLocale = Sugar.Date.getLocale('ko');
391
koreanLocale.getWeekdayName(6); // "토요일"
392

393
const dutchLocale = Sugar.Date.getLocale('nl');
394
dutchLocale.getWeekdayName(3); // "woensdag"
395
```
396

397
## Types
398

399
```javascript { .api }
400
/**
401
 * Locale interface providing localization methods and properties
402
 */
403
interface Locale {
404
  /**
405
   * Adds a custom date format pattern to the locale
406
   */
407
  addFormat(src: string, to?: string[]): void;
408
  
409
  /**
410
   * Formats a duration in milliseconds according to locale rules
411
   */
412
  getDuration(ms: number): string;
413
  
414
  /**
415
   * Returns the first day of the week for the locale
416
   */
417
  getFirstDayOfWeek(): number;
418
  
419
  /**
420
   * Returns the first day of the week year for ISO week calculations
421
   */
422
  getFirstDayOfWeekYear(): number;
423
  
424
  /**
425
   * Returns the localized name of a month
426
   */
427
  getMonthName(n: number): string;
428
  
429
  /**
430
   * Returns the localized name of a weekday
431
   */
432
  getWeekdayName(n: number): string;
433
}
434

435
/**
436
 * Locale definition object for creating custom locales
437
 */
438
interface LocaleDefinition {
439
  months?: string[];
440
  weekdays?: string[];
441
  numerals?: string[];
442
  tokens?: string[];
443
  short?: string;
444
  medium?: string;
445
  long?: string;
446
  full?: string;
447
  stamp?: string;
448
  time?: string;
449
  past?: string;
450
  future?: string;
451
  duration?: string;
452
  modifiers?: Array<{
453
    name: string;
454
    src: string;
455
    value: number;
456
  }>;
457
  parse?: string[];
458
  timeParse?: string[];
459
  timeFrontParse?: string[];
460
}
461

462
/**
463
 * Built-in locale codes available in Sugar
464
 */
465
type BuiltInLocaleCodes = 
466
  | 'ca' | 'da' | 'de' | 'es' | 'fi' | 'fr' | 'it' | 'ja' 
467
  | 'ko' | 'nl' | 'no' | 'pl' | 'pt' | 'ru' | 'sv' 
468
  | 'zh-CN' | 'zh-TW';
469
```