현지화(i18n)

Note: 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

Note: 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.

Note: 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).

Note: 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');

Note: 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)

Note: 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.

현재 Ignite UI for Angular 불가리아어, 체코어, 덴마크어, 네덜란드어, 영어, 프랑스어, 독일어, 헝가리어, 이탈리아어, 일본어, 한국어, 노르웨이어, 폴란드어, 포르투갈어, 루마니아어, 스페인어, 스웨덴어, 터키어, 번체 중국어(zh-Hant), 간체 중국어(zh-Hans)에 대한 리소스 문자열을 탑재하고 있습니다. 이 패키지는igniteui-angular-i18n 기본 현지화igniteui-angular로 제공되는 영어를 제외하고는 이용할 수 있습니다.

몇 줄의 코드만으로 사용자는 Ignite UI for Angular 구성 요소의 지역화 문자열을 쉽게 변경할 수 있습니다.

Angular Localization Example

참고: 샘플에 포함된 힌디어(HI)는 설명 목적으로만 사용되었으며 사용자 지정 현지화 개체 전달 가능성을 강조하기 위한 것입니다. 이 샘플에는 요약을 위해 현지화된 여러 문자열만 포함되어 있습니다. 자세한 내용은 아래의 현지화된 리소스 활용 섹션을 참조하세요.

Usage

Load localized resources from npm package

패키지에 포함된igniteui-angular-i18n 언어 중 하나로 애플리케이션을 현지화할 수 있습니다:

실행하여 패키지를 설치하세요npm install igniteui-angular-i18n --save-dev

원하는 언어의 리소스 문자열을 가져오고, 컴포넌resourceStrings 트 인스턴스의 입력을 사용해 문자열을 변경하세요.

<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);
    }
}

또는 해당 리소스 객체를 전달하는 함수를changei18n() 호출하여 모든 컴포넌트의 로컬라이제이션을 변경할 수도 있습니다.

// 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);
    }
}

참고: 더 많은 언어가 포함된 패키지에igniteui-angular-i18n 자유롭게 기여해 주세요!

Utilize own localized resources

changei18n함수는 객체를 기대합니다IResourceStrings. 원하는 언어가 패키지에igniteui-angular-i18n 없거나 특정 문자열을 변경하고 싶다면, 필요한 언어와 컴포넌트의 문자열 리소스를 담은 커스텀 객체를 전달할 수 있습니다. 이로 인해 igniteui-각 성분의 글로벌 i18n이 변경됩니다.

// 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);
    }
}

또는 현재 사용 가능한 모든 컴포넌트 리소스 문자열을 받을 수도 있습니다. 각 컴포넌트마다 로컬라이저 가능한 문자열을 포함하는 객체들이 있습니다. 값을 교체하여 국소화할 수 있고, 객체를 매개변수로 함수에changei18n 전달할 수 있습니다.

// 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

단일 인스턴스만igx-grid 로컬라이즈해야 한다면 방법이 있습니다. 속성은resourceStrings 사용되어야 하며, 타입의 새로운 인스턴스IGridResourceStrings로 설정되어야 합니다.

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

this.grid.resourceStrings = newGridRes;

Available resource strings

Additional Resources

우리 커뮤니티는 활동적이며 항상 새로운 아이디어를 환영합니다.

현지화(i18n)

현지화(i18n)

Angular Localization Example

Locale

Global API

lang attribute

Angular API

Per component

Formatting

Date formats

Localized resource strings

Regions and scripts

Customize a component

Language and formatting

Language only

Custom localized resource strings

Available resource strings

Legacy Localization (i18n)

Angular Localization Example

Usage

Load localized resources from npm package

Utilize own localized resources

Localize specific strings for a specific instance of a component

Available resource strings

Additional Resources

테마

`lang` attribute