diff --git a/en/application-dev/internationalization/Readme-EN.md b/en/application-dev/internationalization/Readme-EN.md new file mode 100644 index 0000000000000000000000000000000000000000..4a1435843d6842dfaacbd1a56419efc6ef5b7487 --- /dev/null +++ b/en/application-dev/internationalization/Readme-EN.md @@ -0,0 +1,5 @@ +# Internationalization + +- [Overview](international-overview.md) +- [Internationalization Development (intl)](intl-guidelines.md) +- [Internationalization Development (i18n)](i18n-guidelines.md) diff --git a/en/application-dev/internationalization/i18n-guidelines.md b/en/application-dev/internationalization/i18n-guidelines.md new file mode 100644 index 0000000000000000000000000000000000000000..0ded9fd39da8131472cdb600ffd6d3ebc7daff5f --- /dev/null +++ b/en/application-dev/internationalization/i18n-guidelines.md @@ -0,0 +1,363 @@ +# Internationalization Development (i18n) + + +## 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. Obtains 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); + ``` diff --git a/en/application-dev/internationalization/international-overview.md b/en/application-dev/internationalization/international-overview.md new file mode 100644 index 0000000000000000000000000000000000000000..f41f6b0cb00c105e9a69e9e94388713c638ad658 --- /dev/null +++ b/en/application-dev/internationalization/international-overview.md @@ -0,0 +1,24 @@ +# Overview + + +If an application is targeted for users and markets in different regions with different languages and time zones, it is necessary for you to provide localized versions to ensure good experience for your users. + + +Internationalization capabilities determine how hard or easy application localization will be. With the rich internationalization APIs provided by the system, localization is much more efficient and cost-effective, accelerating your design and implementation of a well-internationalized application. + + +## Basic Concepts + +- Locale: an abstract representation of the commonalities of a group in terms of language, script, country or region, and other regional features such as calendar, sorting, and currency. + +- Preferred language: the language that the user prefers to use in a service or system. You can add a preferred language by choosing **Settings** > **System & updates** > **Language & input** > **Language and region** > **ADD LANGUAGE** on your mobile phone. + + +## Working Principles + +You just need to specify a locale when calling internationalization APIs, and localization will be automatically implemented for that locale. Locale information can be hard coded, but it is more common for users to set the system language and region by themselves. + + +## Constraints + +None diff --git a/en/application-dev/internationalization/intl-guidelines.md b/en/application-dev/internationalization/intl-guidelines.md new file mode 100644 index 0000000000000000000000000000000000000000..9bbfa269163f903889cca28307472c808752a130 --- /dev/null +++ b/en/application-dev/internationalization/intl-guidelines.md @@ -0,0 +1,302 @@ +# Internationalization Development (intl) + + +## Setting Locale Information + +[Locale](../reference/apis/js-apis-intl.md) APIs are used to maximize or minimize locale information. + + +### Available APIs + + | Module | API | Description | +| -------- | -------- | -------- | +| ohos.intl | constructor()8+ | Instantiates a **Locale** object. | +| ohos.intl | constructor(locale?: string, options?: options) | Instantiates a **Locale** object based on the locale parameter and options. | +| ohos.intl | toString(): string | Converts locale information into a string. | +| ohos.intl | maximize(): Locale | Maximizes locale information. | +| ohos.intl | minimize(): Locale | Minimizes locale information. | + + +### How to Develop + +1. Instantiate a **Locale** object. + Create a **Locale** object using the **Locale** constructor. This method receives a string representing the locale and an optional [Attributes](../reference/apis/js-apis-intl.md) list (**intl** is the name of the imported module). + + + ``` + var locale = "zh-CN"; + var options = {caseFirst: false, calendar: "chinese", collation: pinyin}; + var localeObj = new intl.Locale(locale, options); + ``` + +2. Obtain the string representing a **Locale** object. + Call the **toString** method to obtain the string representing a **Locale** object, including the language, region, and other options. + + ``` + var localeStr = localeObj.toString(); + ``` + +3. Maximize locale information. + Call the **maximize** method to maximize locale information; that is, supplement the missing script and region information. + + ``` + var maximizedLocale = localeObj.maximize(); + ``` + +4. Minimize locale information. + Call the **minimize** method to minimize locale information; that is, delete the unnecessary script and region information. + + ``` + var minimizedLocale = localeObj.minimize(); + ``` + + +## Formatting the Date and Time + +[DateTimeFormat](../reference/apis/js-apis-intl.md) APIs are used to format the date and time for a specific locale. + + +### Available APIs + + | Module | API | Description | +| -------- | -------- | -------- | +| ohos.intl | constructor()8+ | 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. | +| ohos.intl | 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. | +| ohos.intl | resolvedOptions(): DateTimeOptions | Obtains the related attributes of the **DateTimeFormat** object. | + + +### How to Develop + +1. 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 (**intl** is the name of the imported module). + + + ``` + var dateTimeFormat = new intl.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). + + ``` + var options = {dateStyle: "full", timeStyle: "full"}; + var dateTimeFormat = new intl.DateTimeFormat("zh-CN", options); + ``` + +2. Format the date and time. + Use the **format** method of **DateTimeFormat** to format a **Date** object. A string is returned as the formatting result. + + ``` + Date date = new Date(); + var formatResult = dateTimeFormat.format(date); + ``` + +3. Format a period. + Use the **formatRange** method of **DateTimeFormat** to format a period. This method 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. + + ``` + Date startDate = new Date(); + Date endDate = new Date(); + var formatResult = dateTimeFormat.formatRange(startDate, endDate); + ``` + +4. Access the attributes of the **DateTimeFormat** object. + The **resolvedOptions** method of **DateTimeFormat** returns an object that contains all related attributes and values of the **DateTimeFormat** object. + + ``` + var options = dateTimeFormat.resolvedOptions(); + ``` + + +## Number Formatting + +[NumberFormat](../reference/apis/js-apis-intl.md) APIs are used to format a number for a specific locale. + + +### Available APIs + + | Module | API | Description | +| -------- | -------- | -------- | +| ohos.intl | constructor()8+ | Creates a **NumberFormat** object. | +| ohos.intl | 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. | +| ohos.intl | resolvedOptions(): NumberOptions | Obtains the attributes of the **NumberFormat** object. | + + +### How to Develop + +1. 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). + + + ``` + var numberFormat = new intl.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). + + ``` + var options = {compactDisplay: "short", notation: "compact"}; + var numberFormat = new intl.NumberFormat("zh-CN", options); + ``` + +2. Format a number. + Use the **format** method of **NumberFormat** to format a number. A string is returned as the formatting result. + + ``` + var number = 1234.5678 + var formatResult = numberFormat.format(number); + ``` + +3. Access the attributes of the **NumberFormat** object. + The **resolvedOptions** method of NumberFormat returns an object that contains all related attributes and values of the **NumberFormat** object. + + ``` + var options = numberFormat.resolvedOptions(); + ``` + + +## String Sorting + +Users in different regions have different requirements for string sorting. [Collator](../reference/apis/js-apis-intl.md) APIs are used to sort strings based on a specific locale. + + +### Available APIs + + | Module | API | Description | +| -------- | -------- | -------- | +| ohos.intl | constructor()8+ | Creates a **Collator** object. | +| ohos.intl | constructor(locale: string \| Array<string>, options?: CollatorOptions)8+ | Creates a **Collator** object and sets the locale and other related attributes. | +| ohos.intl | compare(first: string, second: string): number8+ | Calculates the comparison result of two strings based on the locale and other attributes of the **Collator** object. | +| ohos.intl | resolvedOptions(): CollatorOptions8+ | Obtains the attributes of the **Collator** object. | + + +### How to Develop + +1. 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). + + + ``` + var collator = new intl.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). + + ``` + var collator= new intl.Collator("zh-CN", {localeMatcher: "best fit", usage: "sort"}; + ``` + +2. Compare two strings. + Use the **compare** method of **Collator** 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. + + ``` + var str1 = "first string"; + var str2 = "second string"; + var compareResult = collator.compare(str1, str2); + ``` + +3. Access the attributes of the **Collator** object. + The **resolvedOptions** method of **Collator** returns an object that contains all related attributes and values of the **Collator** object. + + ``` + var options = collator.resolvedOptions(); + ``` + + +## Determining the Singular-Plural Type + +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) APIs are used to determine the singular-plural type for a specific locale. + + +### Available APIs + + | Module | API | Description | +| -------- | -------- | -------- | +| ohos.intl | constructor()8+ | Creates a **PluralRules** object. | +| ohos.intl | constructor(locale: string \| Array<string>, options?: PluralRulesOptions)8+ | Creates a **PluralRules** object and sets the locale and other related attributes. | +| ohos.intl | select(n: number): string8+ | Determines the singular-plural type based on the locale and other formatting-related attributes of the **PluralRules** object. | + + +### How to Develop + +1. 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). + + + ``` + var pluralRules = new intl.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). + + ``` + var plurals = new intl.PluralRules("zh-CN", {localeMatcher: "best fit", type: "cardinal"}; + ``` + +2. Determine the singular or plural category. + Use the **select** method of **PluralRules** to determine the singular-plural type for an input number. This method returns a string as the category of the input number, which can be any of the following: **zero**, **one**, **two**, **few**, **many**, and **other**. + + ``` + var number = 1234.5678 + var categoryResult = plurals.select(number); + ``` + + +## Formatting Relative Time + +[RelativeTimeFormat](../reference/apis/js-apis-intl.md) APIs are used to format the relative time for a specific locale. + + +### Available APIs + + | Module | API | Description | +| -------- | -------- | -------- | +| ohos.intl | constructor()8+ | Creates a **RelativeTimeFormat** object. | +| ohos.intl | constructor(locale: string \| Array<string>, options?: RelativeTimeFormatInputOptions)8+ | Creates a **RelativeTimeFormat** object and sets the locale and other formatting-related attributes. | +| ohos.intl | format(value: number, unit: string): string8+ | 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>8+ | Returns each part of the relative time format based on the locale and other formatting-related attributes of the **RelativeTimeFormat** object. | +| ohos.intl | resolvedOptions(): RelativeTimeFormatResolvedOptions8+ | Obtains the attributes of the **RelativeTimeFormat** object. | + + +### How to Develop + +1. 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). + + + ``` + var relativeTimeFormat = new intl.RelativeTimeFormat(); + ``` + + 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). + + ``` + var relativeTimeFormat = new intl.RelativeTimeFormat("zh-CN", {numeric: "always", style: "long"}; + ``` + +2. Format the relative time. + Use the **format** method of **RelativeTimeFormat** 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**. A string is returned as the formatting result. + + ``` + var number = 2; + var unit = "year" + var formatResult = relativeTimeFormat.format(number, unit); + ``` + +3. Obtain each part of the relative time format. + On obtaining each part of the relative time format, customize the relative time formatting result. + + ``` + var number = 2; + var unit = "year" + var formatResult = relativeTimeFormat.formatToParts(number, unit); + ``` + +4. Access the attributes of the **RelativeTimeFormat** object. + The **resolvedOptions** method of **RelativeTimeFormat** returns 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). + + ``` + var options = numberFormat.resolvedOptions(); + ``` diff --git a/en/application-dev/internationalization/public_sys-resources/icon-caution.gif b/en/application-dev/internationalization/public_sys-resources/icon-caution.gif new file mode 100644 index 0000000000000000000000000000000000000000..6e90d7cfc2193e39e10bb58c38d01a23f045d571 Binary files /dev/null and b/en/application-dev/internationalization/public_sys-resources/icon-caution.gif differ diff --git a/en/application-dev/internationalization/public_sys-resources/icon-danger.gif b/en/application-dev/internationalization/public_sys-resources/icon-danger.gif new file mode 100644 index 0000000000000000000000000000000000000000..6e90d7cfc2193e39e10bb58c38d01a23f045d571 Binary files /dev/null and b/en/application-dev/internationalization/public_sys-resources/icon-danger.gif differ diff --git a/en/application-dev/internationalization/public_sys-resources/icon-note.gif b/en/application-dev/internationalization/public_sys-resources/icon-note.gif new file mode 100644 index 0000000000000000000000000000000000000000..6314297e45c1de184204098efd4814d6dc8b1cda Binary files /dev/null and b/en/application-dev/internationalization/public_sys-resources/icon-note.gif differ diff --git a/en/application-dev/internationalization/public_sys-resources/icon-notice.gif b/en/application-dev/internationalization/public_sys-resources/icon-notice.gif new file mode 100644 index 0000000000000000000000000000000000000000..86024f61b691400bea99e5b1f506d9d9aef36e27 Binary files /dev/null and b/en/application-dev/internationalization/public_sys-resources/icon-notice.gif differ diff --git a/en/application-dev/internationalization/public_sys-resources/icon-tip.gif b/en/application-dev/internationalization/public_sys-resources/icon-tip.gif new file mode 100644 index 0000000000000000000000000000000000000000..93aa72053b510e456b149f36a0972703ea9999b7 Binary files /dev/null and b/en/application-dev/internationalization/public_sys-resources/icon-tip.gif differ diff --git a/en/application-dev/internationalization/public_sys-resources/icon-warning.gif b/en/application-dev/internationalization/public_sys-resources/icon-warning.gif new file mode 100644 index 0000000000000000000000000000000000000000..6e90d7cfc2193e39e10bb58c38d01a23f045d571 Binary files /dev/null and b/en/application-dev/internationalization/public_sys-resources/icon-warning.gif differ diff --git a/zh-cn/application-dev/ui/figures/zh-cn_image_0000001263259399.png b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001263259399.png index c9e2e084909884daa701f5e967050c849c036e5a..dc4a266c02708116362da21577d5b1e582a011fd 100644 Binary files a/zh-cn/application-dev/ui/figures/zh-cn_image_0000001263259399.png and b/zh-cn/application-dev/ui/figures/zh-cn_image_0000001263259399.png differ