Internationalization

26 Jan 202424 minutes to read

The Internationalization library provides support for formatting and parsing date and number objects using the official Unicode CLDR JSON data. The en-US locale is set as default culture and USD is set as default _currencyCode_ for all Syncfusion Angular UI Components.

Loading Culture Data

It requires the following CLDR data to be load using loadCldr function for cultures other than en-US.

File Name	Path
ca-gregorian	cldr/main/en/ca-gregorian.json
timeZoneNames	cldr/main/en/timeZoneNames.json
numbers	cldr/main/en/numbers.json
numberingSystems	cldr/supplemental/numberingSystems.json
currencies	cldr/main/en/currencies.json

Note: For en, dependency files are already loaded in the library.

Installing CLDR Data

CLDR data is available as npm package. So, we can install it through below command to our package.

npm install cldr-data

Binding to i18n library

import { loadCldr } from '@syncfusion/ej2-base';
loadcldr(enNumberData, entimeZoneData);

Changing Global Culture and Currency Code

To set the default culture and the currencyCode for all Syncfusion Angular UI Components, you can use the methods setCulture for setting default locale and setCurrencyCode for setting the currencyCode.

Setting Global Culture

import {setCulture} from '@syncfusion/ej2-base';

setCulture('ar');

Setting Currency Code

import { setCurrencyCode} from '@syncfusion/ej2-base';

setCurrencyCode('QAR');

Note: If global culture is not set then en-US is set as default locale and USD is set as default currency code.

Manipulating Numbers

Supported Format String

Based on the NumberFormatOptions number formatting and parsing operations are processed. You need to specify some or all of the following properties mentioned below table.

No	Properties	Description
1	`format`	Denotes the format to be set .Possible values are 1. N - denotes numeric type 2. C - denotes currency type 3. P - denotes percentage type. Ex: `formatNumber`( 1234344 ,{format:'N4'}). >Note: If no format is specified it takes numeric as default format type.
2	`minimumFractionDigits`	Indicates the minimum number of fraction digits . Possible values are 0 to 20.
3	`maximumFractionDigits`	Indicates the maximum number of fraction digits. Possible values are 0 to 20.
4	`minimumSignificantDigits`	Indicates he minimum number of significant digits. Possible values are 1 to 21. >Note: If `minimumSignificantDigits` is given it is mandatory to give `maximumSignificantDigits`
5	`maximumSignificantDigits`	Indicates he maximum number of significant digits. . Possible values are 1 to 21. >Note: If `maximumSignificantDigits` is given it is mandatory to give `minimumSignificantDigits`
6	`useGrouping`	Indicates whether to enable the group separator or not . By default grouping value will be true.
7	`minimumIntegerDigits`	Indicates the minimum number of the integer digits to be placed in the value. Possible values are 1 to 21.
8	`currency`	Indicates the currency code which needs to considered for the currency formatting.

Note: The minimumIntegerDigits, minimumFractionDigits and maximumFractionDigits are categorized
as group one, minimumSignificantDigits and maximumSignificantDigits are categorized as group two.
If group two properties are defined, then the group one properties will be ignored.

Custom number formatting and parsing

Custom number formatting and parsing are also supported by specifying the pattern directly in the format property of NumberFormatOptions. Custom number format can be achieved by using one or more custom format specifiers listed in the below table.

