Localization (i18n)

As of 21.1.0 this is the recommended way of applying localization to the Ignite UI for Angular components.

With our new localization we introduce more features with less requirements for both our localization strings and formatting for all available locales. The formatting is now based on the standards introduced by the Intl API.

Currently, Ignite UI for Angular ships with resource strings for the following languages: Bulgarian, Czech, Danish, Dutch, English, French, German, Hungarian, Italian, Japanese, Korean, Norwegian, Polish, Portuguese, Romanian, Spanish, Swedish, Turkish, Traditional Chinese (zh-Hant) and Simplified Chinese (zh-Hans). These are available via the igniteui-angular-i18n package, except for English which comes as a default localization in igniteui-angular.

Angular Localization Example

Hindi (HI) included in the sample is only for illustrational purposes and to emphasize on the possibility to pass a custom localization object. In this sample, it contains only several localized strings for the summary. More details at Custom localized resource strings section below.

Locale

By locale, we will refer to the general strings defining the different languages and regions on Earth. In our case they are based on the BCP 47 tag definition and most of the basic ones are described in the IANA Language Subtag Registry and for a list of languages you can also `refer to ISO 639 language standard.

It affects both the formatting of the dates and numbers and the localized resource strings that our components use. The default locale for the Ignite UI for Angular components is en-US.

There are several ways that you can set locale. Either globally or per component.

Global API

You can set the locale that will be used globally using the setCurrentI18n method, that comes from the igniteui-angular package. It will affect both formatting and registered resource strings used in all of our components. For more on resource strings see Localized resource strings

setCurrentI18n('de');

We support the full range of possible locales supported by Intl. If you provide a locale that is not valid or supported, it will use the default en-US locale for the time being, until you change it to a valid one.

In general you should register your resources under the languages, regions and scripts for the tags you plan to use, so that your components are localized as well. For more see Regions and Scripts section.

`lang` attribute

With this approach we have the ability to set localization through the lang global attribute of the HTML tag. This attribute is being watched and if it is changed, all rendered components will update their resource strings to the currently set language. All rules regarding the tag used apply as described above.

This works only on root level and will not work for inner elements on the page.

<html lang="ja">
    <head>
        <title>My app</title>
    </head>
    <body></body>
</html>

Angular API

You can use also Angular’s built in LOCALE_ID token to set the locale for the whole application. The tag provided will work the same way for our components compared to how our API handles.

Per component

Each component will also have its own locale property, that you can specify and it will then not be affected by the global locale.

<igx-grid [data]="data" locale="ja">
    <igx-column field="ProductName" header="Product Name" [groupable]="true"></igx-column>
    <igx-column field="QuantityPerUnit" header="Quantity Per Unit" [groupable]="true"></igx-column>
</igx-grid>

Formatting

Locale like mentioned affects the formatting in all Ignite UI for Angular components that render dates, numbers and some strings related to them. Previously you had to import Angular’s global variants of the locale data they provide in order to be able to use it in your app. This is no longer the case and this comes built in our localization by default and you won’t need to import and register anything for it to work.

Since we are just introducing this feature, the Angular’s way is still available and very much working as before and is still the default way, if you are already using it.

If you are just starting though, you will only need to add the provideIgniteIntl() method to your app config, which will make sure that you use the new formatting, even if you have the Angular’s locale data imported:

export const appConfig: ApplicationConfig = {
    providers: [
        //...
        provideIgniteIntl()
    ]
};

Date formats

Components like the IgxGrid or IgxDatePicker allow for specifying date format (for the grid per column). The lists bellow show the available options that you can set or build your own custom format.

Available predefined format options:

Option	Equivalent to	Examples (given in en-US locale)
‘short'	'M/d/yy, h:mm a’	6/15/15, 9:03 AM
’medium'	'MMM d, y, h:mm:ss a’	Jun 15, 2015, 9:03:01 AM
’long'	'MMMM d, y, h:mm:ss a z’	June 15, 2015 at 9:03:01 AM GMT+1
’full'	'EEEE, MMMM d, y, h:mm:ss a zzzz’	Monday, June 15, 2015 at 9:03:01 AM GMT+01:00
’shortDate'	'M/d/yy’	6/15/15
’mediumDate'	'MMM d, y’	Jun 15, 2015
’longDate'	'MMMM d, y’	June 15, 2015
’fullDate'	'EEEE, MMMM d, y’	Monday, June 15, 2015
’shortTime'	'h:mm a’	9:03 AM
’mediumTime'	'h:mm:ss a’	9:03:01 AM
’longTime'	'h:mm:ss a z’	9:03:01 AM GMT+1
’fullTime'	'h:mm:ss a zzzz’	9:03:01 AM GMT+01:00

Custom format options:

Date field	Value	Description	Example
Weekday	c, cc, ccc, E, EE, EEE	Short version of the weekday	Tue
	cccc, EEEE	Long version of the weekday	Tuesday
	ccccc, EEEEE	Narrow version of the weekday	T
Day	d	Numeric display (single digit when possible)	1, 10
	dd	2-digit always (zero padded)	01, 10
Month	M, L	Numeric display (single digit when possible)	8, 12
	MM, LL	2-digit always (zero padded)	08, 12
	MMM, LLL	Short month name	Oct
	MMMM, LLLL	Long month name	October
	MMMMM, LLLLL	Narrow month name	O
Year	y, yyy, yyyy	Numeric display	1, 24, 632, 2025
	yy	2-digit display (zero padded when possible)	01, 24, 32, 25
ISO 8601 year	Y, YYY, YYYY	Numeric display	1, 24, 632, 2025
	YY	2-digit display (zero padded when possible)	01, 24, 32, 25
Era	G, GG, GGG	Short display	AD, BC
	GGGG	Long display	Anno Domini, Before Christ
	GGGGG	Narrow display	A, B
Minute	m	Numeric (single digit when possible)	1, 5, 22
	mm	2-digit display (zero padded)	01, 05, 22
Hour 1-12	h	Numeric (single digit when possible)	8, 12
	hh	2-digit (zero padded)	08, 13
Hour 0-23	H	Numeric (single digit when possible)	8, 21
	HH	2-digit (zero padded)	08, 21
Hour 0-11	K	Numeric (single digit when possible)	0, 11
	KK	2-digit (zero padded)	00, 11
Second	s	Numeric (single digit when possible)	0…59
	ss	2-digit (zero padded)	00…59
Fractional seconds	S	Numeric for 1 digit	0…9
	SS	Numeric for 2 digits	00…99
	SSS	Numeric for 3 digits	000…999
Period of time - abbreviated	a, t	Lower case always	am, pm
	aa, aaa, tt, ttt	Upper case always	AM, PM
	aaaa, tttt	Case based on locale	am, pm, AM, PM
	aaaaa, ttttt	Narrow lower case always	a, p
Period of time - extended	b, bb, bbb, B, BB, BBB	Short display. Based on `Intl` locale	en-GB: at night
	bbbb, BBBB	Long display. Based on `Intl` locale	en-GB: at night
	bbbbb, BBBBB	Narrow display. Based on `Intl` locale	en-GB: at night
Timezone	z, zz, zzz, Z, ZZ, ZZZ, O, OO, OOO	Short display	GMT+4
	zzzz, ZZZZ, OOOO	Long display	GMT+0430

Localized resource strings

All components in Ignite UI for Angular render in English by default and they can be rendered in any of the listed languages at the top as well. There are three ways you can achieve that globally and one way per component. For any language that is not currently available, custom translation can be provided for each resource string that is available through our API.

The translations for the component strings are stored in resource strings and they will need to be registered in our localization system so that the component can use them.

To achieve that, you first need to install the igniteui-angular-i18n package, which contains the localized resource strings for all languages:

npm install igniteui-angular-i18n --save-dev

After that you will need to register each language you would like to have available to them. Lets say German and Japanese:

import { IgxResourceStringsDE, IgxResourceStringsJA } from 'igniteui-angular-i18n';

registerI18n(IgxResourceStringsDE, 'de');
registerI18n(IgxResourceStringsJA, 'ja');

You will also need to provide to which locale they will apply to. If not a valid tag is provided, it will set the resources for the default ‘en-US’ locale.

Regions and scripts

We take into account the language + region or language + script from the locale you used to register your resources, since these are the most commonly used. They are separated by - and region/script are usually defined on a second or third position. For example, en-US and en-GB or en-Latn.

If you do not use region or script, the resources you register will apply to all locales that use the en language, for example. That is unless you define resources for the regions and scripts as well. Then only for those you have not defined, will return the resources for en in this case.

The script for us has higher priority than the region when registering resources. We recommend in general to use either region or script, without mixing them and using both at the same time. That way it is easier to manage and know which one you have available and should be used, based on the locale you set.

Anyway, if you happen to use them both, lets take for example the en language with GB region and Latn script. If you define resources for both region and script like en-GB and en-Latn, and later on you set your locale, having both region and script to en-Latn-GB, we will take the resources from the script one first. If it is not available, then we will return the available region, unless you explicitly set your locale to en-Latn, of course. If you have for none of them registered resources, we will take the default for en if available.

Customize a component

If you would like to have specific component in your app use either the already registered resources globally but with different localization or completely replace the resource strings for it, you can do that the following way.

Language and formatting

If you would like to set different from the global localization for a component, you can do that by setting the locale property. This will affect the language of the resource strings used as well as the formatting, since they are tied together.

With this approach you should already have the available resource strings globally registered:

import { IgxResourceStringsJA } from 'igniteui-angular-i18n';

registerI18n(IgxResourceStringsJA, 'ja');

By setting the locale property of the component, this will override the global locale currently in use:

<igx-grid [data]="data" locale="ja">
    <igx-column field="ProductName" header="Product Name" [groupable]="true"></igx-column>
    <igx-column field="QuantityPerUnit" header="Quantity Per Unit" [groupable]="true"></igx-column>
</igx-grid>

Language only

If you would like to change only the language of the component, without changing the locale, you can even set the resource strings of each component using the resourceStrings property, which will override the globally used ones:

<igx-grid [data]="data" [resourceStrings]="resourcesDE">
    <igx-column field="ProductName" header="Product Name" [groupable]="true"></igx-column>
    <igx-column field="QuantityPerUnit" header="Quantity Per Unit" [groupable]="true"></igx-column>
</igx-grid>

You will need to make sure you use the correct resource string type for the component you would like to override it with. Each component has its own set of resource strings. In this case for the grid in German:

import { GridResourceStringsDE } from 'igniteui-angular-i18n';

// Inside App Component:
public resourcesDE = GridResourceStringsDE;

Custom localized resource strings

If you would like to localize your app, but we do not provide resource strings for the language you use and would like to provide your own translation, you can always provide custom resource string. You can do that globally or per component(using the resourceStrings property).

Feel free to contribute to the igniteui-i18n-resources package with more languages. The igniteui-angular-i18n are based on them.

You can use the provided IResourceStrings type for all components to get typings for the resource stings used:

import { IResourceStrings } from 'igniteui-angular';

export const customResourcesForAll: IResourceStrings = {
    //...
};
registerI18n(customResourcesForAll, 'custom');

Or for a specific component separately, in this case the grids:

import { IGridResourceStrings } from 'igniteui-angular';

export const customGridResources: IGridResourceStrings = {
    grid_summary_count: 'गणना',
    grid_summary_min: 'न्यून',
    grid_summary_max: 'अधिक',
    grid_summary_sum: 'योग',
    grid_summary_average: 'औसत'
};

You can even mix however you want the already existing resource strings with the ones you want to customize, even for the default English language:

import { IResourceStrings, CalendarResourceStringsEN, DatePickerResourceStringsEN } from 'igniteui-angular';

export const customResources: IResourceStrings = Object.assign(
    {},
    CalendarResourceStringsEN,
    DatePickerResourceStringsEN,
    {
        grid_summary_count: 'Custom count',
        grid_summary_min: 'Minium',
        grid_summary_max: 'Maximum',
        grid_summary_sum: 'Custom summary'
    }
);
registerI18n(customResources, 'en');

The last examples set only specific resource strings. This means that the rest will default to English, if they are not available for the components in use to get.

Available resource strings

Legacy Localization (i18n)

This is an old way of handling localization that was recommended until 21.0.x. We suggest using the new available way above if you are using newer versions. This will still work until further notice.

Currently, Ignite UI for Angular ships with resource strings for the following languages and scripts: Bulgarian, Czech, Danish, Dutch, English, French, German, Hungarian, Italian, Japanese, Korean, Norwegian, Polish, Portuguese, Romanian, Spanish, Swedish, Turkish, Traditional Chinese (zh-Hant) and Simplified Chinese (zh-Hans). These are available via the igniteui-angular-i18n package, except for English which comes as a default localization in igniteui-angular.

With only a few lines of code, users can easily change the localization strings in Ignite UI for Angular components.

Angular Localization Example

Usage

Load localized resources from npm package

You can localize an application in one of the languages available in the igniteui-angular-i18n package like this:

Install the package by executing npm install igniteui-angular-i18n --save-dev

Import the resource strings for the desired language and either change the strings for a component instance, using the component’s resourceStrings input.

<igx-grid [data]="data" [resourceStrings]="resourcesDE" [locale]="locale">
    <igx-grid-toolbar>
        <igx-grid-toolbar-title>German Locale</igx-grid-toolbar-title>
    </igx-grid-toolbar>
    <igx-column field="ProductName" header="Product Name" [groupable]="true">
    </igx-column>
    <igx-column field="QuantityPerUnit" header="Quantity Per Unit" [groupable]="true">
    </igx-column>
    <igx-column field="UnitPrice" header="Unit Price" [sortable]="true" [hasSummary]="true"
        [dataType]="'currency'" [groupable]="true">
    </igx-column>
    <igx-column field="OrderDate" header="Order Date" [dataType]="'date'" [groupable]="true">
    </igx-column>
    <igx-column field="Discontinued" header="Discontinued" [dataType]="'boolean'" [groupable]="true">
    </igx-column>
</igx-grid>

import { Component } from '@angular/core';
import { registerLocaleData } from '@angular/common';

import localeDE from '@angular/common/locales/de';
import { GridResourceStringsDE } from 'igniteui-angular-i18n';

@Component({
    selector: 'app-locale',
    styleUrls: ['./locale.component.scss'],
    templateUrl: 'locale.component.html'
})
export class LocaleComponent implements OnInit {
    public resourcesDE = GridResourceStringsDE;
    public locale = 'DE';
    public data: any[];

    constructor() {
        registerLocaleData(localeDE);
    }
}

Alternatively, you can call the changei18n() function passing the corresponding resource object to change the localization for all components.

// app.component.ts
import { Component, OnInit } from '@angular/core';
import { changei18n } from "igniteui-angular/core";
import { IgxResourceStringsJA } from 'igniteui-angular-i18n';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent implements OnInit {
    public ngOnInit(): void {
        changei18n(IgxResourceStringsJA);
    }
}

Feel free to contribute to the igniteui-angular-i18n package with more languages!

Utilize own localized resources

changei18n function expects an IResourceStrings object. If the language you want to use is not available in the igniteui-angular-i18n package, or simply want to change a particular string, you can pass a custom object containing your string resources for the language and components you need. This will change the global i18n for the igniteui-angular components.

// app.component.ts
import { Component, OnInit } from '@angular/core';
import { changei18n, IGridResourceStrings } from "igniteui-angular/core";

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent implements OnInit {
    public partialCustomHindi: IGridResourceStrings;

    public ngOnInit(): void {
        this.partialCustomHindi = {
            igx_grid_summary_count: 'गणना',
            igx_grid_summary_min: 'न्यून',
            igx_grid_summary_max: 'अधिक',
            igx_grid_summary_sum: 'योग',
            igx_grid_summary_average: 'औसत'
        };
        // This will change all grid application instances' strings to the newly provided ones
        changei18n(this.partialCustomHindi);
    }
}

Alternatively, you may get all currently available component resource strings. There is objects for each component containing localizable strings. The values could be replaced in order to be localized and then the object can be passed to the changei18n function, as a parameter.

// app.component.ts
import { Component, OnInit } from '@angular/core';
import { changei18n, GridResourceStringsEN, TimePickerResourceStringsEN } from "igniteui-angular/core";

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent implements OnInit {
    public ngOnInit(): void {
        const currentRS = {
            ...GridResourceStringsEN,
            ...TimePickerResourceStringsEN
        };

        for (const key of Object.keys(currentRS)) {
            currentRS[key] = '[Localized] '+ currentRS[key];
        }

        changei18n(currentRS);
    }
}

Localize specific strings for a specific instance of a component

If only a single igx-grid instance should be localized, there is a way. The resourceStrings property should be used and it should be set to a new instance of IGridResourceStrings type.

const newGridRes: IGridResourceStrings = {
    igx_grid_filter: '[Localized]Filter',
    igx_grid_filter_row_close: '[Localized]Close'
}

this.grid.resourceStrings = newGridRes;

Available resource strings

Additional Resources

Our community is active and always welcoming to new ideas.

Localization (i18n)