# Internationalization Development (i18n)
This development guide describes how to use i18n APIs that are not defined in ECMA 402.
## Obtaining System Language and Region Information
APIs are provided to access the system language and region information.
### Available APIs
| Module | API | Description |
| -------- | -------- | -------- |
| ohos.i18n | getSystemLanguage(): string | Obtains the system language. |
| ohos.i18n | getSystemRegion(): string | Obtains the system region. |
| ohos.i18n | getSystemLocale(): string | Obtains the system locale. |
| ohos.i18n | isRTL(locale: string): boolean7+ | Checks whether the locale uses a right-to-left (RTL) language. |
| ohos.i18n | is24HourClock(): boolean7+ | Checks whether the system uses a 24-hour clock. |
| ohos.i18n | getDisplayLanguage(language: string, locale: string, sentenceCase?: boolean): string | Obtains the localized display of a language. |
| ohos.i18n | getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): string | Obtains the localized display of a country. |
### How to Develop
1. Obtain the system language.
Call the **getSystemLanguage** method to obtain the system language (**i18n** is the name of the imported module).
```
var language = i18n.getSystemLanguage();
```
2. Obtain the system region.
Call the **getSystemRegion** method to obtain the system region.
```
var region = i18n.getSystemRegion();
```
3. Obtain the system locale.
Call the **getSystemLocale** method to obtain the system locale.
```
var locale = i18n.getSystemLocale();
```
4. Check whether the locale's language is RTL.
Call the **isRTL** method to check whether the locale's language is RTL.
```
var rtl = i18n.isRTL("zh-CN");
```
5. Check whether the system uses a 24-hour clock.
Call the **is24HourClock** method to check whether the system uses a 24-hour clock.
```
var hourClock = i18n.is24HourClock();
```
6. Obtain the localized display of a language.
Call the **getDisplayLanguage** method to obtain the localized display of a language. **language** indicates the language to be localized, **locale** indicates the locale, and **sentenceCase** indicates whether the first letter of the result must be capitalized.
```
var language = "en";
var locale = "zh-CN";
var sentenceCase = false;
var localizedLanguage = i18n.getDisplayLanguage(language, locale, sentenceCase);
```
7. Obtain the localized display of a country.
Call the **getDisplayCountry** method to obtain the localized display of a country. **country** indicates the country to be localized, **locale** indicates the locale, and **sentenceCase** indicates whether the first letter of the result must be capitalized.
```
var country = "US";
var locale = "zh-CN";
var sentenceCase = false;
var localizedCountry = i18n.getDisplayCountry(country, locale, sentenceCase);
```
## Obtaining Calendar Information
[Calendar](../reference/apis/js-apis-intl.md) APIs are used to obtain calendar information, for example, the localized display of the calendar, the first day of a week, and the minimum count of days in the first week of a year.
### Available APIs
| Module | API | Description |
| -------- | -------- | -------- |
| ohos.i18n | getCalendar(locale: string, type?: string): Calendar8+ | Obtains the **Calendar** object for a specific locale and type. |
| ohos.i18n | setTime(date: Date): void8+ | Sets the date for the **Calendar** object. |
| ohos.i18n | setTime(time: number): void8+ | Sets the time for the **Calendar** object. |
| ohos.i18n | set(year: number, month: number, date: number, hour?: number, minute?: number, second?: number): void8+ | Sets the year, month, day, hour, minute, and second for the **Calendar** object. |
| ohos.i18n | setTimeZone(timezone: string): void8+ | Sets the time zone for the **Calendar** object. |
| ohos.i18n | getTimeZone(): string8+ | Obtains the time zone for the **Calendar** object. |
| ohos.i18n | getFirstDayOfWeek(): number8+ | Obtains the first day of a week for the **Calendar** object. |
| ohos.i18n | setFirstDayOfWeek(value: number): void8+ | Sets the first day of a week for the **Calendar** object. |
| ohos.i18n | getMinimalDaysInFirstWeek(): number8+ | Obtains the minimum count of days in the first week of a year. |
| ohos.i18n | setMinimalDaysInFirstWeek(value: number): void8+ | Sets the minimum count of days in the first week of a year. |
| ohos.i18n | getDisplayName(locale: string): string8+ | Obtains the localized display of the **Calendar** object. |
| ohos.i18n | isWeekend(date?: Date): boolean8+ | Checks whether a given date is a weekend. |
### How to Develop
1. Instantiate a **Calendar** object.
Call the **getCalendar** method to obtain the time zone object of a specific locale and type (**i18n** is the name of the imported module). **type** indicates the valid calendar type, for example, **buddhist**, **chinese**, **coptic**, **ethiopic**, **hebrew**, **gregory**, **indian**, **islamic_civil**, **islamic_tbla**, **islamic_umalqura**, **japanese**, and **persian**. If **type** is left unspecified, the default calendar type of the locale is used.
```
var calendar = i18n.getCalendar("zh-CN", "gregory);
```
2. Set the time for the **Calendar** object.
Call the **setTime** method to set the time of the **Calendar** object. This method receives two types of parameters. One is a **Date** object, and the other is a value indicating the number of milliseconds elapsed since January 1, 1970, 00:00:00 GMT.
```
var date1 = new Date();
calendar.setTime(date1);
var date2 = 1000;
calendar.setTime(date2);
```
3. Set the year, month, day, hour, minute, and second for the **Calendar** object.
Call the **set** method to set the year, month, day, hour, minute, and second for the **Calendar** object.
```
calendar.set(2021, 12, 21, 6, 0, 0)
```
4. Set and obtain the time zone for the **Calendar** object.
Call the **setTimeZone** and **getTimeZone** methods to set and obtain the time zone for the **Calendar** object. The **setTimeZone** method requires an input string to indicate the time zone to be set.
```
calendar.setTimeZone("Asia/Shanghai");
var timezone = calendar.getTimeZone();
```
5. Set and obtain the first day of a week for the **Calendar** object.
Call the **setFirstDayOfWeek** and **getFirstDayOfWeek** methods to set and obtain the first day of a week for the **Calendar** object. **setFirstDayOfWeek** must be set to a value indicating the first day of a week. The value **1** indicates Sunday, and the value **7** indicates Saturday.
```
calendar.setFirstDayOfWeek(1);
var firstDayOfWeek = calendar.getFirstDayOfWeek();
```
6. Set and obtain the minimum count of days in the first week for the **Calendar** object.
Call the **setMinimalDaysInFirstWeek** and **getMinimalDaysInFirstWeek** methods to set and obtain the minimum count of days in the first week for the **Calendar** object.
```
calendar.setMinimalDaysInFirstWeek(3);
var minimalDaysInFirstWeek = calendar.getMinimalDaysInFirstWeek();
```
7. Obtain the localized display of the **Calendar** object.
Call the **getDisplayName** method to obtain the localized display of the **Calendar** object.
```
var localizedName = calendar.getDisplayName("zh-CN");
```
8. Check whether a date is a weekend.
Call the **isWeekend** method to determine whether the input date is a weekend.
```
var date = new Date();
var weekend = calendar.isWeekend(date);
```
## Formatting a Phone Number
[PhoneNumberFormat](../reference/apis/js-apis-intl.md) APIs are used to format phone numbers in different countries and check whether the phone number formats are correct.
### Available APIs
| Module | API | Description |
| -------- | -------- | -------- |
| ohos.i18n | constructor(country: string, options?: PhoneNumberFormatOptions)8+ | Instantiates a **PhoneNumberFormat** object. |
| ohos.i18n | isValidNumber(number: string): boolean8+ | Checks whether the value of **number** is a phone number in the correct format. |
| ohos.i18n | format(number: string): string8+ | Formats the value of **number** based on the specified country and style. |
### How to Develop
1. Instantiate a **PhoneNumberFormat** object.
Call the **PhoneNumberFormat** constructor to instantiate a **PhoneNumberFormat** object. The country code and formatting options of the phone number need to be passed into this constructor. The formatting options are optional, including a style option. Values of this option include: **E164**, **INTERNATIONAL**, **NATIONAL**, and **RFC3966**.
```
var phoneNumberFormat = new i18n.PhoneNubmerFormat("CN", {type: "E164"});
```
2. Check whether the phone number format is correct.
Call the **isValidNumber** method to check whether the format of the input phone number is correct.
```
var validNumber = phoneNumberFormat.isValidNumber("15812341234");
```
3. Format a phone number.
Call the **format** method of **PhoneNumberFormat** to format the input phone number.
```
var formattedNumber = phoneNumberFormat.format("15812341234");
```
## Measurement Conversion
An API can be called to implement measurement conversion.
### Available APIs
| Module | API | Description |
| -------- | -------- | -------- |
| ohos.i18n | unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale: string, style?: string): string8+ | Converts one measurement unit (**fromUnit**) into another (**toUnit**) and formats the unit based on the specified locale and style. |
### How to Develop
1. Convert a measurement unit.
Call the [unitConvert](../reference/apis/js-apis-intl.md) method to convert a measurement unit and format the display result.
```
var fromUnit = {unit: "cup", measureSystem: "US"};
var toUnit = {unit: "liter", measureSystem: "SI"};
var number = 1000;
var locale = "en-US";
var style = "long";
i18n.Util.unitConvert(fromUtil, toUtil, number, locale, style);
```
## Alphabet Index
[IndexUtil](../reference/apis/js-apis-intl.md) APIs are used to obtain the alphabet indexes of different locales and calculate the index to which a string belongs.
### Available APIs
| Module | API | Description |
| -------- | -------- | -------- |
| ohos.i18n | getInstance(locale?: string): IndexUtil8+ | Instantiates an **IndexUtil** object. |
| ohos.i18n | getIndexList(): Array<string>8+ | Obtains the index list of the current locale. |
| ohos.i18n | addLocale(locale: string): void8+ | Adds the index of a new locale to the index list. |
| ohos.i18n | getIndex(text: string): string8+ | Obtains the index of **text**. |
### How to Develop
1. Instantiate an **IndexUtil** object.
Call the **getInstance** method to instantiate an **IndexUtil** object for a specific locale. When the **locale** parameter is empty, instantiate an **IndexUtil** object of the default locale.
```
var indexUtil = getInstance("zh-CN");
```
2. Obtain the index list.
Call the **getIndexList** method to obtain the alphabet index list of the current locale.
```
var indexList = indexUtil.getIndexList();
```
3. Add an index.
Call the **addLocale** method to add the alphabet index of a new locale to the current index list.
```
indexUtil.addLocale("ar")
```
4. Obtain the index of a string.
Call the **getIndex** method to obtain the alphabet index of a string.
```
var text = "access index";
indexUtil.getIndex(text);
```
## Obtaining Line Breaks of Text
When a text is displayed in more than one line, [BreakIterator](../reference/apis/js-apis-intl.md) APIs are used to obtain the line break positions of the text.
### Available APIs
| Module | API | Description |
| -------- | -------- | -------- |
| ohos.i18n | getLineInstance(locale: string): BreakIterator8+ | Instantiates a **BreakIterator** object. |
| ohos.i18n | setLineBreakText(text: string): void8+ | Sets the text to be processed. |
| ohos.i18n | getLineBreakText(): string8+ | Obtains the text to be processed. |
| ohos.i18n | current(): number8+ | Obtains the current position of a **BreakIterator** object in the text being processed. |
| ohos.i18n | first(): number8+ | Sets a **BreakIterator** object to the first breakable point. |
| ohos.i18n | last(): number8+ | Sets a **BreakIterator** object to the last breakable point. |
| ohos.i18n | next(index?: number): number8+ | Moves a **BreakIterator** object to the break point according to **index**. |
| ohos.i18n | previous(): number8+ | Moves a **BreakIterator** object to the previous break point. |
| ohos.i18n | following(offset: number): number8+ | Moves a **BreakIterator** object to the break point following the position specified by **offset**. |
| ohos.i18n | isBoundary(offset: number): boolean8+ | Determines whether a position is a break point. |
### How to Develop
1. Instantiate a **BreakIterator** object.
Call the **getLineInstance** method to instantiate a **BreakIterator** object.
```
var locale = "en-US"
var breakIterator = i18n.getLineInstance(locale);
```
2. Set and access the text that requires line breaking.
Call the **setLineBreakText** and **getLineBreakText** methods to set and access the text that requires line breaking.
```
var text = "Apple is my favorite fruit";
breakIterator.setLineBreakText(text);
var breakText = breakIterator.getLineBreakText();
```
3. Obtain the current position of the **BreakIterator** object.
Call the **current** method to obtain the current position of the **BreakIterator** object in the text being processed.
```
var pos = breakIterator.current();
```
4. Set the position of a **BreakIterator** object.
The following APIs are provided to adjust the **first**, **last**, **next**, **previous**, or **following** position of the **BreakIterator** object in the text to be processed.
```
var firstPos = breakIterator.first(); // Sets a BreakIterator object to the first break point, that is, the start position of the text.
var lastPos = breakIterator.last(); // Sets a BreakIterator object to the last break point, that is, the position after the text end.
// Moves a BreakIterator object forward or backward by a certain number of break points.
// If a positive number is input, move backward. If a negative number is input, move forward. If no value is input, move one position backward.
// When the object is moved out of the text length range, -1 is returned.
var nextPos = breakIterator.next(-2);
var previousPos = breakIterator.previous(); // Moves a BreakIterator object to the previous break point. When the text length is out of the range, -1 is returned.
// Moves a BreakIterator object to the break point following the position specified by offset. If the object is moved out of the text length range, -1 is returned.
var followingPos = breakIterator.following(10);
```
5. Determine whether a position is a break point.
Call the **isBoundary** method to determine whether a position is a break point. If yes, **true** is returned and the **BreakIterator** object is moved to this position. If no, **false** is returned and the **BreakIterator** object is moved to a break point after this position.
```
var isboundary = breakIterator.isBoundary(5);
```