Specifier	Description	Input	Format Output
0	Replaces the zero with the corresponding digit if one is present. Otherwise, zero appears in the result string.	`instance.formatNumber`(123,{format: ‘0000’ })	‘0123’
#	Replaces the “#” symbol with the corresponding digit if one is present; otherwise, no digit appears in the result string.	`instance.formatNumber`(1234,{format: ‘####’ })	‘1234’
.	Denotes the number of digits allowed after the decimal points if it’s not specified then no need to specify decimal point values.	`instance.formatNumber`(546321,{format: ‘###0.##0#’ })	‘546321.000’
%	Percent specifier denotes the percentage type format.	`instance.formatNumber`(1,{format: ‘0000 %’ })	‘0100 %’
$	Denotes the currency type format based on the global currency code specified.	`instance.formatNumber`(13,{format: ‘$ ###.00’ });	‘$ 13.00’
;	Denotes separate formats for positive, negative and zero values.	`instance.formatNumber`(-120,{format: ‘###.##;(###.00);-0’});	‘(120.00)’
‘String’ (single Quotes)	Denotes the characters enclosed within single Quote(‘) to be replaced in the resultant string.	`instance.formatNumber`(-123.44,{format: “####.## ‘@’”})	‘123.44 @’

Note: If custom format pattern is specified other NumberFormatOptions properties will not be considered.

Number formatting

`getNumberFormat`

The getNumberFormat method which will return a function that formats given number based on the NumberFormatOptions specified.

app.component.ts
app.module.ts
main.ts
import { Component } from '@angular/core';
import { Internationalization } from  '@syncfusion/ej2-base';

@Component({
    selector: 'app-root',
    template:` <div id='container'>
    <div>Value:<span class='format text'>1234545.65</span></div>
    <div>Formatted Value:<span class='result text'> </span></div>
    </div> `
})

export class AppComponent {
    ngAfterViewInit() {
        let intl: Internationalization = new Internationalization();
        let nFormatter: Function = intl.getNumberFormat({ skeleton: 'C3', currency: 'USD',minimumIntegerDigits:8});
        let formattedValue: string = nFormatter(1234545.65);
        (document.querySelector('.result') as Element).innerHTML = formattedValue;
        }
        }
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';

/**
 * Module
 */
@NgModule({
    imports: [
        BrowserModule,
    ],
    declarations: [AppComponent],
    bootstrap: [AppComponent]
})
export class AppModule { }
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { enableProdMode } from '@angular/core';
import { AppModule } from './app.module';

import 'zone.js';
enableProdMode();
platformBrowserDynamic().bootstrapModule(AppModule);

`formatNumber`

The formatNumber method which takes two arguments numeric value andNumberFormatOptions and returns the formatted string.

app.component.ts
app.module.ts
main.ts
import { Component } from '@angular/core';
import { Internationalization } from  '@syncfusion/ej2-base';

@Component({
    selector: 'app-root',
    template:` <div id='container'>
    <div>Value:<span class='format text'>1234545.65</span></div>
    <div>Formatted Value:<span class='result text'> </span></div>
    </div> `
    })

export class AppComponent {
    ngAfterViewInit() {
        let intl: Internationalization = new Internationalization();
        let formattedString: string = intl.formatNumber(12345.65,{ format:'C5' ,
        useGrouping: false,minimumSignificantDigits:1, maximumSignificantDigits:3 });
        (document.querySelector('.result') as Element).innerHTML = formattedString;
        }
        }
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';

/**
 * Module
 */
@NgModule({
    imports: [
        BrowserModule,
    ],
    declarations: [AppComponent],
    bootstrap: [AppComponent]
})
export class AppModule { }
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { enableProdMode } from '@angular/core';
import { AppModule } from './app.module';

import 'zone.js';
enableProdMode();
platformBrowserDynamic().bootstrapModule(AppModule);

Parsing

`getNumberParser`

The getNumberParser method which will return a function that parses given string based on the NumberFormatOptions specified.

app.component.ts
app.module.ts
main.ts
import { Component } from '@angular/core';
import { Internationalization } from  '@syncfusion/ej2-base';

@Component({
    selector: 'app-root',
    template:` <div id='container'>
    <div>FormattedValue:<span class='format text'>123567.45%</span></div>
    <div>ParsedOutput:<span class='result text'> </span></div>
    </div>`
})

export class AppComponent {
    ngAfterViewInit() {
        let intl: Internationalization = new Internationalization();
        let nParser: Function =  intl.getNumberParser({ format:'P2' , useGrouping: false});
        let val: number = nParser('123567.45%');
        (document.querySelector('.result') as Element).innerHTML = val + '';
        }
        }
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';

/**
 * Module
 */
@NgModule({
    imports: [
        BrowserModule,
    ],
    declarations: [AppComponent],
    bootstrap: [AppComponent]
})
export class AppModule { }
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { enableProdMode } from '@angular/core';
import { AppModule } from './app.module';

import 'zone.js';
enableProdMode();
platformBrowserDynamic().bootstrapModule(AppModule);

`parseNumber`

The parseNumber method which takes two arguments the string value and NumberFormatOptions and returns the numeric value.

app.component.ts
app.module.ts
main.ts
import { Component } from '@angular/core';
import { Internationalization } from  '@syncfusion/ej2-base';

@Component({
    selector: 'app-root',
    template:` <div id='container'>
    <div>FormattedValue:<span class='format text'>$01,234,545.650</span></div>
    <div>ParsedOutput:<span class='result text'> </span></div>
    </div>`
})

export class AppComponent {
    ngAfterViewInit() {
        let intl: Internationalization = new Internationalization();
        let val: number = intl.parseNumber('$01,234,545.650', { format: 'C3', currency: 'USD', minimumIntegerDigits: 8 });
        (document.querySelector('.result') as Element).innerHTML = val + '';
        }
        }
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';

/**
 * Module
 */
@NgModule({
    imports: [
        BrowserModule,
    ],
    declarations: [AppComponent],
    bootstrap: [AppComponent]
})
export class AppModule { }
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { enableProdMode } from '@angular/core';
import { AppModule } from './app.module';

import 'zone.js';
enableProdMode();
platformBrowserDynamic().bootstrapModule(AppModule);

Manipulating DateTime

Supported Format String

Based on the DateFormatOptions date formatting and parsing operations are processed. You need to specify some or all of the following properties mentioned below table.

Options	Descriptions
Type	It specifies the type of format to be used supported types . 1. `date` 2. `dateTime` 3. `time` Based on the type specified the supported skeletons are given below 1. short 2. medium, 3. long 4. full Ex: `formatDate`(new Date(), {type: 'date', skeleton:medium}) >Note: If not type specified then date type is set by default
skeleton	Specifies the format in which the `dateTime` format will process

Date type skeletons

skeleton	Option input	Format Output
short	{type: 'date', skeleton:'short'})	11/4/16
medium	{type: 'date', skeleton:'medium'})	Nov 4, 2016
long	{type: 'date', skeleton:'long'}	November 4, 2016
full	{type: 'date', skeleton:full})	Friday, November 4, 2016

Time type skeletons

skeleton	Option input	Format Output
short	{type: 'time', skeleton:'short'}	1:03 PM
medium	{type: 'time', skeleton:'medium'}	1:03:04 PM
Long	{type: 'time', skeleton:'long'})	1:03:04 PM GMT+5
full	{type: 'time', skeleton:'full'})	1:03:04 PM GMT+05:30

DateTime type skeletons

Skeleton	Option input	Format Output
short	{type: '`dateTime`', skeleton:'short'}	11/4/16, 1:03 PM
medium	{type: '`dateTime`, skeleton:'medium'}	Nov 4, 2016, 1:03:04 PM
Long	{type: '`dateTime`', skeleton:'long'})	November 4, 2016 at 1:03:04 PM GMT+5
full	{type: '`dateTime`', skeleton:'full'})	Friday, November 4, 2016 at 1:03:04 PM GMT+05:30

Additional skeletons

Apart from the standard date type formats additional format are supported by using the additional skeletons given in below table.

skeleton	Option input	Format Output
d	{skeleton:'d'}	7
E	{skeleton:'E'}	Mon
Ed	{skeleton:'Ed'}	7 Mon
Ehm	{skeleton:'Ehm'})	Mon 12:43 AM
EHm	{skeleton:'EHm;});	Mon 12:43
Ehms	{skeleton:'Ehms' }	Mon 2:45:23 PM
EHms	{skeleton:'EHms'})	Mon 12:45:45
Gy	{skeleton:'Gy' }	2016 AD
GyMMM	{skeleton:'GyMMM'}	: Nov 2016 AD
GyMMMd	{skeleton:'GyMMMd'}	Nov 7, 2016 AD
GyMMMEd	{skeleton:'GyMMMEd'}	Mon, Nov 7, 2016 AD
h	{skeleton:'h'}	12 PM
H	{skeleton:'H'}	12
hm	{skeleton:'hm'}	12:59 PM
Hm	{skeleton:'Hm'}	12:59
hms	{skeleton:'hms'}	12:59:13 PM
Hms	{skeleton:'Hms'}	12:59:13
M	{skeleton:'M'}	11
Md	{skeleton:'Md'}	11/7
MEd	{skeleton:'hms'}	Mon, 11/7
MMM	{skeleton:'MMM'}	Nov
MMMEd	{skeleton:'MMMEd'}	Mon, Nov 7
MMMd	{skeleton:'MMMEd'}	Nov 7
ms	{skeleton:'ms'}	59:13
y	{skeleton:'y' }	2016
yM	{skeleton:'yM' }	11/2016
yMd	{skeleton:'yMd' }	11/7/2016
yMEd	{skeleton:'yMEd' }	Mon, 11/7/2016
yMMM	{skeleton:'yMMM' }	Nov 2016
yMMMd	{skeleton:'yMMMd'}	Nov 7, 2016
yMMMEd	{skeleton:'yMMMEd'}	Mon, Nov 7, 2016
yMMM	{skeleton:'yMMM'}	Nov 2016

Note: Culture specific format skeletons are also supported.

Custom Formats

To use the custom date and time formats we need to specify the date/time pattern directly in the format property.
Custom format string must contain one or more of the following standard date/time symbols

Symbols	Description
G	Denotes the era in the date
y	Denotes the year.
M / L	Denotes month.
E / c	Denotes the day of week.
d	Denotes the day of month.
h / H	Denotes the hour. h for 12 hour and H for 24 hours format.
m	Denotes minutes.
s	Denotes seconds.
a	Denotes the am/pm designator it will only be displayed if hour is specified in the h format.
z	Denotes the time zone.
’ (single quotes)	To display words in the formatted date you can specify the words with in the single quotes

Custom format example

import { Component } from '@angular/core';
import { Internationalization } from  '@syncfusion/ej2-base';

@Component({
    selector: 'app-root',
    templateUrl:`default.html`
})

export class AppComponent {
    ngAfterViewInit() {
        let intl: Internationalization = new Internationalization();
        let formattedString: string =  intl.formatDate(new Date('1/12/2014 10:20:33'), { format:'\'year:\'y' \'month:\' MM' });
        //Output: "year:2014 month:01"
        }
        }

Note: If format property is given in options other properties are not considered.

Formatting

`getDateFormat`

The getDateFormat method which will return a function that formats given date object based on the DateFormatOptions specified.

app.component.ts
app.module.ts
main.ts
import { Component } from '@angular/core';
import { Internationalization } from  '@syncfusion/ej2-base';

@Component({
    selector: 'app-root',
    template:` <div id='container'>
    <div>DateValue:<span class='format text'>new Date('1/12/2014 10:20:33')</span></div>
    <div>Formatted Value:<span class='result text'> </span></div>
    <div> `
})

export class AppComponent {
    ngAfterViewInit() {
        let intl: Internationalization = new Internationalization();
        let dFormatter: Function = intl.getDateFormat({ skeleton: 'full', type: 'dateTime' });
        let formattedString: string = dFormatter(new Date('1/12/2014 10:20:33'));
        (document.querySelector('.result') as Element).innerHTML = formattedString;
        }
        }
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';

/**
 * Module
 */
@NgModule({
    imports: [
        BrowserModule,
    ],
    declarations: [AppComponent],
    bootstrap: [AppComponent]
})
export class AppModule { }
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { enableProdMode } from '@angular/core';
import { AppModule } from './app.module';

import 'zone.js';
enableProdMode();
platformBrowserDynamic().bootstrapModule(AppModule);

`formatDate`

The formatDate method which takes two arguments date object and DateFormatOptions and returns the formatted string.

app.component.ts
app.module.ts
main.ts
import { Component } from '@angular/core';
import { Internationalization } from  '@syncfusion/ej2-base';

@Component({
    selector: 'app-root',
    template:` <div id='container'>
    <div>DateValue:<span class='format text'>new Date('1/12/2014 10:20:33')</span></div>
    <div>Formatted Value:<span class='result text'> </span></div>
    <div> `
})

export class AppComponent {
    ngAfterViewInit() {
        let intl: Internationalization = new Internationalization();
        let date: Date = new Date();
        let formattedString: string =  intl.formatDate(new Date('1/12/2014 10:20:33'), { skeleton: 'GyMMM' });
        (document.querySelector('.result') as Element).innerHTML = formattedString;
        }
        }
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';

/**
 * Module
 */
@NgModule({
    imports: [
        BrowserModule,
    ],
    declarations: [AppComponent],
    bootstrap: [AppComponent]
})
export class AppModule { }
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { enableProdMode } from '@angular/core';
import { AppModule } from './app.module';

import 'zone.js';
enableProdMode();
platformBrowserDynamic().bootstrapModule(AppModule);

Parsing

`getDateParser`

The getDateParser method which will return a function that parses given string based on the DateFormatOptions specified.

app.component.ts
app.module.ts
main.ts
import { Component } from '@angular/core';
import { Internationalization } from  '@syncfusion/ej2-base';

@Component({
    selector: 'app-root',
    template:` <div id='container'>
    <div>Fromatted value:<span class='format text'>Friday, November 4, 2016 at 1:03:04 PM GMT+05:30</span></div>
    <div>parsed Value:<span class='result text'> </span></div>
    </div> `
})

export class AppComponent {
    ngAfterViewInit() {
        let intl: Internationalization = new Internationalization();
        let dParser: Function = intl.getDateParser({skeleton: 'full', type: 'dateTime'});
        let val: Date = dParser('Friday, November 4, 2016 at 1:03:04 PM GMT+05:30');
        (document.querySelector('.result') as Element).innerHTML = val.toString();
        }
        }
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';

/**
 * Module
 */
@NgModule({
    imports: [
        BrowserModule,
    ],
    declarations: [AppComponent],
    bootstrap: [AppComponent]
})
export class AppModule { }
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { enableProdMode } from '@angular/core';
import { AppModule } from './app.module';

import 'zone.js';
enableProdMode();
platformBrowserDynamic().bootstrapModule(AppModule);

`parseDate`

The parseDate method which takes two arguments string value and DateFormatOptions and returns the date Object.

app.component.ts
app.module.ts
main.ts
import { Component } from '@angular/core';
import { Internationalization } from  '@syncfusion/ej2-base';

@Component({
    selector: 'app-root',
    template:` <div id='container'>
    <div>Fromatted value:<span class='format text'>11/2016</span></div>
    <div>parsed Value:<span class='result text'> </span></div>
    </div> `
})

export class AppComponent {
    ngAfterViewInit() {
        let intl:Internationalization = new Internationalization();
        let val: number | any =  intl.parseDate('11/2016',{skeleton: 'yM'});
        (document.querySelector('.result') as Element).innerHTML = val.toString();
        }
        }
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';

/**
 * Module
 */
@NgModule({
    imports: [
        BrowserModule,
    ],
    declarations: [AppComponent],
    bootstrap: [AppComponent]
})
export class AppModule { }
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
import { enableProdMode } from '@angular/core';
import { AppModule } from './app.module';

import 'zone.js';
enableProdMode();
platformBrowserDynamic().bootstrapModule(AppModule);