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 **i18n** 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).
## Obtaining System Language and Region Information
The [intl](intl-guidelines.md) module provides basic i18n capabilities through the standard i18n interfaces defined in ECMA 402. It works with the **i18n** module to provide a complete suite of i18n capabilities.
You can use APIs provided in the following table to obtain the system language and region information.
## Obtaining and Setting i18n Information
The system provides APIs to configure information such as the system language, preferred language, country or region, 24-hour clock, and local digit switch.
| ohos.i18n | getSystemLanguage(): string | Obtains the system language. |
| System | getDisplayCountry(country:string,locale:string,sentenceCase?:boolean):string<sup>9+</sup> | Obtains the localized representation of a country. |
| ohos.i18n | getSystemRegion(): string | Obtains the system region. |
| System | getDisplayLanguage(language:string,locale:string,sentenceCase?:boolean):string<sup>9+</sup> | Obtains the localized representation of a language. |
| ohos.i18n | getSystemLocale(): string | Obtains the system locale. |
| System | getSystemLanguages():Array<string><sup>9+</sup> | Obtains the system language list. |
| ohos.i18n | isRTL(locale: string): boolean<sup>7+</sup> | Checks whether the locale uses a right-to-left (RTL) language. |
| System | getSystemCountries(language: string):Array<string><sup>9+</sup> | Obtains the list of countries and regions supported for the specified language. |
| ohos.i18n | is24HourClock(): boolean<sup>7+</sup> | Checks whether the system uses a 24-hour clock. |
| System | isSuggested(language: string, region?: string): boolean<sup>9+</sup> | Checks whether the system language matches the specified region. |
| ohos.i18n | getDisplayLanguage(language: string, locale: string, sentenceCase?: boolean): string | Obtains the localized display of a language. |
| System | getSystemLanguage():string<sup>9+</sup> | Obtains the system language. |
| ohos.i18n | getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): string | Obtains the localized display of a country name. |
| System | setSystemLanguage(language: string)<sup>9+</sup> | Sets the system language. |
| System | getSystemRegion():string<sup>9+</sup> | Obtains the system region. |
| System | setSystemRegion(region: string)<sup>9+</sup> | Sets the system region. |
| System | getSystemLocale():string<sup>9+</sup> | Obtains the system locale. |
| System | setSystemLocale(locale: string)<sup>9+</sup> | Sets the system locale. |
| System | is24HourClock():boolean<sup>9+</sup> | Checks whether the 24-hour clock is used. |
| System | set24HourClock():boolean<sup>9+</sup> | Sets the 24-hour clock. |
| System | addPreferredLanguage(language: string, index?: number)<sup>9+</sup> | Adds a preferred language to the specified position on the preferred language list. |
| System | removePreferredLanguage(index: number)<sup>9+</sup> | Deletes a preferred language from the specified position on the preferred language list. |
| System | getPreferredLanguageList()<sup>9+</sup> | Obtains the preferred language list. |
| System | getFirstPreferredLanguage()<sup>9+</sup> | Obtains the first language in the preferred language list. |
| System | getAppPreferredLanguage()<sup>9+</sup> | Obtains the preferred language of an application. |
| System | setUsingLocalDigit(flag: boolean)<sup>9+</sup> | Sets whether to enable the local digit switch. |
| System | getUsingLocalDigit()<sup>9+</sup> | Checks whether the local digit switch is turned on. |
| | isRTL(locale:string):boolean<sup>9+</sup> | Checks whether the locale uses a right-to-left (RTL) language.|
### How to Develop
### How to Develop
1. Import the **i18n** module.
1. Obtain the system language.
```js
importI18nfrom'@ohos.i18n'
```
Call the **getSystemLanguage** method to obtain the system language (**i18n** is the name of the imported module).
2. Obtain and set the system language.
Call **setSystemLanguage** to set the system language. (This is a system API and can be called only by system applications with the **UPDATE_CONFIGURATION** permission.)
Call the **getSystemLanguage** API to obtain the system language.
```js
```js
let language = i18n.getSystemLanguage();
try{
I18n.System.setSystemLanguage("en");// Set the system language to en.
letlanguage=I18n.System.getSystemLanguage();// language = "en"
Call the **getSystemRegion** method to obtain the system region.
Call **setSystemRegion** to set the system country or region. (This is a system API and can be called only by system applications with the **UPDATE_CONFIGURATION** permission.)
Call **getSystemRegion** to obtain the system country or region.
```js
```js
let region = i18n.getSystemRegion();
try{
I18n.System.setSystemRegion("CN");// Set the system country to CN.
letregion=I18n.System.getSystemRegion();// region = "CN"
Call the **getSystemLocale** method to obtain the system locale.
Call **setSystemLocale** to set the system locale. (This is a system API and can be called only by system applications with the **UPDATE_CONFIGURATION** permission.) For details about how to set a locale, see [Setting Locale Information](../internationalization/intl-guidelines.md#setting-locale-information).
Call **getSystemLocale** to obtain the system locale.
```js
```js
let locale = i18n.getSystemLocale();
try{
I18n.System.setSystemLocale("zh-Hans-CN");// Set the system locale to zh-Hans-CN.
7. Obtain the localized representation 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.
Call **getDisplayLanguage** to obtain the localized representation 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
```js
try{
letlanguage="en";
letlanguage="en";
letlocale="zh-CN";
letlocale="zh-CN";
letsentenceCase=false;
letsentenceCase=false;
let localizedLanguage = i18n.getDisplayLanguage(language, locale, sentenceCase);
8. Obtain the localized representation of a country.
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.
Call **getDisplayCountry** to obtain the localized representation 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.
```js
```js
try{
letcountry="US";
letcountry="US";
letlocale="zh-CN";
letlocale="zh-CN";
letsentenceCase=false;
letsentenceCase=false;
let localizedCountry = i18n.getDisplayCountry(country, locale, sentenceCase);
9. Obtain the list of system languages and the list of countries supported by a system language.
## Obtaining Calendar Information
Call **getSystemLanguages** to obtain the list of system languages.
Call **getSystemCountries** to obtain the list of countries and regions supported by a system language.
```js
[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.
Call **addPreferredLanguage** to add a preferred language to the preferred language list.
| -------- | -------- | -------- |
Call **removePreferredLanguage** to remove a preferred language from the preferred language list. (**addPreferredLanguage** and **removePreferredLanguage** are system APIs and can be called only by system applications with the **UPDATE_CONFIGURATION** permission.)
| ohos.i18n | getCalendar(locale: string, type?: string): Calendar<sup>8+</sup> | Obtains the **Calendar** object for a specific locale and type. |
Call **getPreferredLanguageList** to obtain the preferred language list.
| ohos.i18n | setTime(date: Date): void<sup>8+</sup> | Sets the date for the **Calendar** object. |
Call **getFirstPreferredLanguage** to obtain the first preferred language in the preferred language list.
| ohos.i18n | setTime(time: number): void<sup>8+</sup> | Sets the time for the **Calendar** object. |
Call **getAppPreferredLanguageList** to obtain the preferred language of the application. It is the first language that matches the application resource in the preferred language list.
| ohos.i18n | set(year: number, month: number, date: number, hour?: number, minute?: number, second?: number): void<sup>8+</sup> | Sets the year, month, day, hour, minute, and second for the **Calendar** object. |
| ohos.i18n | setTimeZone(timezone: string): void<sup>8+</sup> | Sets the time zone for the **Calendar** object. |
| ohos.i18n | getTimeZone(): string<sup>8+</sup> | Obtains the time zone for the **Calendar** object. |
| ohos.i18n | getFirstDayOfWeek(): number<sup>8+</sup> | Obtains the first day of a week for the **Calendar** object. |
| ohos.i18n | setFirstDayOfWeek(value: number): void<sup>8+</sup> | Sets the first day of a week for the **Calendar** object. |
| ohos.i18n | getMinimalDaysInFirstWeek(): number<sup>8+</sup> | Obtains the minimum count of days in the first week of a year. |
| ohos.i18n | setMinimalDaysInFirstWeek(value: number): void<sup>8+</sup> | Sets the minimum count of days in the first week of a year. |
| ohos.i18n | getDisplayName(locale: string): string<sup>8+</sup> | Obtains the localized display of the **Calendar** object. |
| ohos.i18n | isWeekend(date?: Date): boolean<sup>8+</sup> | Checks whether a given date is a weekend. |
```js
try{
I18n.System.addPreferredLanguage("en-GB",0);// Set the first language in the preferred language list to en-GB.
letlist=I18n.System.getPreferredLanguageList();// Obtain the preferred language list. Example: list = ["en-GB", ...]
I18n.System.removePreferredLanguage(list.length-1);// Remove the last preferred language from the preferred language list.
letappPreferredLanguage=I18n.System.getAppPreferredLanguage();// Set the preferred language of the application to en-GB if the application contains en-GB resources.
Call **setUsingLocalDigit** to enable the local digit switch. (This is a system API and can be called only by system applications with the UPDATE_CONFIGURATION permission.)
Call **getUsingLocalDigit** to check whether the local digit switch is enabled.
Currently, the local digit switch applies only to the following languages: "ar", "as", "bn", "fa", "mr", "my", "ne", and "ur".
```js
try{
I18n.System.setUsingLocalDigit(true);// Enable the local digit switch.
letstatus=I18n.System.getUsingLocalDigit();// status = true
[Calendar](../reference/apis/js-apis-i18n.md#calendar8) provides APIs to obtain calendar information, for example, localized representation of the calendar, the start day of a week, and the minimum number of days in the first week of a year.
| | getCalendar(locale:string,type?:string):Calendar<sup>8+</sup> | Obtains the **Calendar** object for a specific locale and type.|
| Calendar | setTime(date:Date): void<sup>8+</sup> | Sets the date for this **Calendar** object. |
| Calendar | setTime(time:number): void<sup>8+</sup> | Sets the date for this **Calendar** object. |
| Calendar | set(year:number,month:number,date:number,hour?:number,minute?:number,second?:number): void<sup>8+</sup> | Sets the year, month, day, hour, minute, and second for this **Calendar** object. |
| Calendar | setTimeZone(timezone:string): void<sup>8+</sup> | Sets the time zone of this **Calendar** object. |
| Calendar | getTimeZone():string<sup>8+</sup> | Obtains the time zone of this **Calendar** object. |
| Calendar | getFirstDayOfWeek():number<sup>8+</sup> | Obtains the start day of a week for this **Calendar** object. |
| Calendar | setFirstDayOfWeek(value:number): void<sup>8+</sup> | Sets the first day of a week for the **Calendar** object. |
| Calendar | getMinimalDaysInFirstWeek():number<sup>8+</sup> | Obtains the minimum number of days in the first week of a year. |
| Calendar | setMinimalDaysInFirstWeek(value:number): void<sup>8+</sup> | Sets the minimum number of days in the first week of a year. |
| Calendar | getDisplayName(locale:string):string<sup>8+</sup> | Obtains the localized display of the **Calendar** object. |
| Calendar | isWeekend(date?:Date):boolean<sup>8+</sup> | Checks whether the specified date in this **Calendar** object is a weekend. |
### How to Develop
### How to Develop
1. Instantiate a **Calendar** object.
1. Import the **i18n** module.
```js
importI18nfrom'@ohos.i18n'
```
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.
2. Instantiate a **Calendar** object.
Call **getCalendar** 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.
```js
```js
let calendar = i18n.getCalendar("zh-CN", "gregory");
letcalendar=I18n.getCalendar("zh-CN","chinese");// Create the Calendar object for the Chinese lunar calendar.
```
```
2. Set the time for the **Calendar** object.
3. 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.
Call **setTime** to set the time of the **Calendar** object. Two types of parameters are supported. 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
```js
letdate1=newDate();
letdate1=newDate();
...
@@ -132,120 +249,122 @@ You can use APIs provided in the following table to obtain the system language a
...
@@ -132,120 +249,122 @@ You can use APIs provided in the following table to obtain the system language a
calendar.setTime(date2);
calendar.setTime(date2);
```
```
3. Set the year, month, day, hour, minute, and second for the **Calendar** object.
4. Set the year, month, day, hour, minute, and second for this**Calendar** object.
Call the **set** method to set the year, month, day, hour, minute, and second for the **Calendar** object.
Call **set** to set the year, month, day, hour, minute, and second for the **Calendar** object.
```js
```js
calendar.set(2021,12,21,6,0,0)
calendar.set(2021,12,21,6,0,0)
```
```
4. Set and obtain the time zone for the **Calendar** object.
5. 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.
Call **setTimeZone** and **getTimeZone** to set and obtain the time zone of the **Calendar** object. Note that **setTimeZone** requires an input string to indicate the time zone to be set.
```js
```js
calendar.setTimeZone("Asia/Shanghai");
calendar.setTimeZone("Asia/Shanghai");
let timezone = calendar.getTimeZone();
lettimezone=calendar.getTimeZone();// timezone = "China Standard Time"
```
```
5. Set and obtain the first day of a week for the **Calendar** object.
6. 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.
Call **setFirstDayOfWeek** and **getFirstDayOfWeek** to set and obtain the start 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
```js
calendar.setFirstDayOfWeek(1);
calendar.setFirstDayOfWeek(1);
let firstDayOfWeek = calendar.getFirstDayOfWeek();
6. Set and obtain the minimum count of days in the first week for the **Calendar** object.
7. Set and obtain the minimum count of days in the first week for the **Calendar** object.
Call **setMinimalDaysInFirstWeek** and **getMinimalDaysInFirstWeek** to set and obtain the minimum number 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
```js
calendar.setMinimalDaysInFirstWeek(3);
calendar.setMinimalDaysInFirstWeek(3);
let minimalDaysInFirstWeek = calendar.getMinimalDaysInFirstWeek();
[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.
[PhoneNumberFormat](../reference/apis/js-apis-i18n.md#phonenumberformat8) provides APIs to format phone numbers of different countries or regions and check whether the phone number format is correct.
| PhoneNumberFormat | constructor(country:string,options?:PhoneNumberFormatOptions)<sup>8+</sup> | Instantiates a **PhoneNumberFormat** object.|
| ohos.i18n | isValidNumber(number: string): boolean<sup>8+</sup> | Checks whether the value of **number** is a phone number in the correct format. |
| PhoneNumberFormat | isValidNumber(number:string):boolean<sup>8+</sup> | Checks whether the value of **number** is a phone number in the correct format.|
| ohos.i18n | format(number: string): string<sup>8+</sup> | Formats the value of **number** based on the specified country and style. |
| PhoneNumberFormat | format(number:string):string<sup>8+</sup> | Formats the value of **number** based on the specified country and style. |
| PhoneNumberFormat | getLocationName(number: string, locale: string): string<sup>9+</sup> | Obtains the home location of a phone number. |
### How to Develop
### How to Develop
1. Instantiate a **PhoneNumberFormat** object.
1. Import the **i18n** module.
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**.
```js
importI18nfrom'@ohos.i18n'
```
2. 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**.
```js
```js
let phoneNumberFormat = new i18n.PhoneNumberFormat("CN", {type: "E164"});
| 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. |
| I18NUtil | unitConvert(fromUnit:UnitInfo,toUnit:UnitInfo,value:number,locale:string,style?:string):string<sup>9+</sup> | Converts one measurement unit into another and formats the unit based on the specified locale and style.|
### How to Develop
### How to Develop
1. Convert a measurement unit.
1. Import the **i18n** module.
Call the [unitConvert](../reference/apis/js-apis-i18n.md#unitconvert9) method to convert a measurement unit and format the display result.
```js
importI18nfrom'@ohos.i18n'
```
2. Convert a measurement unit.
Call [unitConvert](../reference/apis/js-apis-i18n.md#unitconvert9) to convert a measurement unit and format the display result.
```js
```js
letfromUnit={unit:"cup",measureSystem:"US"};
letfromUnit={unit:"cup",measureSystem:"US"};
...
@@ -253,139 +372,361 @@ The **unitConvert** API is provided to help you implement measurement conversion
...
@@ -253,139 +372,361 @@ The **unitConvert** API is provided to help you implement measurement conversion
[IndexUtil](../reference/apis/js-apis-i18n.md#indexutil8) provides APIs 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.
| | getInstance(locale?:string):IndexUtil<sup>8+</sup> | Instantiates an **IndexUtil** object. |
| ohos.i18n | getIndexList(): Array<string><sup>8+</sup> | Obtains the index list of the current locale. |
| IndexUtil | getIndexList():Array<string><sup>8+</sup> | Obtains the index list of the current locale. |
| ohos.i18n | addLocale(locale: string): void<sup>8+</sup> | Adds the index of a new locale to the index list. |
| IndexUtil | addLocale(locale:string): void<sup>8+</sup> | Adds the index of a new locale to the index list.|
| ohos.i18n | getIndex(text: string): string<sup>8+</sup> | Obtains the index of **text**. |
| IndexUtil | getIndex(text:string):string<sup>8+</sup> | Obtains the index of a text object. |
### How to Develop
### How to Develop
1. Instantiate an **IndexUtil** object.
1. Import the **i18n** module.
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.
```js
importI18nfrom'@ohos.i18n'
```
2. Instantiates an **IndexUtil** object.
Call **getInstance** to instantiate an **IndexUtil** object for a specific locale. When the **locale** parameter is empty, instantiate an **IndexUtil** object of the default locale.
```js
```js
let indexUtil = i18n.getInstance("zh-CN");
letindexUtil=I18n.getInstance("zh-CN");
```
```
2. Obtain the index list.
3. Obtain the index list.
Call the **getIndexList** method to obtain the alphabet index list of the current locale.
Call **getIndexList** to obtain the alphabet index list of the current locale.
Call the **addLocale** method to add the alphabet index of a new locale to the current index list.
Call **addLocale** to add the alphabet index of a new locale to the current index list.
```js
```js
indexUtil.addLocale("ar")
indexUtil.addLocale("ar")
```
```
4. Obtain the index of a string.
5. Obtain the index of a string.
Call the **getIndex** method to obtain the alphabet index of a string.
Call **getIndex** to obtain the alphabet index of a string.
```js
```js
lettext="access index";
lettext="access index";
indexUtil.getIndex(text);
letindex=indexUtil.getIndex(text);// index = "A"
```
```
## Obtaining Line Breaks of Text
## Obtaining Line Breaks of 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.
When a text is displayed in more than one line, use [BreakIterator8](../reference/apis/js-apis-i18n.md#breakiterator8) APIs to obtain the line break positions of the text.
| | getLineInstance(locale:string):BreakIterator<sup>8+</sup> | Instantiates a **BreakIterator** object. |
| ohos.i18n | setLineBreakText(text: string): void<sup>8+</sup> | Sets the text to be processed. |
| BreakIterator | setLineBreakText(text:string): void<sup>8+</sup> | Sets the text to be processed. |
| ohos.i18n | getLineBreakText(): string<sup>8+</sup> | Obtains the text to be processed. |
| BreakIterator | getLineBreakText():string<sup>8+</sup> | Obtains the text to be processed. |
| ohos.i18n | current(): number<sup>8+</sup> | Obtains the current position of a **BreakIterator** object in the text being processed. |
| BreakIterator | current():number<sup>8+</sup> | Obtains the current position of a **BreakIterator** object in the text being processed. |
| ohos.i18n | first(): number<sup>8+</sup> | Sets a **BreakIterator** object to the first breakable point. |
| BreakIterator | first():number<sup>8+</sup> | Sets a **BreakIterator** object to the first breakable point. |
| ohos.i18n | last(): number<sup>8+</sup> | Sets a **BreakIterator** object to the last breakable point. |
| BreakIterator | last():number<sup>8+</sup> | Sets a **BreakIterator** object to the last breakable point. |
| ohos.i18n | next(index?: number): number<sup>8+</sup> | Moves a **BreakIterator** object to the break point according to **index**. |
| BreakIterator | next(index?:number):number<sup>8+</sup> | Moves a **BreakIterator** object to the break point according to **index**. |
| ohos.i18n | previous(): number<sup>8+</sup> | Moves a **BreakIterator** object to the previous break point. |
| BreakIterator | previous():number<sup>8+</sup> | Moves a **BreakIterator** object to the previous break point. |
| ohos.i18n | following(offset: number): number<sup>8+</sup> | Moves a **BreakIterator** object to the break point following the position specified by **offset**. |
| BreakIterator | following(offset:number):number<sup>8+</sup> | Moves a **BreakIterator** object to the break point following the position specified by **offset**.|
| ohos.i18n | isBoundary(offset: number): boolean<sup>8+</sup> | Determines whether a position is a break point. |
| BreakIterator | isBoundary(offset:number):boolean<sup>8+</sup> | Determines whether a position is a break point. |
### How to Develop
### How to Develop
1. Instantiate a **BreakIterator** object.
1. Import the **i18n** module.
```js
importI18nfrom'@ohos.i18n'
```
Call the **getLineInstance** method to instantiate a **BreakIterator** object.
2. Instantiate a **BreakIterator** object.
Call **getLineInstance** to instantiate a **BreakIterator** object.
```js
```js
letlocale="en-US"
letlocale="en-US"
let breakIterator = i18n.getLineInstance(locale);
letbreakIterator=I18n.getLineInstance(locale);
```
```
2. Set and access the text that requires line breaking.
3. 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.
Call **setLineBreakText** and **getLineBreakText** to set and access the text that requires line breaking.
```js
```js
lettext="Apple is my favorite fruit";
lettext="Apple is my favorite fruit";
breakIterator.setLineBreakText(text);
breakIterator.setLineBreakText(text);
let breakText = breakIterator.getLineBreakText();
letbreakText=breakIterator.getLineBreakText();// breakText = "Apple is my favorite fruit"
```
```
3. Obtain the current position of the **BreakIterator** object.
4. 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.
Call **current** to obtain the current position of the **BreakIterator** object in the text being processed.
```js
```js
let pos = breakIterator.current();
letpos=breakIterator.current();// pos = 0
```
```
4. Set the position of a **BreakIterator** object.
5. 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.
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.
```js
```js
let firstPos = breakIterator.first(); // Set a BreakIterator object to the first break point, that is, the start position of the text.
letfirstPos=breakIterator.first();// Set a BreakIterator object to the first break point, that is, the start position of the text (firstPos = 0).
let lastPos = breakIterator.last(); // Set a BreakIterator object to the last break point, that is, the position after the text end.
letlastPos=breakIterator.last();// Sets a BreakIterator object to the last break point, that is, the position after the text end (lastPos = 26).
// Move a BreakIterator object forward or backward by a certain number of break points.
// 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.
// 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.
// If the object is moved out of the text length range, **-1** is returned.
let nextPos = breakIterator.next(-2);
letnextPos=breakIterator.next(-2);// nextPos = 12
let previousPos = breakIterator.previous(); // Move a BreakIterator object to the previous break point. When the text length is out of the range, -1 is returned.
letpreviousPos=breakIterator.previous();// Move a BreakIterator object to the previous break point. When the text length is out of the range, **-1** is returned. Example: previousPos = 9
// 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.
// 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.
Call **isBoundary** 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.
[TimeZone](../reference/apis/js-apis-i18n.md#timezone) provides APIs to obtain time zone information, such as the time zone ID, localized representation, and time zone offset.
| TimeZone | getID(): string<sup>7+</sup> | Obtains the time zone ID. |
| TimeZone | getDisplayName(locale?: string, isDST?: boolean): string<sup>7+</sup> | Obtains the localized representation of the time zone. |
| TimeZone | getRawOffset(): number<sup>7+</sup> | Obtains the offset between the time zone represented by a **TimeZone** object and the UTC time zone. |
| TimeZone | getOffset(date?: number): number<sup>7+</sup> | Obtains the offset between the time zone represented by a **TimeZone** object and the UTC time zone at a certain time point. |
| TimeZone | getAvailableIDs(): Array<string><sup>9+</sup> | Obtains the list of time zone IDs supported by the system. |
| TimeZone | getAvailableZoneCityIDs(): Array<string><sup>9+</sup> | Obtains the list of time zone city IDs supported by the system. |
| TimeZone | getCityDisplayName(cityID: string, locale: string): string<sup>9+</sup> | Obtains the localized representation of a time zone city in the specified locale. |
| TimeZone | getTimezoneFromCity(cityID: string): TimeZone<sup>9+</sup> | Obtains the **TimeZone** object corresponding to the specified time zone ID.|
### How to Develop
1. Import the **i18n** module.
```js
importI18nfrom'@ohos.i18n'
```
```
5. Determine whether a position is a break point.
2. Instantiate the **TimeZone** object, and obtain the time zone information.
Call **getTimeZone** to obtain the **TimeZone** object.
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.
```js
lettimezone=I18n.getTimeZone();// If you use the default settings, you'll obtain the TimeZone object corresponding to the system time zone.
```
Obtain the time zone ID, localized representation, time zone offset, and time zone offset at a certain time point.
lettimezoneDisplayName=timezone.getDisplayName();// timezoneDisplayName = "New Zealand Standard Time"
```
## Obtain the **Transliterator** object.
Call [Transliterator](../reference/apis/js-apis-i18n.md#transliterator9) APIs to create a **Transliterator** object and obtain the transliterated string.
[Unicode](../reference/apis/js-apis-i18n.md#unicode9) provides APIs to obtain character information, for example, whether a character is a digit or a space.
| I18NUtil | getDateOrder(locale: string): string<sup>9+</sup> | Checks the sequence of year, month, and day in a date. |
### How to Develop
1. Import the **i18n** module.
```js
importI18nfrom'@ohos.i18n'
```
2. Check the sequence of year, month, and day in a date.
Call **getDateOrder** to obtain the sequence of year, month, and day in the date of the specified locale.
The API returns a string consisting of three parts, **y**, **L**, and **d**, which indicate the year, month, and day, respectively. The three parts are separated by using a hyphen (-), for example, **y-L-d**.
```js
letorder=I18n.I18NUtil.getDateOrder("zh-CN");// order = "y-L-d" indicates that the sequence of year, month, and day in Chinese is year-month-day.
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. For more details about APIs and their usage, see [Intl](../reference/apis/js-apis-intl.md).
The **intl** 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. For more details about APIs and their usage, see [intl](../reference/apis/js-apis-intl.md).
> **NOTE**
The [I18N](i18n-guidelines.md) module provides enhanced I18N capabilities through supplementary interfaces that are not defined in ECMA 402. It works with the Intl module to provide a complete suite of I18N capabilities.
>
> In the code snippets in this document, **intl** refers to the name of the imported module.
## Setting Locale Information
## Setting Locale Information
Use [Locale](../reference/apis/js-apis-intl.md#locale) APIs to maximize or minimize locale information.
[Locale](../reference/apis/js-apis-intl.md#locale) provides APIs to maximize or minimize the locale information.
### Available APIs
### Available APIs
| Module | API | Description |
| Class| API| Description|
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| ohos.intl | constructor()<sup>8+</sup> | Instantiates a **Locale** object. |
| Locale | constructor()<sup>8+</sup> | Instantiates a **Locale** object.|
| ohos.intl | constructor(locale?: string, options?: options) | Instantiates a **Locale** object based on the locale parameter and options. |
| Locale | constructor(locale:string,options?:LocaleOptions) | Instantiates a **Locale** object based on the locale parameter and options.|
| ohos.intl | toString(): string | Converts locale information into a string. |
| Locale | toString():string | Converts locale information into a string.|
Importing an incorrect bundle can lead to unexpected API behavior.
```js
importIntlfrom'@ohos.intl'
```
2. Instantiates a **Locale** object.
Create a **Locale** object by using the **Locale** constructor. This method receives a string representing the locale and an optional [Attributes](../reference/apis/js-apis-intl.md#localeoptions) list.
Create a **Locale** object using the **Locale** constructor. This API receives a string representing the locale and an optional [attribute](../reference/apis/js-apis-intl.md#localeoptions) list. (Note that **intl** is the name of the imported module.)
A **Locale** object consists of four parts: language, script, region, and extension, which are separated by using a hyphen (-).
A **Locale** object consists of four parts: language, script, region, and extension, which are separated by using a hyphen (-).
- Language: mandatory. It is represented by a two-letter or three-letter code as defined in ISO-639. For example, **en** indicates English and **zh** indicates Chinese.
- Language: mandatory. It is represented by a two-letter or three-letter code as defined in ISO-639. For example, **en** indicates English and **zh** indicates Chinese.
- Script: optional. It is represented by a four-letter code as defined in ISO-15924. The first letter is in uppercase, and the remaining three letters are in lowercase. For example, **Hant** represents the traditional Chinese, and **Hans** represents the simplified Chinese.
- Script: optional. It is represented by a four-letter code as defined in ISO-15924. The first letter is in uppercase, and the remaining three letters are in lowercase. For example, **Hant** represents the traditional Chinese, and **Hans** represents the simplified Chinese.
- Country or region: optional. It is represented by two-letter code as defined in ISO-3166. Both letters are in uppercase. For example, **CN** represents China, and **US** represents the United States.
- Country or region: optional. It is represented by two-letter code as defined in ISO-3166. Both letters are in uppercase. For example, **CN** represents China, and **US** represents the United States.
- Extensions: optional. Each extension consists of two parts, key and value. Currently, the extensions listed in the following table are supported (see BCP 47 Extensions). Extensions can be in any sequence and are written in the format of **-key-value**. They are appended to the language, script, and region by using **-u**. For example, **zh-u-nu-latn-ca-chinese** indicates that the Latin numbering system and Chinese calendar system are used. Extensions can also be passed via the second parameter.
- Extensions: optional. Each extension consists of two parts, key and value. Currently, the extensions listed in the following table are supported (see BCP 47 Extensions). Extensions can be in any sequence and are written in the format of **-key-value**. They are appended to the language, script, and region by using **-u**. For example, **zh-u-nu-latn-ca-chinese** indicates that the latn digital system and chinese calendar system are used. Extensions can also be passed via the second parameter.
| Extended Parameter ID| Description|
| Extended Parameter ID| Description|
| -------- | -------- |
| -------- | -------- |
| ca | Calendar algorithm.|
| ca | Calendar algorithm.|
...
@@ -40,305 +44,346 @@ Use [Locale](../reference/apis/js-apis-intl.md#locale) APIs to maximize or minim
...
@@ -40,305 +44,346 @@ Use [Locale](../reference/apis/js-apis-intl.md#locale) APIs to maximize or minim
| hc | Hour cycle.|
| hc | Hour cycle.|
| nu | Numbering system.|
| nu | Numbering system.|
| kn | Whether numeric collation is used when sorting or comparing strings.|
| kn | Whether numeric collation is used when sorting or comparing strings.|
| kf | Whether upper case or lower case is considered when sorting or comparing strings.|
| kf | Whether capitalization is considered when sorting or comparing strings.|
Use [DateTimeFormat](../reference/apis/js-apis-intl.md#datetimeformat) APIs to format the date and time for a specific locale.
[DateTimeFormat](../reference/apis/js-apis-intl.md#datetimeformat) provides APIs to format the date and time for the specified locale.
### Available APIs
### Available APIs
| Module | API | Description |
| Class| API| Description|
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| ohos.intl | constructor()<sup>8+</sup> | Creates a **DateTimeFormat** object. |
| DateTimeFormat | constructor()<sup>8+</sup> | Creates a **DateTimeFormat** object.|
| ohos.intl | constructor(locale: string \| Array<string>, options?: DateTimeOptions) | Creates a **DateTimeFormat** object and sets the locale and other formatting-related attributes. |
| DateTimeFormat | constructor(locale:string\|Array<string>,options?:DateTimeOptions) | Creates a **DateTimeFormat** object and sets the locale and other formatting-related attributes.|
| ohos.intl | format(date: Date): string | Calculates the date and time based on the locale and other formatting-related attributes of the **DateTimeFormat** object. |
| DateTimeFormat | format(date:Date):string | Calculates the date and time based on the locale and other formatting-related attributes of the **DateTimeFormat** object.|
| ohos.intl | formatRange(startDate: Date, endDate: Date): string | Calculates the period based on the locale and other formatting-related attributes of the **DateTimeFormat** object. |
| DateTimeFormat | formatRange(startDate:Date,endDate:Date):string | Calculates the period based on the locale and other formatting-related attributes of the **DateTimeFormat** object.|
| ohos.intl | resolvedOptions(): DateTimeOptions | Obtains the related attributes of the **DateTimeFormat** object. |
| DateTimeFormat | resolvedOptions():DateTimeOptions | Obtains the related attributes of the **DateTimeFormat** object.|
### How to Develop
### How to Develop
1. Instantiate a **DateTimeFormat** object.
1. Import the **intl** module.
Use the default constructor of **DateTimeFormat** to obtain the system default locale by accessing the system language and region settings, and set it as the locale in the **DateTimeFormat** object.
Importing an incorrect bundle can lead to unexpected API behavior.
```js
importIntlfrom'@ohos.intl'
```
2. Instantiate a **DateTimeFormat** object.
Use the default constructor of **DateTimeFormat** to obtain the system default locale by accessing the system language and region settings, and set it as the locale in the **DateTimeFormat** object.
```js
```js
letdateTimeFormat=newintl.DateTimeFormat();
letdateTimeFormat=newIntl.DateTimeFormat();
```
```
Alternatively, use your own locale and formatting parameters to create a **DateTimeFormat** object. Formatting parameters are optional. For a full list of formatting parameters, see [DateTimeOptions](../reference/apis/js-apis-intl.md#datetimeoptions).
Alternatively, use your own locale and formatting parameters to create a **DateTimeFormat** object. Formatting parameters are optional. For a full list of formatting parameters, see [DateTimeOptions](../reference/apis/js-apis-intl.md#datetimeoptions).
Call the **format** method to format the date and time in the **DateTimeFormat** object. This method returns a string representing the formatting result.
Call **format** to format a **Date** object. A string is returned as the formatting result.
letformatResult=dateTimeFormat.format(date);// formatResult = "January 12, 2023, Thursday, 12:12:12 pm, China Standard Time"
```
```
3. Format a period.
4. Format a period.
Call the **formatRange** method to format the period in the **DateTimeFormat** object. This method requires input of two **Date** objects, which respectively indicate the start date and end date of a period. This method returns a string representing the formatting result.
Call **formatRange** to format a period. This API requires the input of two **Date** objects, which respectively indicate the start date and end date of a period. A string is returned as the formatting result.
4. Obtain attributes of the **DateTimeFormat** object.
5. Access the attributes of the **DateTimeFormat** object.
Call the **resolvedOptions** method to obtain attributes of the **DateTimeFormat** object. This method will return an array that contains all attributes and values of the object.
Call **resolvedOptions** to obtain an object that contains all related attributes and values of the **DateTimeFormat** object.
[NumberFormat](../reference/apis/js-apis-intl.md#numberformat) provides APIs to implement the number formatting specific to a locale.
Use [NumberFormat](../reference/apis/js-apis-intl.md#numberformat) APIs to format numbers for a specific locale.
### Available APIs
### Available APIs
| Module | API | Description |
| Class| API| Description|
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| ohos.intl | constructor()<sup>8+</sup> | Creates a **NumberFormat** object. |
| NumberFormat | constructor()<SUP>8+</SUP> | Creates a **NumberFormat** object for the specified locale.|
| ohos.intl | constructor(locale: string \| Array<string>, options?: NumberOptions) | Creates a **NumberFormat** object and sets the locale and other formatting-related attributes. |
| NumberFormat | constructor(locale:string\|Array<string>,options?:NumberOptions) | Creates a **NumberFormat** object and sets the locale and other formatting-related attributes.|
| ohos.intl | format(number: number): string | Calculates the number based on the locale and other formatting-related attributes of the **NumberFormat** object. |
| NumberFormat | format(number:number):string | Calculates the number based on the locale and other formatting-related attributes of the **NumberFormat** object.|
| ohos.intl | resolvedOptions(): NumberOptions | Obtains attributes of the **NumberFormat** object. |
| NumberFormat | resolvedOptions():NumberOptions | Obtains the attributes of the **NumberFormat** object.|
### How to Develop
### How to Develop
1. Instantiate a **NumberFormat** object.
1. Import the **intl** module.
Use the default constructor of **NumberFormat** to obtain the system default locale by accessing the system language and region settings, and set it as the locale in the **NumberFormat** object.
Importing an incorrect bundle can lead to unexpected API behavior.
```js
importIntlfrom'@ohos.intl'
```
2. Instantiate a **NumberFormat** object.
Use the default constructor of **NumberFormat** to obtain the system default locale by accessing the system language and region settings and set it as the locale in the **NumberFormat** object (**intl** is the name of the imported module).
```js
```js
letnumberFormat=newintl.NumberFormat();
letnumberFormat=newIntl.NumberFormat();
```
```
Alternatively, use your own locale and formatting parameters to create a **NumberFormat** object. Formatting parameters are optional. For a full list of formatting parameters, see [NumberOptions](../reference/apis/js-apis-intl.md#numberoptions).
Alternatively, use your own locale and formatting parameters to create a **NumberFormat** object. Formatting parameters are optional. For a full list of formatting parameters, see [NumberOptions](../reference/apis/js-apis-intl.md#numberoptions).
3. Obtain attributes of the **NumberFormat** object.
4. Access the attributes of the **NumberFormat** object.
Call the **resolvedOptions** method to obtain attributes of the **NumberFormat** object. This method will return an array that contains all attributes and values of the object.
Call **resolvedOptions** to obtain an object that contains all related attributes and values of the **NumberFormat** object.
Users in different regions have different requirements for string sorting. [Collator](../reference/apis/js-apis-intl.md#collator8) provides APIs to sort character strings specific to a locale.
Use [Collator](../reference/apis/js-apis-intl.md#collator8) APIs to sort strings based on a specific locale. Users in different regions have different preferences for string sorting.
### Available APIs
### Available APIs
| Module | API | Description |
| Class| API| Description|
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| ohos.intl | constructor()<sup>8+</sup> | Creates a **Collator** object. |
| Collator | constructor()<sup>8+</sup> | Creates a **Collator** object.|
| ohos.intl | constructor(locale: string \| Array<string>, options?: CollatorOptions)<sup>8+</sup> | Creates a **Collator** object and sets the locale and other related attributes. |
| Collator | constructor(locale:string\|Array<string>,options?:CollatorOptions)<sup>8+</sup> | Creates a **Collator** object and sets the locale and other related attributes.|
| ohos.intl | compare(first: string, second: string): number<sup>8+</sup> | Calculates the comparison result of two strings based on the locale and other attributes of the **Collator** object. |
| Collator | compare(first:string,second:string):number<sup>8+</sup> | Calculates the comparison result of two strings based on the locale and other attributes of the **Collator** object.|
| ohos.intl | resolvedOptions(): CollatorOptions<sup>8+</sup> | Obtains attributes of the **Collator** object. |
| Collator | resolvedOptions():CollatorOptions<sup>8+</sup> | Obtains the attributes of the **Collator** object.|
### How to Develop
### How to Develop
1. Instantiate a **Collator** object.
1. Import the **intl** module.
Use the default constructor of **Collator** to obtain the system default locale by accessing the system language and region settings, and set it as the locale in the **Collator** object.
Importing an incorrect bundle can lead to unexpected API behavior.
```js
importIntlfrom'@ohos.intl'
```
2. Instantiate a **Collator** object.
Use the default constructor of **Collator** to obtain the system default locale by accessing the system language and region settings and set it as the locale in the **Collator** object (**intl** is the name of the imported module).
```js
```js
letcollator=newintl.Collator();
letcollator=newIntl.Collator();
```
```
Alternatively, use your own locale and formatting parameters to create a **Collator** object. For a full list of parameters, see [CollatorOptions](../reference/apis/js-apis-intl.md#collatoroptions9).
Alternatively, use your own locale and formatting parameters to create a **Collator** object. For a full list of parameters, see [CollatorOptions](../reference/apis/js-apis-intl.md#collatoroptions9).
The **sensitivity** parameter is used to specify the levels of differences that will be used for string comparison. The value **base** indicates that only characters are compared, but not the accent and capitalization. For example, 'a' != 'b', 'a' == '', 'a'=='A'. The value **accent** indicates that the accent is considered, but not the capitalization. For example, 'a' != 'b', 'a' == '', 'a'=='A'. The value **case** indicates that the capitalization is considered, but the accent. For example, 'a' != 'b', 'a' == '', 'a'=='A'. The value **variant** indicates that the accent and capitalization are considered. For example, 'a' != 'b', 'a' == '', 'a'=='A'.
Call the **compare** method to compare two input strings. This method returns a value as the comparison result. The return value **-1** indicates that the first string is shorter than the second string, the return value **1** indicates that the first string is longer than the second string, and the return value **0** indicates that the two strings are of equal lengths. This allows you to sort character strings based on the comparison result.
Call **compare** to compare two input strings. This API returns a value as the comparison result. The return value **-1** indicates that the first string is shorter than the second string, the return value **1** indicates that the first string is longer than the second string, and the return value **0** indicates that the two strings are of equal lengths. This allows you to sort character strings based on the comparison result.
4. Access the attributes of the **Collator** object.
Call the **resolvedOptions** method to obtain attributes of the **Collator** object. This method will return an array that contains all attributes and values of the object.
Call **resolvedOptions** to obtain an object that contains all related attributes and values of the **Collator** object.
Use [PluralRules](../reference/apis/js-apis-intl.md#pluralrules8) APIs to determine the singular-plural type for a specific locale. According to the grammar of certain languages, the singular or plural form of a noun depends on its preceding number.
According to grammars in certain languages, the singular or plural form of a noun depends on the number prior to the noun. [PluralRules](../reference/apis/js-apis-intl.md#pluralrules8) provides APIs to determine the singular-plural type for a specific locale.
### Available APIs
### Available APIs
| Module | API | Description |
| Class| API| Description|
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| ohos.intl | constructor()<sup>8+</sup> | Creates a **PluralRules** object. |
| PluralRules | constructor()<sup>8+</sup> | Creates a **PluralRules** object.|
| ohos.intl | constructor(locale: string \| Array<string>, options?: PluralRulesOptions)<sup>8+</sup> | Creates a **PluralRules** object and sets the locale and other related attributes. |
| PluralRules | constructor(locale:string\|Array<string>,options?:PluralRulesOptions)<sup>8+</sup> | Creates a **PluralRules** object and sets the locale and other related attributes.|
| ohos.intl | select(n: number): string<sup>8+</sup> | Determines the singular-plural type based on the locale and other formatting-related attributes of the **PluralRules** object. |
| PluralRules | select(n:number):string<sup>8+</sup> | Determines the singular-plural type based on the locale and other formatting-related attributes of the **PluralRules** object.|
### How to Develop
### How to Develop
1. Instantiate a **PluralRules** object.
1. Import the **intl** module.
Use the default constructor of **PluralRules** to obtain the system default locale by accessing the system language and region settings, and set it as the locale in the **PluralRules** object.
Importing an incorrect bundle can lead to unexpected API behavior.
```js
importIntlfrom'@ohos.intl'
```
2. Instantiate a **PluralRules** object.
Use the default constructor of **PluralRules** to obtain the system default locale by accessing the system language and region settings and set it as the locale in the **PluralRules** object (**intl** is the name of the imported module).
```js
```js
letpluralRules=newintl.PluralRules();
letpluralRules=newIntl.PluralRules();
```
```
Alternatively, use your own locale and formatting parameters to create a **PluralRules** object. For a full list of parameters, see [PluralRulesOptions](../reference/apis/js-apis-intl.md#pluralrulesoptions9).
Alternatively, use your own locale and formatting parameters to create a **PluralRules** object. For a full list of parameters, see [PluralRulesOptions](../reference/apis/js-apis-intl.md#pluralrulesoptions9).
Call the **select** method to determine the singular-plural type of an input number. This method will return a string representing the singular-plural type, which can be any of the following: **zero**, **one**, **two**, **few**, **many**, and **other**.
Call **select** to determine the singular-plural type for an input number. This API returns a string as the category of the input number, which can be any of the following: **zero**, **one**, **two**, **few**, **many**, and **other**.
[RelativeTimeFormat](../reference/apis/js-apis-intl.md#relativetimeformat8) provides APIs to format the relative time for a specific locale.
Use [RelativeTimeFormat](../reference/apis/js-apis-intl.md#relativetimeformat8) APIs to format the relative time for a specific locale.
### Available APIs
### Available APIs
| Module | API | Description |
| Class| API| Description|
| -------- | -------- | -------- |
| -------- | -------- | -------- |
| ohos.intl | constructor()<sup>8+</sup> | Creates a **RelativeTimeFormat** object. |
| RelativeTimeFormat | constructor()<sup>8+</sup> | Creates a **RelativeTimeFormat** object.|
| ohos.intl | constructor(locale: string \| Array<string>, options?: RelativeTimeFormatInputOptions)<sup>8+</sup> | Creates a **RelativeTimeFormat** object and sets the locale and other formatting-related attributes. |
| RelativeTimeFormat | constructor(locale:string\|Array<string>,options?:RelativeTimeFormatInputOptions)<sup>8+</sup> | Creates a **RelativeTimeFormat** object and sets the locale and other formatting-related attributes.|
| ohos.intl | format(value: number, unit: string): string<sup>8+</sup> | Calculates the relative time format based on the locale and other formatting-related attributes of the **RelativeTimeFormat** object. |
| RelativeTimeFormat | format(value:number,unit:string):string<sup>8+</sup> | Calculates the relative time format based on the locale and other formatting-related attributes of the **RelativeTimeFormat** object.|
| ohos.intl | formatToParts(value: number, unit: string): Array<object><sup>8+</sup> | Returns each part of the relative time format based on the locale and other formatting-related attributes of the **RelativeTimeFormat** object. |
| RelativeTimeFormat | formatToParts(value:number,unit:string):Array<object><sup>8+</sup> | Obtains each part of the relative time format based on the locale and other formatting-related attributes of the **RelativeTimeFormat** object.|
| ohos.intl | resolvedOptions(): RelativeTimeFormatResolvedOptions<sup>8+</sup> | Obtains attributes of the **RelativeTimeFormat** object. |
| RelativeTimeFormat | resolvedOptions():RelativeTimeFormatResolvedOptions<sup>8+</sup> | Obtains the attributes of the **RelativeTimeFormat** object.|
### How to Develop
### How to Develop
1. Instantiate a **RelativeTimeFormat** object.
1. Import the **intl** module.
Importing an incorrect bundle can lead to unexpected API behavior.
```js
importIntlfrom'@ohos.intl'
```
Use the default constructor of **RelativeTimeFormat** to obtain the system default locale by accessing the system language and region settings, and set it as the locale in the**RelativeTimeFormat** object.
2. Instantiate a**RelativeTimeFormat** object.
Use the default constructor of **RelativeTimeFormat** to obtain the system default locale by accessing the system language and region settings and set it as the locale in the **RelativeTimeFormat** object (**intl** is the name of the imported module).
Alternatively, use your own locale and formatting parameters to create a **RelativeTimeFormat** object. Formatting parameters are optional. For a full list of formatting parameters, see [RelativeTimeFormatInputOptions](../reference/apis/js-apis-intl.md#relativetimeformatinputoptions9).
Alternatively, use your own locale and formatting parameters to create a **RelativeTimeFormat** object. Formatting parameters are optional. For a full list of formatting parameters, see [RelativeTimeFormatInputOptions](../reference/apis/js-apis-intl.md#relativetimeformatinputoptions9).
Call the **format** method to format the relative time. This method receives a numeric value representing the time length and a string-form unit, like **year**, **quarter**, **month**, **week**, **day**, **hour**, **minute**, and **second**. This method returns a string representing the formatting result.
Call **format** to format the relative time. This API receives a numeric value representing the time length and a string-form unit, like **year**, **quarter**, **month**, **week**, **day**, **hour**, **minute**, and **second**. A string is returned as the formatting result.
4. Obtain attributes of the **RelativeTimeFormat** object.
5. Access the attributes of the **RelativeTimeFormat** object.
Call the **resolvedOptions** method to obtain attributes of the **RelativeTimeFormat** object. This method will return an array that contains all attributes and values of the object. For a full list of attributes, see [RelativeTimeFormatResolvedOptions](../reference/apis/js-apis-intl.md#relativetimeformatresolvedoptions8).
Call **resolvedOptions** to obtain an object that contains all related attributes and values of the **RelativeTimeFormat** object. For a full list of attributes, see [RelativeTimeFormatResolvedOptions](../reference/apis/js-apis-intl.md#relativetimeformatresolvedoptions8).
The **i18n** 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 **i18n** 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](js-apis-intl.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.
The [intl](js-apis-intl.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.
The **intl** 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 **intl** 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 interfaces that are not defined in ECMA 402. It works with the intl module to provide a complete suite of i18n capabilities.
The [i18n](js-apis-i18n.md) module provides enhanced i18n capabilities through supplementary interfaces that are not defined in ECMA 402. It works with the intl module to provide a complete suite of i18n capabilities.
> **NOTE**
> **NOTE**
> - 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.
> - 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.
