Internationalization
24 Jun 202424 minutes to read
The Internationalization library provided by Syncfusion enables formatting and parsing of date and number objects using official Unicode CLDR JSON data. By default, the en-US
locale is set as the default culture, and USD
is set as the default currency code for all Syncfusion Angular UI Components.
Loading CLDR-JSON Data
Syncfusion CLDR data package contains only JSON data files generated using the official Unicode CLDR JSON data. This helps users avoid utilizing the existing cldr-data package, which has third-party library vulnerabilities. The loadCldr
function is required to load the following CLDR data for cultures other than en-US
.
NOTE
Syncfusion CLDR data package is published based on the releases of the Unicode CLDR JSON data. The package will be published within a week after the official Unicode CLDR JSON data is released.
Individual file path reference
Syncfusion CLDR data can be loaded by referring to individual paths from the package below, such as:
File Name | Path |
---|---|
ca-gregorian | @syncfusion/ej2-cldr-data/main/en/ca-gregorian.json |
timeZoneNames | @syncfusion/ej2-cldr-data/main/en/timeZoneNames.json |
numbers | @syncfusion/ej2-cldr-data/main/en/numbers.json |
currencies | @syncfusion/ej2-cldr-data/main/en/currencies.json |
numberingSystems | @syncfusion/ej2-cldr-data/supplemental/numberingSystems.json |
Single file path reference
Syncfusion CLDR data can also be loaded by referring to a single path from the package below, such as:
File Name | Path |
---|---|
ca-gregorian, timeZoneNames, numbers, currencies | @syncfusion/ej2-cldr-data/main/en/all.json |
numberingSystems | @syncfusion/ej2-cldr-data/supplemental/numberingSystems.json |
Note: For
en
, dependency files are already loaded in the library.
Installing CLDR data
Syncfusion CLDR data is available as npm package. So, we can install it through below command to our package.
npm install @syncfusion/ej2-cldr-data
Binding to i18n library
The i18n library to use the CLDR data to format, parse number and date/time values in a way that is appropriate for the en
culture. The loadCldr function takes two arguments, enNumberData and enTimeZoneData, which are the CLDR data for numbers and time zones, respectively, for the en culture.
import { loadCldr } from '@syncfusion/ej2-base';
import enNumberData from "@syncfusion/ej2-cldr-data/main/en/numbers.json";
import entimeZoneData from "@syncfusion/ej2-cldr-data/main/en/timeZoneNames.json";
loadcldr(enNumberData, entimeZoneData);
Changing global Culture and Currency code
To set the default culture and the currency code for all Syncfusion Angular UI Components, you can use the methods setCulture
for setting the default locale and setCurrencyCode
for setting the currency code.
import {setCulture, setCurrencyCode} from '@syncfusion/ej2-base';
setCulture('ar');
setCurrencyCode('QAR');
Note: If global culture is not set, then
en-US
is set as the default locale, andUSD
is set as the 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 in the table below
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
andmaximumFractionDigits
are categorized
as group one,minimumSignificantDigits
andmaximumSignificantDigits
are categorized as group two.
If group two properties are defined, then group one properties will be ignored.
Custom number formatting and parsing
Custom number formatting and parsing can also be achieved by directly specifying the pattern in the format property of NumberFormatOptions
. One or more of the custom format specifiers listed in the table below can be used to create custom number format.
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 a custom format pattern is specified, other
NumberFormatOptions
properties will not be considered.
Number Parsing
getNumberParser
The getNumberParser
method, which will return a function that parses a given string based on the NumberFormatOptions
specified.
import { NgModule } from '@angular/core'
import { BrowserModule } from '@angular/platform-browser'
import { Component } from '@angular/core';
import { Internationalization } from '@syncfusion/ej2-base';
@Component({
standalone: true,
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 { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));
parseNumber
The parseNumber
method, which takes two arguments, the string value and NumberFormatOptions
and returns the numeric value.
import { NgModule } from '@angular/core'
import { BrowserModule } from '@angular/platform-browser'
import { Component } from '@angular/core';
import { Internationalization } from '@syncfusion/ej2-base';
@Component({
standalone: true,
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 any).innerHTML = val + '';
}
}
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));
Number formatting
getNumberFormat
The getNumberFormat
method will return a function that formats a given number based on the NumberFormatOptions
specified.
import { NgModule } from '@angular/core'
import { BrowserModule } from '@angular/platform-browser'
import { Component } from '@angular/core';
import { Internationalization } from '@syncfusion/ej2-base';
@Component({
standalone: true,
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 as string;
}
}
import { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));
formatNumber
The formatNumber
method, which takes two arguments, a numeric value and NumberFormatOptions
, and returns the formatted string.
import { NgModule } from '@angular/core'
import { BrowserModule } from '@angular/platform-browser'
import { Component } from '@angular/core';
import { Internationalization } from '@syncfusion/ej2-base';
@Component({
standalone: true,
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 { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));
Manipulating DateTime
Supported format string
Date formatting and parsing operations are performed based on the DateFormatOptions
. You need to specify some or all of the following properties mentioned in the table below.
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 formats are supported by using the additional skeletons given in the 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.
A 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. |
f | Denotes milliseconds. |
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 the format property is given as an option, other properties are not considered.
Date Parsing
getDateParser
The getDateParser
method will return a function that parses a given string based on the DateFormatOptions
specified.
import { NgModule } from '@angular/core'
import { BrowserModule } from '@angular/platform-browser'
import { Component } from '@angular/core';
import { Internationalization } from '@syncfusion/ej2-base';
@Component({
standalone: true,
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 { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));
parseDate
The date object is returned by the parseDate
method, which takes two arguments, a string value and DateFormatOptions
.
import { NgModule } from '@angular/core'
import { BrowserModule } from '@angular/platform-browser'
import { Component } from '@angular/core';
import { Internationalization } from '@syncfusion/ej2-base';
@Component({
standalone: true,
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 { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));
Date Formatting
getDateFormat
The getDateFormat
method, which will return a function that formats a given date object based on the DateFormatOptions
specified.
import { NgModule } from '@angular/core'
import { BrowserModule } from '@angular/platform-browser'
import { Component } from '@angular/core';
import { Internationalization } from '@syncfusion/ej2-base';
@Component({
standalone: true,
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 { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));
formatDate
The formatDate
method, which takes two arguments, the date object and DateFormatOptions
, returns the formatted string.
import { NgModule } from '@angular/core'
import { BrowserModule } from '@angular/platform-browser'
import { Component } from '@angular/core';
import { Internationalization } from '@syncfusion/ej2-base';
@Component({
standalone: true,
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 { bootstrapApplication } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import 'zone.js';
bootstrapApplication(AppComponent).catch((err) => console.error(err));