1# @ohos.intl (Internationalization) 2 3The **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. 4The [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. 5 6> **NOTE** 7> 8> - 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. 9> 10> - The APIs of this module conform to the [Common Locale Data Repository (CLDR)](https://cldr.unicode.org) internationalization database. The processing result may change with CLDR evolution. API version 12 corresponds to [CLDR 42](https://cldr.unicode.org/index/downloads/cldr-42). For details about data changes, visit the official website. 11> 12> - Since API version 11, some APIs of this module are supported in ArkTS widgets. 13> 14> - Since API version 12, the APIs of this module are supported in atomic services. 15 16 17## Modules to Import 18 19```ts 20import { intl } from '@kit.LocalizationKit'; 21``` 22 23## Locale 24 25### Attributes 26 27**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 28 29**Atomic service API**: This API can be used in atomic services since API version 12. 30 31**System capability**: SystemCapability.Global.I18n 32 33| Name | Type | Mandatory | Description | 34| --------------- | ------- | -------- | ---------------------------------------- | 35| language | string | Yes | Language associated with the locale, for example, **zh**. | 36| script | string | Yes | Script type of the language, for example, **Hans**. | 37| region | string | Yes | Country or region associated with the locale, for example, **CN**. | 38| baseName | string | Yes | Basic information about the locale, which consists of the language, script, and region, for example, **zh-Hans-CN**. | 39| caseFirst | string | Yes | Whether case is taken into account for the locale's collation rules.<br>The value can be **upper**, **lower**, or **false**.| 40| calendar | string | Yes | Calendar for the locale.<br>The value can be any of the following: **buddhist**, **chinese**, **coptic**, **dangi**, **ethioaa**, **ethiopic**, **gregory**, **hebrew**, **indian**, **islamic**, **islamic-umalqura**, **islamic-tbla**, **islamic-civil**, **islamic-rgsa**, **iso8601**, **japanese**, **persian**, **roc**, or **islamicc**.| 41| collation | string | Yes | Collation rules for the locale.<br>The value can be any of the following: The value can be any of the following: **big5han**, **compat**, **dict**, **direct**, **ducet**, **eor**, **gb2312**, **phonebk**, **phonetic**, **pinyin**, **reformed**, **searchjl**, **stroke**, **trad**, **unihan**, **zhuyin**.| 42| hourCycle | string | Yes | Time system for the locale.<br>The value can be **h12**, **h23**, **h11**, **h24**.| 43| numberingSystem | string | Yes | Numbering system for the locale.<br>The value can be any of the following: **adlm**, **ahom**, **arab**, **arabext**, **bali**, **beng**, **bhks**, **brah**, **cakm**, **cham**, **deva**, **diak**, **fullwide**, **gong**, **gonm**, **gujr**, **guru**, **hanidec**, **hmng**, **hmnp**, **java**, **kali**, **khmr**, **knda**, **lana**, **lanatham**, **laoo**, **latn**, **lepc**, **limb**, **mathbold**, **mathdbl**, **mathmono**, **mathsanb**, **mathsans**, **mlym**, **modi**, **mong**, **mroo**, **mtei**, **mymr**, **mymrshan**, **mymrtlng**, **newa**, **nkoo**, **olck**, **orya**, **osma**, **rohg**, **saur**, **segment**, **shrd**, **sind**, **sinh**, **sora**, **sund**, **takr**, **talu**, **tamldec**, **telu**, **thai**, **tibt**, **tirh**, **vaii**, **wara**, **wcho**.| 44| numeric | boolean | Yes | Whether to apply special collation rules for numeric characters.<br>The default value is **false**. | 45 46> **NOTE** 47> 48> - For details about **caseFirst** and **collation**, see Table 1 in [Sorting by Local Habits ](../../internationalization/i18n-sorting-local.md). 49> 50> - For details about **calendar**, see Table 1 in [Calendar Setting](../../internationalization/i18n-calendar.md). 51> 52> - For details about **hourCycle**, see Table 5 in [Date and Time Formatting](../../internationalization/i18n-time-date.md). 53 54### constructor<sup>8+</sup> 55 56constructor() 57 58Creates a **Locale** object. 59 60**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 61 62**Atomic service API**: This API can be used in atomic services since API version 12. 63 64**System capability**: SystemCapability.Global.I18n 65 66**Example** 67 ```ts 68 // When creating a **Locale** object, the default constructor uses the current locale of the system. 69 let locale = new intl.Locale(); 70 // Return the current system locale. 71 let localeID = locale.toString(); 72 ``` 73 74### constructor 75 76constructor(locale: string, options?: LocaleOptions) 77 78Creates a **Locale** object. 79 80**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 81 82**Atomic service API**: This API can be used in atomic services since API version 12. 83 84**System capability**: SystemCapability.Global.I18n 85 86**Parameters** 87 88| Name | Type | Mandatory | Description | 89| -------------------- | -------------------------------- | ---- | ---------------------------- | 90| locale | string | Yes | A string containing locale information, including the language, optional script, and region.<br>The locale can any or all of the preceding information.| 91| options | [LocaleOptions](#localeoptions) | No | Options for creating the **Locale** object.| 92 93**Example** 94 ```ts 95 // Create a Locale object named zh-CN. 96 let locale = new intl.Locale("zh-CN"); 97 let localeID = locale.toString(); // localeID = "zh-CN" 98 ``` 99 100 101### toString 102 103toString(): string 104 105Obtains the string that represents a **Locale** object. 106 107**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 108 109**Atomic service API**: This API can be used in atomic services since API version 12. 110 111**System capability**: SystemCapability.Global.I18n 112 113**Return value** 114 115| Type | Description | 116| ------ | ----------- | 117| string | String that represents the **Locale** object.| 118 119**Example** 120 ```ts 121 // Create a Locale object named en-GB. 122 let locale = new intl.Locale("en-GB"); 123 let localeID = locale.toString(); // localeID = "en-GB" 124 ``` 125 126### maximize 127 128maximize(): Locale 129 130Maximizes information of a **Locale** object. If the script and country/region information is missing, add the information. 131 132**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 133 134**Atomic service API**: This API can be used in atomic services since API version 12. 135 136**System capability**: SystemCapability.Global.I18n 137 138**Return value** 139 140| Type | Description | 141| ----------------- | ---------- | 142| [Locale](#locale) | **Locale** object with the script and country/region information.| 143 144**Example** 145 ```ts 146 // Create a Locale object named zh. 147 let locale = new intl.Locale("zh"); 148 // Complete the script and region of the Locale object. 149 let maximizedLocale = locale.maximize(); 150 let localeID = maximizedLocale.toString(); // localeID = "zh-Hans-CN" 151 152 // Create a Locale object named en-US. 153 locale = new intl.Locale("en-US"); 154 // Complete the script of the Locale object. 155 maximizedLocale = locale.maximize(); 156 localeID = maximizedLocale.toString(); // localeID = "en-Latn-US" 157 ``` 158 159 160### minimize 161 162minimize(): Locale 163 164Minimizes information of the **Locale** object. If the script and country/region information is present, delete the information. 165 166**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 167 168**Atomic service API**: This API can be used in atomic services since API version 12. 169 170**System capability**: SystemCapability.Global.I18n 171 172**Return value** 173 174| Type | Description | 175| ----------------- | ---------- | 176| [Locale](#locale) | **Locale** object without the script or country/region information.| 177 178**Example** 179 ```ts 180 // Create a Locale object named zh-Hans-CN. 181 let locale = new intl.Locale("zh-Hans-CN"); 182 // Remove the script and region of the Locale object. 183 let minimizedLocale = locale.minimize(); 184 let localeID = minimizedLocale.toString(); // localeID = "zh" 185 186 // Create a Locale object named en-US. 187 locale = new intl.Locale("en-US"); 188 // Remove the region of the Locale object. 189 minimizedLocale = locale.minimize(); 190 localeID = minimizedLocale.toString(); // localeID = "en" 191 ``` 192 193## LocaleOptions 194 195Options for initializing the **Locale** object. Since API version 9, the **LocaleOptions** attribute is changed from mandatory to optional. 196 197**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 198 199**Atomic service API**: This API can be used in atomic services since API version 12. 200 201**System capability**: SystemCapability.Global.I18n 202 203| Name | Type | Mandatory | Description | 204| --------------- | ------- | ---- |---------------------------------------- | 205| calendar | string | No |Calendar parameter.<br>The value can be any of the following: **buddhist**, **chinese**, **coptic**, **dangi**, **ethioaa**, **ethiopic**, **gregory**, **hebrew**, **indian**, **islamic**, **islamic-umalqura**, **islamic-tbla**, **islamic-civil**, **islamic-rgsa**, **iso8601**, **japanese**, **persian**, **roc**, or **islamicc**.| 206| collation | string | No |Collation parameter.<br>The value can be any of the followings: **big5han**, **compat**, **dict**, **direct**, **ducet**, **emoji**, **eor**, **gb2312**, **phonebk**, **phonetic**, **pinyin**, or **reformed**". **search**, **searchjl**, **standard**, **stroke**, **trad**, **unihan**, **zhuyin**.| 207| hourCycle | string | No |Hour cycle.<br>The value can be **h11**, **h12**, **h23**, or **h24**.| 208| numberingSystem | string | No |Numbering system.<br>The value can be any of the following: **adlm**, **ahom**, **arab**, **arabext**, **bali**, **beng**, **bhks**, **brah**, **cakm**, **cham**, **deva**, **diak**, **fullwide**, **gong**, **gonm**, **gujr**, **guru**, **hanidec**, **hmng**, **hmnp**, **java**, **kali**, **khmr**, **knda**, **lana**, **lanatham**, **laoo**, **latn**, **lepc**, **limb**, **mathbold**, **mathdbl**, **mathmono**, **mathsanb**, **mathsans**, **mlym**, **modi**, **mong**, **mroo**, **mtei**, **mymr**, **mymrshan**, **mymrtlng**, **newa**, **nkoo**, **olck**, **orya**, **osma**, **rohg**, **saur**, **segment**, **shrd**, **sind**, **sinh**, **sora**, **sund**, **takr**, **talu**, **tamldec**, **telu**, **thai**, **tibt**, **tirh**, **vaii**, **wara**, **wcho**.| 209| numeric | boolean | No | Whether to apply special collation rules for numeric characters. The default value is **false**. | 210| caseFirst | string | No | Whether upper case or lower case is sorted first.<br>The value can be **upper**, **lower**, or **false**.| 211 212> **NOTE** 213> 214> - For details about **calendar**, see Table 1 in [Calendar Setting](../../internationalization/i18n-calendar.md). 215> 216> - For details about **hourCycle**, see Table 5 in [Date and Time Formatting](../../internationalization/i18n-time-date.md). 217> 218> - For details about **caseFirst** and **collation**, see Table 1 in [Sorting by Local Habits ](../../internationalization/i18n-sorting-local.md). 219 220## DateTimeFormat 221 222### constructor<sup>8+</sup> 223 224constructor() 225 226Creates a **DateTimeOptions** object for the specified locale. 227 228**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 229 230**Atomic service API**: This API can be used in atomic services since API version 12. 231 232**System capability**: SystemCapability.Global.I18n 233 234**Example** 235 ```ts 236 // Use the current system locale to create a DateTimeFormat object. 237 let datefmt= new intl.DateTimeFormat(); 238 ``` 239 240### constructor 241 242constructor(locale: string | Array<string>, options?: DateTimeOptions) 243 244Creates a **DateTimeOptions** object for the specified locale. 245 246**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 247 248**Atomic service API**: This API can be used in atomic services since API version 12. 249 250**System capability**: SystemCapability.Global.I18n 251 252**Parameters** 253 254| Name | Type | Mandatory | Description | 255| -------------------- | ------------------------------------ | ---- | ---------------------------- | 256| locale | string \| Array<string> | Yes | A string containing locale information, including the language, optional script, and region.<br>The locale can any or all of the preceding information.| 257| options | [DateTimeOptions](#datetimeoptions) | No | Options for creating the **DateTimeOptions** object.<br>If no options are set, the default values of **year**, **month**, and **day** are **numeric**.| 258 259**Example** 260 ```ts 261 // Use locale zh-CN to create a DateTimeFormat object. Set dateStyle to full and timeStyle to medium. 262 let datefmt= new intl.DateTimeFormat("zh-CN", { dateStyle: 'full', timeStyle: 'medium' }); 263 264 // Use the locale list ["ban**, **zh"] to create a DateTimeFormat object. Because ban is an invalid locale ID, locale zh is used to create the DateTimeFormat object. 265 let datefmt= new intl.DateTimeFormat(["ban", "zh"], { dateStyle: 'full', timeStyle: 'medium' }); 266 ``` 267 268### format 269 270format(date: Date): string 271 272Formats the date and time. 273 274**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 275 276**Atomic service API**: This API can be used in atomic services since API version 12. 277 278**System capability**: SystemCapability.Global.I18n 279 280**Parameters** 281 282| Name | Type | Mandatory | Description | 283| ---- | ---- | ---- | ------- | 284| date | Date | Yes | Date and time to be formatted.| 285 286**Return value** 287 288| Type | Description | 289| ------ | ------------ | 290| string | A string containing the formatted date and time.| 291 292**Example** 293 ```ts 294 let date = new Date(2021, 11, 17, 3, 24, 0); 295 // Use locale en-GB to create a DateTimeFormat object. 296 let datefmt = new intl.DateTimeFormat("en-GB"); 297 let formattedDate = datefmt.format(date); // formattedDate "17/12/2021" 298 299 // Use locale en-GB to create a DateTimeFormat object. Set dateStyle to full and timeStyle to medium. 300 datefmt = new intl.DateTimeFormat("en-GB", { dateStyle: 'full', timeStyle: 'medium' }); 301 formattedDate = datefmt.format(date); // formattedDate "Friday, 17 December 2021 at 03:24:00" 302 ``` 303 304### formatRange 305 306formatRange(startDate: Date, endDate: Date): string 307 308Formats date and time ranges. 309 310**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 311 312**Atomic service API**: This API can be used in atomic services since API version 12. 313 314**System capability**: SystemCapability.Global.I18n 315 316**Parameters** 317 318| Name | Type | Mandatory | Description | 319| --------- | ---- | ---- | -------- | 320| startDate | Date | Yes | Start date and time.| 321| endDate | Date | Yes | End date and time.| 322 323**Return value** 324 325| Type | Description | 326| ------ | -------------- | 327| string | A string containing the formatted date and time ranges.| 328 329**Example** 330 ```ts 331 let startDate = new Date(2021, 11, 17, 3, 24, 0); 332 let endDate = new Date(2021, 11, 18, 3, 24, 0); 333 // Use locale en-GB to create a DateTimeFormat object. 334 let datefmt = new intl.DateTimeFormat("en-GB"); 335 let formattedDateRange = datefmt.formatRange(startDate, endDate); // formattedDateRange = "17/12/2021 - 18/12/2021" 336 ``` 337 338### resolvedOptions 339 340resolvedOptions(): DateTimeOptions 341 342Obtains the options for creating a **DateTimeOptions** object. 343 344**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 345 346**Atomic service API**: This API can be used in atomic services since API version 12. 347 348**System capability**: SystemCapability.Global.I18n 349 350**Return value** 351 352| Type | Description | 353| ------------------------------------ | ----------------------------- | 354| [DateTimeOptions](#datetimeoptions) | Options for the **DateTimeOptions** object.| 355 356**Example** 357 ```ts 358 let datefmt = new intl.DateTimeFormat("en-GB", { dateStyle: 'full', timeStyle: 'medium' }); 359 // Obtain the options of the DateTimeFormat object. 360 let options = datefmt.resolvedOptions(); 361 let dateStyle = options.dateStyle; // dateStyle = "full" 362 let timeStyle = options.timeStyle; // timeStyle = "medium" 363 ``` 364 365 366## DateTimeOptions 367 368Defines the options for a **DateTimeOptions** object. Since API version 9, the **DateTimeOptions** attribute is changed from mandatory to optional. 369 370**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 371 372**Atomic service API**: This API can be used in atomic services since API version 12. 373 374**System capability**: SystemCapability.Global.I18n 375 376| Name | Type | Mandatory | Description | 377| --------------- | ------- | ---- | ---------------------------------------- | 378| locale | string | No |Locale, for example, **zh-Hans-CN**. | 379| dateStyle | string | No |Date format.<br>The value can be **long**, **short**, **medium**, **full**, or **auto**.| 380| timeStyle | string | No |Time format.<br>The value can be **long**, **short**, **medium**, **full**, or **auto**.| 381| hourCycle | string | No |Hour cycle.<br>The value can be **h11**, **h12**, **h23**, or **h24**.| 382| timeZone | string | No |Time zone represented by a valid IANA time zone ID. | 383| numberingSystem | string | No |Numbering system.<br>The value can be any of the following: **adlm**, **ahom**, **arab**, **arabext**, **bali**, **beng**, **bhks**, **brah**, **cakm**, **cham**, **deva**, **diak**, **fullwide**, **gong**, **gonm**, **gujr**, **guru**, **hanidec**, **hmng**, **hmnp**, **java**, **kali**, **khmr**, **knda**, **lana**, **lanatham**, **laoo**, **latn**, **lepc**, **limb**, **mathbold**, **mathdbl**, **mathmono**, **mathsanb**, **mathsans**, **mlym**, **modi**, **mong**, **mroo**, **mtei**, **mymr**, **mymrshan**, **mymrtlng**, **newa**, **nkoo**, **olck**, **orya**, **osma**, **rohg**, **saur**, **segment**, **shrd**, **sind**, **sinh**, **sora**, **sund**, **takr**, **talu**, **tamldec**, **telu**, **thai**, **tibt**, **tirh**, **vaii**, **wara**, **wcho**.| 384| hour12 | boolean | No | Whether to use the 12-hour clock.<br>If **hour12** and **hourCycle** are not set and the 24-hour clock is turned on, the default value of **hour12** is **false**. | 385| weekday | string | No | Workday display format.<br>The value can be **long**, **short**, **narrow**, or **auto**.| 386| era | string | No | Era display format.<br>The value can be **long**, **short**, **narrow**, or **auto**.| 387| year | string | No | Year display format.<br>The value can be **numeric** or **2-digit**. | 388| month | string | No | Month display format.<br>The value can be **numeric**, **2-digit**, **long**, **short**, or **narrow**.| 389| day | string | No | Date display format.<br>The value can be **numeric** or **2-digit**. | 390| hour | string | No | Hour display format.<br>The value can be **numeric** or **2-digit**. | 391| minute | string | No | Minute display format.<br>The value can be **numeric** or **2-digit**. | 392| second | string | No | Second display format.<br>The value can be **numeric** or **2-digit**. | 393| timeZoneName | string | No | Localized representation of a time zone name.<br>The value can be **long**, **short**, or **auto**. | 394| dayPeriod | string | No | Time period display format.<br>The value can be **long**, **short**, **narrow**, or **auto**.3| 395| localeMatcher | string | No | Locale matching algorithm.<br>The value can be **lookup** or **best fit**.| 396| formatMatcher | string | No | Format matching algorithm.<br>The value can be **basic** or **best fit**.| 397 398> **NOTE** 399> 400> - For details about the display effects of **dateStyle**, **timeStyle**, **weekday**, and **year**, see Table 1 in [Date and Time Formatting](../../internationalization/i18n-time-date.md). 401> 402> - For details about the parameter values in different scenarios, see [Date and Time Formatting](../../internationalization/i18n-time-date.md). 403 404## NumberFormat 405 406### constructor<sup>8+</sup> 407 408constructor() 409 410Creates a **NumberFormat** object for the specified locale. 411 412**Atomic service API**: This API can be used in atomic services since API version 12. 413 414**System capability**: SystemCapability.Global.I18n 415 416**Example** 417 ```ts 418 // Use the current system locale to create a NumberFormat object. 419 let numfmt = new intl.NumberFormat(); 420 ``` 421 422 423### constructor 424 425constructor(locale: string | Array<string>, options?: NumberOptions) 426 427Creates a **NumberFormat** object for the specified locale. 428 429**Atomic service API**: This API can be used in atomic services since API version 12. 430 431**System capability**: SystemCapability.Global.I18n 432 433**Parameters** 434 435| Name | Type | Mandatory | Description | 436| -------------------- | -------------------------------- | ---- | ---------------------------- | 437| locale | string \| Array<string> | Yes | A string containing locale information, including the language, optional script, and region.| 438| options | [NumberOptions](#numberoptions) | No | Options for creating the **NumberFormat** object. | 439 440**Example** 441 ```ts 442 // Use locale en-GB to create a NumberFormat object. Set style to decimal and notation to scientific. 443 let numfmt = new intl.NumberFormat("en-GB", {style:'decimal', notation:"scientific"}); 444 ``` 445 446### format 447 448format(number: number): string 449 450Formats a number. 451 452**Atomic service API**: This API can be used in atomic services since API version 12. 453 454**System capability**: SystemCapability.Global.I18n 455 456**Parameters** 457 458| Name | Type | Mandatory | Description | 459| ------ | ------ | ---- | ---- | 460| number | number | Yes | Number to be formatted.| 461 462**Return value** 463 464| Type | Description | 465| ------ | ---------- | 466| string | Formatted number.| 467 468 469**Example** 470 ```ts 471 // Use locale list ["en-GB**, **zh"] to create a NumberFormat object. Because en-GB is a valid locale ID, it is used to create the NumberFormat object. 472 let numfmt = new intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"}); 473 let formattedNumber = numfmt.format(1223); // formattedNumber = 1.223E3 474 ``` 475 476 477### resolvedOptions 478 479resolvedOptions(): NumberOptions 480 481Obtains the options for creating a **NumberFormat** object. 482 483**Atomic service API**: This API can be used in atomic services since API version 12. 484 485**System capability**: SystemCapability.Global.I18n 486 487**Return value** 488 489| Type | Description | 490| -------------------------------- | --------------------------- | 491| [NumberOptions](#numberoptions) | Options for creating the **NumberFormat** object.| 492 493 494**Example** 495 ```ts 496 let numfmt = new intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"}); 497 // Obtain the options of the NumberFormat object. 498 let options = numfmt.resolvedOptions(); 499 let style = options.style; // style = decimal 500 let notation = options.notation; // notation = scientific 501 ``` 502 503## NumberOptions 504 505Options for creating the **NumberFormat** object. Since API version 9, the **NumberOptions** attribute is changed from mandatory to optional. 506 507**Atomic service API**: This API can be used in atomic services since API version 12. 508 509**System capability**: SystemCapability.Global.I18n 510 511| Name | Type | Mandatory | Description | 512| ------------------------ | ------- | ---- | ---------------------------------------- | 513| locale | string | No | Locale, for example, **zh-Hans-CN**.<br>The default value of **locale** is the system locale. | 514| currency | string | No | Currency unit. The value must comply with the [ISO-4217 standard](https://www.iso.org/iso-4217-currency-codes.html), for example, EUR, CNY, and USD.<br>From API version 12, a three-digit number is supported, for example, **978**, **156**, or **840**. | 515| currencySign | string | No | Currency unit symbol. The value can be **standard** or **accounting**.<br>The default value is **standard**.| 516| currencyDisplay | string | No | Currency display mode. The value can be **symbol**, **narrowSymbol**, **code**, or **name**.<br>The default value is **symbol**.| 517| unit | string | No | Unit name, for example, **meter**, **inch**, or **hectare**. | 518| unitDisplay | string | No | Display format of units. The value can be **long**, **short**, or **narrow**.<br>The default value is **short**.| 519| unitUsage<sup>8+</sup> | string | No | Application scenario of units. The value can be any of the following: "default**, **area-land-agricult**, **area-land-commercl**, **area-land-residntl**, **length-person**, **length-person-small**, **length-rainfall**, **length-road**, **length-road-small**, **length-snowfall**, **length-vehicle**, **length-visiblty**, **length-visiblty-small**, **length-person-informal**, **length-person-small-informal**, **length-road-informal**, **speed-road-travel**, **speed-wind**, **temperature-person**, **temperature-weather**, **volume-vehicle-fuel**, **elapsed-time-second**, **size-file-byte**, or **size-shortfile-byte**.<br>The default value is **default**.| 520| signDisplay | string | No | Number sign display format. The value can be **auto**, **never**, **always**, or **expectZero**.<br>The default value is **auto**.| 521| compactDisplay | string | No | Compact display format. The value can be **long** or **short**.<br>The default value is **short**. | 522| notation | string | No | Number formatting specification. The value can be **standard**, **scientific**, **engineering**, or **compact**.<br>The default value is **standard**.| 523| localeMatcher | string | No | Locale matching algorithm. The value can be **lookup** or **best fit**.<br>The default value is **best fit**.| 524| style | string | No | Number display format. The value can be **decimal**, **currency**, **percent**, or **unit**.<br>The default value is **decimal**.| 525| numberingSystem | string | No | Numbering system for the locale. The value can be any of the following: **adlm**, **ahom**, **arab**, **arabext**, **bali**, **beng**, **bhks**, **brah**, **cakm**, **cham**, **deva**, **diak**, **fullwide**, **gong**, **gonm**, **gujr**, **guru**, **hanidec**, **hmng**, **hmnp**, **java**, **kali**, **khmr**, **knda**, **lana**, **lanatham**, **laoo**, **latn**, **lepc**, **limb**, **mathbold**, **mathdbl**, **mathmono**, **mathsanb**, **mathsans**, **mlym**, **modi**, **mong**, **mroo**, **mtei**, **mymr**, **mymrshan**, **mymrtlng**, **newa**, **nkoo**, **olck**, **orya**, **osma**, **rohg**, **saur**, **segment**, **shrd**, **sind**, **sinh**, **sora**, **sund**, **takr**, **talu**, **tamldec**, **telu**, **thai**, **tibt**, **tirh**, **vaii**, **wara**, **wcho**. The default value is the default numbering system of the specified locale.| 526| useGrouping | boolean | No | Whether to use grouping for display. The default value is **auto**. | 527| minimumIntegerDigits | number | No | Minimum number of digits allowed in the integer part of a number. The value ranges from **1** to **21**.<br>The default value of is **1**. | 528| minimumFractionDigits | number | No | Minimum number of digits in the fraction part of a number. The value ranges from **0** to **20**.<br>The default value is **0**. | 529| maximumFractionDigits | number | No | Maximum number of digits in the fraction part of a number. The value ranges from **1** to **21**.<br>The default value is **3**. | 530| minimumSignificantDigits | number | No | Minimum number of the least significant digits. The value ranges from **1** to **21**.<br>The default value of is **1**. | 531| maximumSignificantDigits | number | No | Maximum number of the least significant digits. The value ranges from **1** to **21**.<br>The default value is **21**. | 532 533> **NOTE** 534> 535> - For details about the meaning or display effect of different values, see [Number and Unit of Measurement Formatting](../../internationalization/i18n-numbers-weights-measures.md). 536 537## Collator<sup>8+</sup> 538 539### constructor<sup>8+</sup> 540 541constructor() 542 543Creates a **Collator** object. 544 545**Atomic service API**: This API can be used in atomic services since API version 12. 546 547**System capability**: SystemCapability.Global.I18n 548 549**Example** 550 ```ts 551 // Use the system locale to create a Collator object. 552 let collator = new intl.Collator(); 553 ``` 554 555 556### constructor<sup>8+</sup> 557 558constructor(locale: string | Array<string>, options?: CollatorOptions) 559 560Creates a **Collator** object. 561 562**Atomic service API**: This API can be used in atomic services since API version 12. 563 564**System capability**: SystemCapability.Global.I18n 565 566**Parameters** 567 568| Name | Type | Mandatory | Description | 569| -------------------- | ------------------------------------ | ---- | ---------------------------- | 570| locale | string \| Array<string> | Yes | A string containing locale information, including the language, optional script, and region. | 571| options | [CollatorOptions](#collatoroptions8) | No | Options for creating a **Collator** object. | 572 573**Example** 574 ```ts 575 // Use locale zh-CN to create a Collator object. Set localeMatcher to lookup and usage to sort. 576 let collator = new intl.Collator("zh-CN", {localeMatcher: "lookup", usage: "sort"}); 577 ``` 578 579 580### compare<sup>8+</sup> 581 582compare(first: string, second: string): number 583 584Compares two strings based on the specified collation rules. 585 586**Atomic service API**: This API can be used in atomic services since API version 12. 587 588**System capability**: SystemCapability.Global.I18n 589 590**Parameters** 591 592| Name | Type | Mandatory | Description | 593| ------ | ------ | ---- | ------------ | 594| first | string | Yes | First string to compare. | 595| second | string | Yes | Second string to compare.| 596 597**Return value** 598 599| Type | Description | 600| ------ | ---------------------------------------- | 601| number | Comparison result.<br>- If the value is a negative number, the first string comes before the second string.<br>- If the value is **0**, the first and second strings are in the same sequence.<br>- If the value is a positive number, the first string is comes after the second string.| 602 603**Example** 604 ```ts 605 // Use locale en-GB to create a Collator object. 606 let collator = new intl.Collator("en-GB"); 607 // Compare the sequence of the first and second strings. 608 let compareResult = collator.compare("first", "second"); // compareResult = -1 609 ``` 610 611 612### resolvedOptions<sup>8+</sup> 613 614resolvedOptions(): CollatorOptions 615 616Obtains the options for creating a **Collator** object. 617 618**Atomic service API**: This API can be used in atomic services since API version 12. 619 620**System capability**: SystemCapability.Global.I18n 621 622**Return value** 623 624| Type | Description | 625| ------------------------------------ | ----------------- | 626| [CollatorOptions](#collatoroptions8) | Options for creating a **Collator** object.| 627 628**Example** 629 ```ts 630 let collator = new intl.Collator("zh-Hans", { usage: 'sort', ignorePunctuation: true }); 631 // Obtain the options of the Collator object. 632 let options = collator.resolvedOptions(); 633 let usage = options.usage; // usage = "sort" 634 let ignorePunctuation = options.ignorePunctuation; // ignorePunctuation = true 635 ``` 636 637 638## CollatorOptions<sup>8+</sup> 639 640Defines the options for creating a **Collator** object. 641 642Since API version 9, the attributes in **CollatorOptions** are optional. 643 644**Atomic service API**: This API can be used in atomic services since API version 12. 645 646**System capability**: SystemCapability.Global.I18n 647 648| Name | Type | Mandatory | Description | 649| ----------------- | ------- | ---- | ---------------------------------------- | 650| localeMatcher | string | No | Locale matching algorithm. The value can be **lookup** or **best fit**.<br>The default value is **best fit**.| 651| usage | string | No | Whether the comparison is for sorting or for searching. The value can be **sort** or **search**.<br>The default value is **sort**. | 652| sensitivity | string | No | Differences in the strings that lead to non-zero return values. The value can be **base**, **accent**, **case**, or **letiant**.<br>The default value is **variant**.| 653| ignorePunctuation | boolean | No | Whether punctuation is ignored. The value can be **true** or **false**.<br>The default value is **false**. | 654| collation | string | No | Collation rule.<br>The value can be any of the following: **big5han**, **compat**, **dict**, **direct**, **ducet**, **eor**, **gb2312**, **phonebk**, **phonetic**, **pinyin**, **reformed**, **searchjl**, **stroke**, **trad**, **unihan**, or **zhuyin**.<br>The default value is **default**.| 655| numeric | boolean | No | Whether numeric collation is used. The value can be **true** or **false**.<br>The default value is **false**. | 656| caseFirst | string | No | Whether upper case or lower case is sorted first. The value can be **upper**, **lower**, or **false**.<br>The default value is **false**.| 657 658 659> **NOTE** 660> 661> - For details about the meanings of **usage**, **sensitivity**, **collation**, and **caseFirst**, see [Sorting by Local Habits](../../internationalization/i18n-sorting-local.md). 662 663 664## PluralRules<sup>8+</sup> 665 666### constructor<sup>8+</sup> 667 668constructor() 669 670Creates a **PluralRules** object to obtain the singular-plural type of numbers. 671 672**Atomic service API**: This API can be used in atomic services since API version 12. 673 674**System capability**: SystemCapability.Global.I18n 675 676**Example** 677 ```ts 678 // Use the system locale to create a PluralRules object. 679 let pluralRules = new intl.PluralRules(); 680 ``` 681 682 683### constructor<sup>8+</sup> 684 685constructor(locale: string | Array<string>, options?: PluralRulesOptions) 686 687Creates a **PluralRules** object to obtain the singular-plural type of numbers. 688 689**Atomic service API**: This API can be used in atomic services since API version 12. 690 691**System capability**: SystemCapability.Global.I18n 692 693**Parameters** 694 695| Name | Type | Mandatory | Description | 696| -------------------- | ---------------------------------------- | ---- | ---------------------------- | 697| locale | string \| Array<string> | Yes | A string containing locale information, including the language, optional script, and region.| 698| options | [PluralRulesOptions](#pluralrulesoptions8) | No | Options for creating a **PluralRules** object. | 699 700**Example** 701 ```ts 702 // Use locale zh-CN to create a PluralRules object. Set localeMatcher to lookup and type to cardinal. 703 let pluralRules= new intl.PluralRules("zh-CN", {"localeMatcher": "lookup", "type": "cardinal"}); 704 ``` 705 706### select<sup>8+</sup> 707 708select(n: number): string 709 710Obtains a string that represents the singular-plural type of the specified number. 711 712**Atomic service API**: This API can be used in atomic services since API version 12. 713 714**System capability**: SystemCapability.Global.I18n 715 716**Parameters** 717 718| Name | Type | Mandatory | Description | 719| ---- | ------ | ---- | ------------ | 720| n | number | Yes | Number for which the singular-plural type is to be obtained.| 721 722**Return value** 723 724| Type | Description | 725| ------ | ---------------------------------------- | 726| string | Singular-plural type. The value can be any of the following: **zero**, **one**, **two**, **few**, **many**, **others**.<br>For details about the meanings of different values, see [Language Plural Rules](https://www.unicode.org/cldr/charts/45/supplemental/language_plural_rules.html).| 727 728**Example** 729 ```ts 730 // Use locale zh-Hans to create a PluralRules object. 731 let zhPluralRules = new intl.PluralRules("zh-Hans"); 732 // Determine the singular-plural type corresponding to number 1 in locale zh-Hans. 733 let plural = zhPluralRules.select(1); // plural = other 734 735 // Use locale en-US to create a PluralRules object. 736 let enPluralRules = new intl.PluralRules("en-US"); 737 // Determine the singular-plural type corresponding to number 1 in locale en-US. 738 plural = enPluralRules.select(1); // plural = one 739 ``` 740 741 742## PluralRulesOptions<sup>8+</sup> 743 744Defines the options for creating a **PluralRules** object. Since API version 9, the **PluralRulesOptions** attribute is changed from mandatory to optional. 745 746**Atomic service API**: This API can be used in atomic services since API version 12. 747 748**System capability**: SystemCapability.Global.I18n 749 750| Name | Type | Readable | Writable | Description | 751| ------------------------ | ------ | ---- | ---- | ---------------------------------------- | 752| localeMatcher | string | Yes | Yes | Locale matching algorithm. The value can be **lookup** or **best fit**.<br>The default value is **best fit**.| 753| type | string | Yes | Yes | Collation type. The value can be **cardinal** or **ordinal**.<br>The default value is **cardinal**.<br>The value **cardinal** indicates a cardinal number and the value **ordinal** indicates an ordinal number. | 754| minimumIntegerDigits | number | Yes | Yes | Minimum number of digits allowed in the integer part of a number. The value ranges from **1** to **21**.<br>The default value is **1**. | 755| minimumFractionDigits | number | Yes | Yes | Minimum number of digits in the fraction part of a number. The value ranges from **0** to **20**.<br>The default value is **0**. | 756| maximumFractionDigits | number | Yes | Yes | Maximum number of digits in the fraction part of a number. The value ranges from **1** to **21**.<br>The default value is **3**. | 757| minimumSignificantDigits | number | Yes | Yes | Minimum number of the least significant digits. The value ranges from **1** to **21**.<br>The default value is **1**. | 758| maximumSignificantDigits | number | Yes | Yes | Maximum number of the least significant digits. The value ranges from **1** to **21**.<br>The default value is **21**. | 759 760 761## RelativeTimeFormat<sup>8+</sup> 762 763### constructor<sup>8+</sup> 764 765constructor() 766 767Creates a **RelativeTimeFormat** object. 768 769**Atomic service API**: This API can be used in atomic services since API version 12. 770 771**System capability**: SystemCapability.Global.I18n 772 773**Example** 774 ```ts 775 // Use the system locale to create a RelativeTimeFormat object. 776 let relativetimefmt = new intl.RelativeTimeFormat(); 777 ``` 778 779 780### constructor<sup>8+</sup> 781 782constructor(locale: string | Array<string>, options?: RelativeTimeFormatInputOptions) 783 784Creates a **RelativeTimeFormat** object. 785 786**Atomic service API**: This API can be used in atomic services since API version 12. 787 788**System capability**: SystemCapability.Global.I18n 789 790**Parameters** 791 792| Name | Type | Mandatory | Description | 793| -------------------- | ---------------------------------------- | ---- | ---------------------------- | 794| locale | string \| Array<string> | Yes | A string containing locale information, including the language, optional script, and region.| 795| options | [RelativeTimeFormatInputOptions](#relativetimeformatinputoptions8) | No | Options for creating a **RelativeTimeFormat** object. | 796 797**Example** 798 ```ts 799 // Use locale zh-CN to create a RelativeTimeFormat object. Set localeMatcher to lookup, numeric to always, and style to long. 800 let relativeTimeFormat = new intl.RelativeTimeFormat("zh-CN", {"localeMatcher": "lookup", "numeric": "always", "style": "long"}); 801 ``` 802 803 804### format<sup>8+</sup> 805 806format(value: number, unit: string): string 807 808Formats the value and unit based on the specified locale and formatting options. 809 810**Atomic service API**: This API can be used in atomic services since API version 12. 811 812**System capability**: SystemCapability.Global.I18n 813 814**Parameters** 815 816| Name | Type | Mandatory | Description | 817| ----- | ------ | ---- | ---------------------------------------- | 818| value | number | Yes | Value to format. | 819| unit | string | Yes | Unit of the relative time.<br>The value can be any of the following: **year**, **quarter**, month**, **week**, **day**, **hour**, **minute**, or **second**.| 820 821**Return value** 822 823| Type | Description | 824| ------ | ---------- | 825| string | Relative time after formatting.| 826 827**Example** 828 ```ts 829 // Use locale zh-CN to create a RelativeTimeFormat object. 830 let relativetimefmt = new intl.RelativeTimeFormat("zh-CN"); 831 // Obtain the localized representation (in unit of quarter) of number 3 in locale zh-CN. 832 let formatResult = relativetimefmt.format(3, "quarter"); // formatResult = "3 quarters later" 833 ``` 834 835 836### formatToParts<sup>8+</sup> 837 838formatToParts(value: number, unit: string): Array<object> 839 840Custom relative time for the specified locale. 841 842**Atomic service API**: This API can be used in atomic services since API version 12. 843 844**System capability**: SystemCapability.Global.I18n 845 846**Parameters** 847 848| Name | Type | Mandatory | Description | 849| ----- | ------ | ---- | ---------------------------------------- | 850| value | number | Yes | Value to format. | 851| unit | string | Yes | Unit of the relative time.<br>The value can be any of the following: **year**, **quarter**, month**, **week**, **day**, **hour**, **minute**, or **second**.| 852 853**Return value** 854 855| Type | Description | 856| ------------------- | --------------------------- | 857| Array<object> | Object array of the relative time format.| 858 859**Example** 860 ```ts 861 // Use locale en to create a RelativeTimeFormat object. Set numeric to auto. 862 let relativetimefmt = new intl.RelativeTimeFormat("en", {"numeric": "auto"}); 863 let parts = relativetimefmt.formatToParts(10, "seconds"); // parts = [ {type: "literal", value: "in"}, {type: "integer", value: 10, unit: "second"}, {type: "literal", value: "seconds"} ] 864 ``` 865 866 867### resolvedOptions<sup>8+</sup> 868 869resolvedOptions(): RelativeTimeFormatResolvedOptions 870 871Obtains the formatting options for **RelativeTimeFormat** objects. 872 873**Atomic service API**: This API can be used in atomic services since API version 12. 874 875**System capability**: SystemCapability.Global.I18n 876 877**Return value** 878 879| Type | Description | 880| ---------------------------------------- | --------------------------------- | 881| [RelativeTimeFormatResolvedOptions](#relativetimeformatresolvedoptions8) | Formatting options for **RelativeTimeFormat** objects.| 882 883**Example** 884 ```ts 885 // Use locale en-GB to create a RelativeTimeFormat object. 886 let relativetimefmt= new intl.RelativeTimeFormat("en-GB", { style: "short" }); 887 // Obtain the options of the RelativeTimeFormat object. 888 let options = relativetimefmt.resolvedOptions(); 889 let style = options.style; // style = "short" 890 ``` 891 892 893## RelativeTimeFormatInputOptions<sup>8+</sup> 894 895Defines the options for creating a **RelativeTimeFormat** object. 896 897Since API version 9, the attributes in **RelativeTimeFormatInputOptions** are optional. 898 899**Atomic service API**: This API can be used in atomic services since API version 12. 900 901**System capability**: SystemCapability.Global.I18n 902 903| Name | Type | Mandatory |Description | 904| ------------- | ------ | ---- | ---------------------------------------- | 905| localeMatcher | string | No | Locale matching algorithm. The value can be **lookup** or **best fit**.<br>The default value is **best fit**.| 906| numeric | string | No | Format of the output message. The value can be **always** or **auto**.<br>The default value is **always**. | 907| style | string | No | Length of an internationalized message. The value can be **long**, **short**, or **narrow**.<br>The default value is **long**.| 908 909> **NOTE** 910> 911> For details about the display effects of **numeric** and **style**, see [Date and Time Formatting](../../internationalization/i18n-time-date.md#relative-time-formatting). 912 913## RelativeTimeFormatResolvedOptions<sup>8+</sup> 914 915Represents the properties of a **RelativeTimeFormat** object. 916 917**Atomic service API**: This API can be used in atomic services since API version 12. 918 919**System capability**: SystemCapability.Global.I18n 920 921| Name | Type | Mandatory |Description | 922| --------------- | ------ | ---- | ---------------------------------------- | 923| locale | string | Yes | A string containing locale information, including the language, optional script, and region. | 924| numeric | string | Yes | Format of the output message. The value can be **always** or **auto**. | 925| style | string | Yes | Length of an internationalized message. The value can be **long**, **short**, or **narrow**.| 926| numberingSystem | string | Yes | Numbering system. | 927