This development guide describes how to use i18n APIs that are not defined in ECMA 402.
This module provides system-related or enhanced I18N capabilities, such as locale management, phone number formatting, and calendar, through supplementary I18N APIs that are not defined in ECMA 402. For more details about APIs and their usage, see [I18N](../reference/apis/js-apis-i18n.md).
The [Intl](intl-guidelines.md) module provides basic I18N capabilities through the standard I18N APIs defined in ECMA 402. It works with the I18N module to provide a complete suite of I18N capabilities.
## Obtaining System Language and Region Information
APIs are provided to access the system language and region information.
You can use APIs provided in the following table to obtain the system language and region information.
### Available APIs
| Module | API | Description |
| Module | API | Description |
| -------- | -------- | -------- |
| ohos.i18n | getSystemLanguage(): string | Obtains the system language. |
| ohos.i18n | getSystemRegion(): string | Obtains the system region. |
...
...
@@ -17,52 +19,58 @@ APIs are provided to access the system language and region information.
| ohos.i18n | isRTL(locale: string): boolean<sup>7+</sup> | Checks whether the locale uses a right-to-left (RTL) language. |
| ohos.i18n | is24HourClock(): boolean<sup>7+</sup> | 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. |
| ohos.i18n | getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): string | Obtains the localized display of a country name. |
### 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).
```
```js
varlanguage=i18n.getSystemLanguage();
```
2. Obtains the system region.
2. Obtain the system region.
Call the **getSystemRegion** method to obtain the system region.
```
```js
var region = i18n.getSystemRegion();
```
3. Obtain the system locale.
Call the **getSystemLocale** method to obtain the system locale.
```
```js
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.
```
```js
varrtl=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.
```
```js
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.
```
```js
var language = "en";
var locale = "zh-CN";
var sentenceCase = false;
...
...
@@ -70,9 +78,10 @@ APIs are provided to access the system language and region information.
```
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.
```
Call the **getDisplayCountry** method to obtain the localized display of a country name. **country** indicates the country code (a two-letter code in compliance with ISO-3166, for example, CN), **locale** indicates the locale, and **sentenceCase** indicates whether the first letter of the result must be capitalized.
```js
var country = "US";
var locale = "zh-CN";
var sentenceCase = false;
...
...
@@ -82,7 +91,7 @@ APIs are provided to access the system language and region information.
## 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.
[Calendar](../reference/apis/js-apis-i18n.md#calendar8) 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
...
...
@@ -106,17 +115,19 @@ APIs are provided to access the system language and region information.
### 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);
```js
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.
```
```js
var date1 = new Date();
calendar.setTime(date1);
var date2 = 1000;
...
...
@@ -124,51 +135,57 @@ APIs are provided to access the system language and region information.
```
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.
```
```js
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.
```
```js
calendar.setTimeZone("Asia/Shanghai");
vartimezone=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.
```
```js
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.
```
```js
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.
Call the **isWeekend** method to determine whether the input date is a weekend.
```
```js
var date = new Date();
var weekend = calendar.isWeekend(date);
```
...
...
@@ -176,12 +193,12 @@ APIs are provided to access the system language and region information.
## 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.
[PhoneNumberFormat](../reference/apis/js-apis-i18n.md#phonenumberformat8) APIs are used to format phone numbers in different countries and check whether the phone number formats are correct.
| ohos.i18n | isValidNumber(number: string): boolean<sup>8+</sup> | Checks whether the value of **number** is a phone number in the correct format. |
...
...
@@ -191,36 +208,37 @@ APIs are provided to access the system language and region information.
### 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"});
```js
var phoneNumberFormat = new i18n.PhoneNumberFormat("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.
Call the **format** method of **PhoneNumberFormat** to format the input phone number.
```
```js
var formattedNumber = phoneNumberFormat.format("15812341234");
```
## Measurement Conversion
An API can be called to implement measurement conversion.
The **unitConvert** API is provided to help you implement measurement conversion.
### Available APIs
| Module | API | Description |
| Module | API | Description |
| -------- | -------- | -------- |
| ohos.i18n | unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale: string, style?: string): string<sup>8+</sup> | Converts one measurement unit (**fromUnit**) into another (**toUnit**) and formats the unit based on the specified locale and style. |
...
...
@@ -228,10 +246,10 @@ An API can be called to implement measurement conversion.
### 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.
Call the [unitConvert](../reference/apis/js-apis-i18n.md#unitconvert8) method to convert a measurement unit and format the display result.
```
```js
var fromUnit = {unit: "cup", measureSystem: "US"};
var toUnit = {unit: "liter", measureSystem: "SI"};
var number = 1000;
...
...
@@ -243,7 +261,7 @@ An API can be called to implement measurement conversion.
## 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.
[IndexUtil](../reference/apis/js-apis-i18n.md#indexutil8) APIs are used to obtain the alphabet indexes of different locales and calculate the index to which a string belongs.
### Available APIs
...
...
@@ -259,31 +277,35 @@ An API can be called to implement measurement conversion.
### 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");
```js
varindexUtil=i18n.getInstance("zh-CN");
```
2. Obtain the index list.
Call the **getIndexList** method to obtain the alphabet index list of the current locale.
```
```js
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.
```
```js
indexUtil.addLocale("ar")
```
4. Obtain the index of a string.
Call the **getIndex** method to obtain the alphabet index of a string.
```
```js
var text = "access index";
indexUtil.getIndex(text);
```
...
...
@@ -291,7 +313,7 @@ An API can be called to implement measurement conversion.
## 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.
When a text is displayed in more than one line, [BreakIterator8](../reference/apis/js-apis-i18n.md#breakiterator8) APIs are used to obtain the line break positions of the text.
### Available APIs
...
...
@@ -313,52 +335,57 @@ When a text is displayed in more than one line, [BreakIterator](../reference/api
### How to Develop
1. Instantiate a **BreakIterator** object.
Call the **getLineInstance** method to instantiate a **BreakIterator** object.
```
```js
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.
```
```js
vartext="Apple is my favorite fruit";
breakIterator.setLineBreakText(text);
varbreakText=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.
```
```js
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.
```js
var firstPos = breakIterator.first(); // Set a BreakIterator object to the first break point, that is, the start position of the text.
var lastPos = breakIterator.last(); // Set a BreakIterator object to the last break point, that is, the position after the text end.
// Move 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 previousPos = breakIterator.previous(); // Move a BreakIterator object to the previous break point. When the text length is out of the range, -1 is returned.
// Move 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.
> - The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
This module provides system-related or enhanced I18N capabilities, such as locale management, phone number formatting, and calendar, through supplementary I18N APIs that are not defined in ECMA 402.
The [Intl](intl-guidelines.md) module provides basic I18N capabilities through the standard I18N APIs defined in ECMA 402. It works with the I18N module to provide a complete suite of I18N capabilities.
> **NOTE**
>
> - This module contains enhanced i18n APIs, which are not defined in ECMA 402.
> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.
## Modules to Import
...
...
@@ -50,14 +54,14 @@ Obtains the localized script for the specified country.
| flag | boolean | Yes | Whether to turn on the local digit switch. The value **true** means to turn on the local digit switch, and the value **false** indicates the opposite.|
**Return value**
| Type | Description |
| ------- | ----------------------------------- |
| boolean | Result indicating whether the local digit switch is successfully set. The value **true** indicates that the local digit switch is successfully set, and the value **false** indicates the opposite.|
**Example**
```ts
varstatus=i18n.setUsingLocalDigit(true);
```
## i18n.getUsingLocalDigit<sup>9+</sup>
getUsingLocalDigit(): boolean
Checks whether the local digit switch is turned on.
| boolean | Result indicating whether the local digit switch is turned on. The value **true** indicates that the local digit switch is turned on, and the value **false** indicates the opposite.|
**Example**
```ts
varstatus=i18n.getUsingLocalDigit();
```
## Transliterator<sup>9+</sup>
### getAvailableIDs<sup>9+</sup>
static getAvailableIDs(): string[]
Obtains a list of IDs supported by the **Transliterator** object.
> - The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
This module provides basic I18N capabilities, such as time and date formatting, number formatting, and string sorting, through the standard I18N APIs defined in ECMA 402.
The [I18N](i18n-guidelines.md) module provides enhanced I18N capabilities through supplementary APIs that are not defined in ECMA 402. It works with the Intl module to provide a complete suite of I18N capabilities.
> **NOTE**
>
> - This module contains standard i18n APIs, which are defined in ECMA 402.
> The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
@@ -461,7 +464,7 @@ Compares two strings based on the sorting policy of the **Collator** object.
| number | Comparison result. If the value is a negative number, the first string is before the second string. If the value of number is **0**, the first string is equal to the second string. If the value of number is a positive number, the first string is after the second string.|
**Example**
```
```js
varcollator=newIntl.Collator("zh-Hans");
collator.compare("first","second");
```
...
...
@@ -481,13 +484,13 @@ Returns properties reflecting the locale and collation options of a **Collator**
| [CollatorOptions](#collatoroptions) | Properties of the **Collator** object.|
