1# @ohos.i18n (Internationalization) 2 3This 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. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9> - 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. 10> 11> - Since API version 11, some APIs of this module are supported in ArkTS widgets. 12 13 14## Modules to Import 15 16```ts 17import { i18n } from '@kit.LocalizationKit'; 18``` 19 20## System<sup>9+</sup> 21 22### getDisplayCountry<sup>9+</sup> 23 24static getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): string 25 26Obtains the localized display of the text for the specified country. 27 28**Atomic service API**: This API can be used in atomic services since API version 12. 29 30**System capability**: SystemCapability.Global.I18n 31 32**Parameters** 33 34| Name | Type | Mandatory | Description | 35| ------------ | ------- | ---- | ---------------- | 36| country | string | Yes | Valid country code. | 37| locale | string | Yes | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region. | 38| sentenceCase | boolean | No | Whether to use sentence case to display the text. The value **true** means to display the text in title case format, and the value **false** means to display the text in the default case format of the locale. The default value is **true**.| 39 40**Return value** 41 42| Type | Description | 43| ------ | ------------- | 44| string | Localized display of the text.| 45 46**Error codes** 47 48For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 49 50| ID | Error Message | 51| ------ | ---------------------- | 52| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 53| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 54 55> **Description** 56> 57> The error message of 890001 is subject to the actual error. 58 59**Example** 60 ```ts 61 import { BusinessError } from '@kit.BasicServicesKit'; 62 63 try { 64 let displayCountry: string = i18n.System.getDisplayCountry('CN', 'en-GB'); // displayCountry = 'China' 65 } catch (error) { 66 let err: BusinessError = error as BusinessError; 67 console.error(`call System.getDisplayCountry failed, error code: ${err.code}, message: ${err.message}.`); 68 } 69 ``` 70 71### getDisplayLanguage<sup>9+</sup> 72 73static getDisplayLanguage(language: string, locale: string, sentenceCase?: boolean): string 74 75Obtains the localized display of the text for the specified language. For example, if **getDisplayLanguage('de', 'zh-Hans-CN')** is called to display German in Chinese, the output is in German. 76 77**Atomic service API**: This API can be used in atomic services since API version 11. 78 79**System capability**: SystemCapability.Global.I18n 80 81**Parameters** 82 83| Name | Type | Mandatory | Description | 84| ------------ | ------- | ---- | ---------------- | 85| language | string | Yes | Valid language ID. | 86| locale | string | Yes | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region. | 87| sentenceCase | boolean | No | Whether to use sentence case to display the text. The value **true** means to display the text in title case format, and the value **false** means to display the text in the default case format of the locale. The default value is **true**.| 88 89**Return value** 90 91| Type | Description | 92| ------ | ------------- | 93| string | Localized display of the text for the specified language.| 94 95**Error codes** 96 97For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 98 99| ID | Error Message | 100| ------ | ---------------------- | 101| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 102| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 103 104**Example** 105 ```ts 106 import { BusinessError } from '@kit.BasicServicesKit'; 107 108 try { 109 // displayLanguage = 'Chinese', that is, display Chinese in English. 110 let displayLanguage: string = i18n.System.getDisplayLanguage('zh', 'en-GB'); 111 } catch (error) { 112 let err: BusinessError = error as BusinessError; 113 console.error(`call System.getDisplayLanguage failed, error code: ${err.code}, message: ${err.message}.`); 114 } 115 ``` 116 117### getSystemLanguages<sup>9+</sup> 118 119static getSystemLanguages(): Array<string> 120 121Obtains the list of system languages. 122 123Since API version 11, this API is supported in ArkTS widgets. 124 125**Atomic service API**: This API can be used in atomic services since API version 12. 126 127**System capability**: SystemCapability.Global.I18n 128 129**Return value** 130 131| Type | Description | 132| ------------------- | ------------ | 133| Array<string> | List of the IDs of system languages.| 134 135**Example** 136 ```ts 137 // systemLanguages = [ 'ug', 'bo', 'zh-Hant', 'en-Latn-US', 'zh-Hans' ] 138 let systemLanguages: Array<string> = i18n.System.getSystemLanguages(); 139 ``` 140 141### getSystemCountries<sup>9+</sup> 142 143static getSystemCountries(language: string): Array<string> 144 145Obtains the list of countries and regions supported for the specified language. 146 147**Atomic service API**: This API can be used in atomic services since API version 12. 148 149**System capability**: SystemCapability.Global.I18n 150 151**Parameters** 152 153| Name | Type | Mandatory | Description | 154| -------- | ------ | ---- | ----- | 155| language | string | Yes | Valid language ID.| 156 157**Return value** 158 159| Type | Description | 160| ------------------- | ------------ | 161| Array<string> | List of countries or regions supported for the specified language.| 162 163**Error codes** 164 165For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 166 167| ID | Error Message | 168| ------ | ---------------------- | 169| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 170| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 171 172> **Description** 173> 174> The error message of 890001 is subject to the actual error. 175 176**Example** 177 ```ts 178 import { BusinessError } from '@kit.BasicServicesKit'; 179 180 try { 181 // systemCountries = [ 'ZW', 'YT', 'YE', ..., 'ER', 'CN', 'DE' ] 182 let systemCountries: Array<string> = i18n.System.getSystemCountries('zh'); 183 } catch (error) { 184 let err: BusinessError = error as BusinessError; 185 console.error(`call System.getSystemCountries failed, error code: ${err.code}, message: ${err.message}.`); 186 } 187 ``` 188 189### isSuggested<sup>9+</sup> 190 191static isSuggested(language: string, region?: string): boolean 192 193Checks whether the system language matches the specified region. 194 195**Atomic service API**: This API can be used in atomic services since API version 12. 196 197**System capability**: SystemCapability.Global.I18n 198 199**Parameters** 200 201| Name | Type | Mandatory | Description | 202| -------- | ------ | ---- | ------------- | 203| language | string | Yes | Valid language ID, for example, **zh**.| 204| region | string | No | Valid region ID, for example, **CN**.<br>The default value is the country or region where the SIM card is used. | 205 206**Return value** 207 208| Type | Description | 209| ------- | ---------------------------------------- | 210| boolean | **true** if the current language matches the locale, and **false** otherwise.| 211 212**Error codes** 213 214For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 215 216| ID | Error Message | 217| ------ | ---------------------- | 218| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 219| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 220 221 222> **Description** 223> 224> The error message of 890001 is subject to the actual error. 225 226**Example** 227 ```ts 228 import { BusinessError } from '@kit.BasicServicesKit'; 229 230 try { 231 let isSuggestedCountry: boolean = i18n.System.isSuggested('zh', 'CN'); // isSuggestedCountry = true 232 } catch (error) { 233 let err: BusinessError = error as BusinessError; 234 console.error(`call System.isSuggested failed, error code: ${err.code}, message: ${err.message}.`); 235 } 236 ``` 237 238### getSystemLanguage<sup>9+</sup> 239 240static getSystemLanguage(): string 241 242Obtains the system language. 243 244**Atomic service API**: This API can be used in atomic services since API version 11. 245 246**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 247 248**System capability**: SystemCapability.Global.I18n 249 250**Return value** 251 252| Type | Description | 253| ------ | ------- | 254| string | System language ID.| 255 256**Example** 257 ```ts 258 let systemLanguage: string = i18n.System.getSystemLanguage(); 259 ``` 260 261### getSystemRegion<sup>9+</sup> 262 263static getSystemRegion(): string 264 265Obtains the system region. 266 267**Atomic service API**: This API can be used in atomic services since API version 12. 268 269**System capability**: SystemCapability.Global.I18n 270 271**Return value** 272 273| Type | Description | 274| ------ | ------- | 275| string | System region ID.| 276 277**Example** 278 ```ts 279 let systemRegion: string = i18n.System.getSystemRegion(); 280 ``` 281 282### getSystemLocale<sup>9+</sup> 283 284static getSystemLocale(): string 285 286Obtains the system locale. 287 288**Atomic service API**: This API can be used in atomic services since API version 11. 289 290**System capability**: SystemCapability.Global.I18n 291 292**Return value** 293 294| Type | Description | 295| ------ | ------- | 296| string | Locale information.| 297 298**Example** 299 ```ts 300 let systemLocale: string = i18n.System.getSystemLocale(); 301 ``` 302 303### is24HourClock<sup>9+</sup> 304 305static is24HourClock(): boolean 306 307Checks whether the 24-hour clock is used. 308 309**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets. 310 311**Atomic service API**: This API can be used in atomic services since API version 12. 312 313**System capability**: SystemCapability.Global.I18n 314 315**Return value** 316 317| Type | Description | 318| ------- | ---------------------------------------- | 319| boolean | **true** if the 24-hour clock is used, and **false** otherwise.| 320 321**Example** 322 ```ts 323 let is24HourClock: boolean = i18n.System.is24HourClock(); 324 ``` 325 326 327### getPreferredLanguageList<sup>9+</sup> 328 329static getPreferredLanguageList(): Array<string> 330 331Obtains the list of preferred languages. 332 333**Atomic service API**: This API can be used in atomic services since API version 12. 334 335**System capability**: SystemCapability.Global.I18n 336 337**Return value** 338 339| Type | Description | 340| ------------------- | --------- | 341| Array<string> | List of preferred languages.| 342 343**Example** 344 ```ts 345 let preferredLanguageList: Array<string> = i18n.System.getPreferredLanguageList(); 346 ``` 347 348### getFirstPreferredLanguage<sup>9+</sup> 349 350static getFirstPreferredLanguage(): string 351 352Obtains the first language in the preferred language list. 353 354**Atomic service API**: This API can be used in atomic services since API version 12. 355 356**System capability**: SystemCapability.Global.I18n 357 358**Return value** 359 360| Type | Description | 361| ------ | -------------- | 362| string | First language in the preferred language list.| 363 364**Example** 365 ```ts 366 let firstPreferredLanguage: string = i18n.System.getFirstPreferredLanguage(); 367 ``` 368 369### setAppPreferredLanguage<sup>11+</sup> 370 371static setAppPreferredLanguage(language: string): void 372 373Sets the preferred language of the application. If the preferred language is set to **default**, the application's language will be the same as the system language, and the setting will take effect upon cold starting of the application. 374 375**Atomic service API**: This API can be used in atomic services since API version 12. 376 377**System capability**: SystemCapability.Global.I18n 378 379**Parameters** 380 381| Name | Type | Mandatory | Description | 382| -------- | ------ | ---- | ----- | 383| language | string | Yes | Valid language ID or **default**.| 384 385**Error codes** 386 387For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 388 389| ID | Error Message | 390| ------ | ---------------------- | 391| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 392| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 393 394**Example** 395 ```ts 396 import { BusinessError } from '@kit.BasicServicesKit'; 397 398 try { 399 i18n.System.setAppPreferredLanguage('zh'); 400 } catch (error) { 401 let err: BusinessError = error as BusinessError; 402 console.error(`call System.setAppPreferredLanguage failed, error code: ${err.code}, message: ${err.message}.`); 403 } 404 ``` 405 406### getAppPreferredLanguage<sup>9+</sup> 407 408static getAppPreferredLanguage(): string 409 410Obtains the preferred language of an application. 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**Return value** 417 418| Type | Description | 419| ------ | -------- | 420| string | Preferred language of the application.| 421 422**Example** 423 ```ts 424 let appPreferredLanguage: string = i18n.System.getAppPreferredLanguage(); 425 ``` 426 427 428### getUsingLocalDigit<sup>9+</sup> 429 430static getUsingLocalDigit(): boolean 431 432Checks whether use of local digits is enabled. 433 434**Atomic service API**: This API can be used in atomic services since API version 12. 435 436**System capability**: SystemCapability.Global.I18n 437 438**Return value** 439 440| Type | Description | 441| ------- | ---------------------------------------- | 442| boolean | The value **true** indicates that the local digit switch is enabled, and the value **false** indicates the opposite.| 443 444**Example** 445 ```ts 446 let usingLocalDigit: boolean = i18n.System.getUsingLocalDigit(); 447 ``` 448 449### getSimplifiedLanguage<sup>15+</sup> 450 451static getSimplifiedLanguage(language?: string): string 452 453Obtains the simplified representation of a language. For example, the simplified representation of **en-Latn-US** is **en**, and that of **en-Latn-GB** is **en-GB**. 454 455**Atomic service API**: This API can be used in atomic services since API version 15. 456 457**System capability**: SystemCapability.Global.I18n 458 459**Parameters** 460 461| Name | Type | Mandatory | Description | 462| -------- | ------ | ---- | ------------- | 463| language | string | No | Valid language ID. The default value is the system language.| 464 465**Return value** 466 467| Type | Description | 468| ------- | ---------------------------------------- | 469| string | If **language** is not passed, the application checks for dialects supported by the system based on the system language and locale. If such a dialect is found, the simplified representation of the dialect is returned. Otherwise, the simplified representation of the system language is returned.<br>If **language** is passed, the simplified representation of the specified language is returned.| 470 471**Error codes** 472 473For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 474 475| ID | Error Message | 476| ------ | ---------------------- | 477| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 478| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 479 480**Example** 481 ```ts 482 import { BusinessError } from '@kit.BasicServicesKit'; 483 484 try { 485 // simplifiedLanguage = 'zh' 486 let simplifiedLanguage: string = i18n.System.getSimplifiedLanguage('zh-Hans-CN'); 487 // simplifiedSystemLanguage = 'zh-Hans' if the current system language is simplified Chinese. 488 let simplifiedSystemLanguage: string = i18n.System.getSimplifiedLanguage(); 489 } catch (error) { 490 let err: BusinessError = error as BusinessError; 491 console.error(`call System.getSimplifiedLanguage failed, error code: ${err.code}, message: ${err.message}.`); 492 } 493 ``` 494 495### getTemperatureType<sup>18+</sup> 496 497static getTemperatureType(): TemperatureType 498 499Obtains the preferred temperature unit for the current user. 500 501**Atomic service API**: This API can be used in atomic services since API version 18. 502 503**System capability**: SystemCapability.Global.I18n 504 505**Return value** 506 507| Type | Description | 508| ------ | ------------- | 509| [TemperatureType](#temperaturetype18) | Temperature unit.| 510 511**Example** 512 ```ts 513 let temperatureType: i18n.TemperatureType = i18n.System.getTemperatureType(); 514 ``` 515 516### getTemperatureName<sup>18+</sup> 517 518static getTemperatureName(type: TemperatureType): string 519 520Obtains the name of a temperature unit. 521 522**Atomic service API**: This API can be used in atomic services since API version 18. 523 524**System capability**: SystemCapability.Global.I18n 525 526**Parameters** 527 528| Name | Type | Mandatory | Description | 529| -------- | ------ | ---- | ------------- | 530| type| [TemperatureType](#temperaturetype18) | Yes | Temperature unit.| 531 532**Return value** 533 534| Type | Description | 535| ------- | ---------------------------------------- | 536| string | Name of the temperature unit, which can be **celsius**, **fahrenheit**, and **kelvin**.| 537 538**Error codes** 539 540For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 541 542| ID | Error Message | 543| ------ | ---------------------- | 544| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 545| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 546 547 548> **Description** 549> 550> The error message of 890001 is subject to the actual error. 551 552**Example** 553 ```ts 554 import { BusinessError } from '@kit.BasicServicesKit'; 555 556 try { 557 // temperatureName = 'celsius' 558 let temperatureName: string = i18n.System.getTemperatureName(i18n.TemperatureType.CELSIUS); 559 } catch (error) { 560 let err: BusinessError = error as BusinessError; 561 console.error(`call System.getTemperatureName failed, error code: ${err.code}, message: ${err.message}.`); 562 } 563 ``` 564 565### getFirstDayOfWeek<sup>18+</sup> 566 567static getFirstDayOfWeek(): WeekDay 568 569Obtains the preferred start day of a week for the current user. 570 571**Atomic service API**: This API can be used in atomic services since API version 18. 572 573**System capability**: SystemCapability.Global.I18n 574 575**Return value** 576 577| Type | Description | 578| ------ | ------------- | 579| [WeekDay](#weekday18) | Start day of a week.| 580 581**Example** 582 ```ts 583 let firstDayOfWeek: i18n.WeekDay = i18n.System.getFirstDayOfWeek(); 584 ``` 585 586## TemperatureType<sup>18+</sup> 587 588Enumerates temperature units. 589 590**Atomic service API**: This API can be used in atomic services since API version 18. 591 592**System capability**: SystemCapability.Global.I18n 593 594| Name| Value| Description| 595| -------- | -------- | -------- | 596| CELSIUS | 1 | Celsius.| 597| FAHRENHEIT | 2 | Fahrenheit.| 598| KELVIN | 3 | Kelvin.| 599 600## WeekDay<sup>18+</sup> 601 602Enumerates the start day of a week. The value is a day from Monday to Sunday. 603 604**Atomic service API**: This API can be used in atomic services since API version 18. 605 606**System capability**: SystemCapability.Global.I18n 607 608| Name| Value| Description| 609| -------- | -------- | -------- | 610| MON | 1 | Monday.| 611| TUE | 2 | Tuesday.| 612| WED | 3 | Wednesday.| 613| THU | 4 | Thursday.| 614| FRI | 5 | Friday.| 615| SAT | 6 | Saturday.| 616| SUN | 7 | Sunday.| 617 618 619## i18n.isRTL 620 621isRTL(locale: string): boolean 622 623Checks whether a locale uses a right-to-left (RTL) language. 624 625**Atomic service API**: This API can be used in atomic services since API version 12. 626 627**System capability**: SystemCapability.Global.I18n 628 629**Parameters** 630 631| Name | Type | Mandatory | Description | 632| ------ | ------ | ---- | ------- | 633| locale | string | Yes | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region. | 634 635**Return value** 636 637| Type | Description | 638| ------- | ---------------------------------------- | 639| boolean | The value **true** indicates that the locale uses an RTL language, and the value **false** indicates the opposite.| 640 641**Example** 642 ```ts 643 let isZhRTL: boolean = i18n.isRTL('zh-CN'); // Since Chinese is not written from right to left, false is returned. 644 let isArRTL: boolean = i18n.isRTL('ar-EG'); // Since Arabic is written from right to left, true is returned. 645 ``` 646 647## i18n.getCalendar<sup>8+</sup> 648 649getCalendar(locale: string, type? : string): Calendar 650 651Obtains a **Calendar** object. 652 653**Atomic service API**: This API can be used in atomic services since API version 12. 654 655**System capability**: SystemCapability.Global.I18n 656 657**Parameters** 658 659| Name | Type | Mandatory | Description | 660| ------ | ------ | ---- | ---------------------------------------- | 661| locale | string | Yes | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region, for example, **zh-Hans-CN**. | 662| type | string | No | Valid calendar type. The value can be **buddhist**, **chinese**, **coptic**, **ethiopic**, **hebrew**, **gregory**, **indian**, **islamic_civil**, **islamic_tbla**, **islamic_umalqura**, **japanese**, or **persian**.<br>The default value is the default calendar type of the locale. For details, see [Calendar Setting](../../internationalization/i18n-calendar.md).| 663 664**Return value** 665 666| Type | Description | 667| ---------------------- | ----- | 668| [Calendar](#calendar8) | **Calendar** object.| 669 670**Example** 671 ```ts 672 let calendar: i18n.Calendar = i18n.getCalendar('zh-Hans', 'chinese'); // Obtain the Calendar object for the Chinese lunar calendar. 673 ``` 674 675## EntityRecognizer<sup>11+</sup> 676 677### constructor<sup>11+</sup> 678 679constructor(locale?: string) 680 681Creates an **entityRecognizer** object. 682 683**Atomic service API**: This API can be used in atomic services since API version 12. 684 685**System capability**: SystemCapability.Global.I18n 686 687**Parameters** 688 689| Name | Type | Mandatory | Description | 690| ---- | ---- | ---- | ----------------- | 691| locale | string | No | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region, for example, **zh-Hans-CN**.<br>The default value is the current system locale.| 692 693**Error codes** 694 695For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 696 697| ID | Error Message | 698| ------ | ---------------------- | 699| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 700| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 701 702**Example** 703 ```ts 704 import { BusinessError } from '@kit.BasicServicesKit'; 705 706 try { 707 let entityRecognizer: i18n.EntityRecognizer = new i18n.EntityRecognizer('zh-CN'); 708 } catch (error) { 709 let err: BusinessError = error as BusinessError; 710 console.error(`call new i18n.EntityRecognizer failed, error code: ${err.code}, message: ${err.message}.`); 711 } 712 ``` 713 714### findEntityInfo<sup>11+</sup> 715 716findEntityInfo(text: string): Array<EntityInfoItem> 717 718Recognizes entities in text. 719 720**Atomic service API**: This API can be used in atomic services since API version 12. 721 722**System capability**: SystemCapability.Global.I18n 723 724**Parameters** 725 726| Name | Type | Mandatory | Description | 727| ---- | ---- | ---- | ----------------- | 728| text | string | Yes | Text to be recognized.| 729 730**Return value** 731 732| Type | Description | 733| ---- | ----------------- | 734| Array<[EntityInfoItem](#entityinfoitem11)> | List of entities in the text.| 735 736**Error codes** 737 738For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 739 740| ID | Error Message | 741| ------ | ---------------------- | 742| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 743 744**Example** 745 ```ts 746 import { BusinessError } from '@kit.BasicServicesKit'; 747 748 try { 749 let entityRecognizer: i18n.EntityRecognizer = new i18n.EntityRecognizer('zh-CN'); 750 let phoneNumberText: string = 'If you have any questions, call us by phone 12345678.'; 751 // phoneNumberEntity[0].type = 'phone_number', phoneNumberEntity[0].begin = 8, phoneNumberEntity[0].end = 19 752 let phoneNumberEntity: Array<i18n.EntityInfoItem> = entityRecognizer.findEntityInfo(phoneNumberText); 753 let dateText: string = 'Let's have dinner on December 1, 2023.'; 754 // dateEntity[0].type = 'date', dateEntity[0].begin = 2, dateEntity[0].end = 12 755 let dateEntity: Array<i18n.EntityInfoItem> = entityRecognizer.findEntityInfo(dateText); 756 } catch (error) { 757 let err: BusinessError = error as BusinessError; 758 console.error(`call EntityRecognizer.findEntityInfo failed, error code: ${err.code}, message: ${err.message}.`); 759 } 760 ``` 761 762## EntityInfoItem<sup>11+</sup> 763 764Defines a list of entities. 765 766**Atomic service API**: This API can be used in atomic services since API version 12. 767 768**System capability**: SystemCapability.Global.I18n 769 770| Name | Type | Readable | Writable | Description | 771| ---- | ---- | ---- | ---- | ----------------- | 772| type | string | Yes | Yes | Entity type. The value can be **phone_number** or **date**.| 773| begin | number | Yes | Yes | Start position of an entity.| 774| end | number | Yes | Yes | End position of an entity.| 775 776## Calendar<sup>8+</sup> 777 778### setTime<sup>8+</sup> 779 780setTime(date: Date): void 781 782Sets the date and time for a **Calendar** object. 783 784**Atomic service API**: This API can be used in atomic services since API version 12. 785 786**System capability**: SystemCapability.Global.I18n 787 788**Parameters** 789 790| Name | Type | Mandatory | Description | 791| ---- | ---- | ---- | ----------------- | 792| date | Date | Yes | Date and time. Note: The month starts from **0**. For example, **0** indicates January.| 793 794**Example** 795 ```ts 796 let calendar: i18n.Calendar = i18n.getCalendar('en-US', 'gregory'); 797 let date: Date = new Date(2021, 10, 7, 8, 0, 0); // The date and time is 2021.11.07 08:00:00. 798 calendar.setTime(date); 799 ``` 800 801 802### setTime<sup>8+</sup> 803 804setTime(time: number): void 805 806Sets the date and time for a **Calendar** object. 807 808**Atomic service API**: This API can be used in atomic services since API version 12. 809 810**System capability**: SystemCapability.Global.I18n 811 812**Parameters** 813 814| Name | Type | Mandatory | Description | 815| ---- | ------ | ---- | ---------------------------------------- | 816| time | number | Yes | Number of milliseconds that have elapsed since the Unix epoch.| 817 818**Example** 819 ```ts 820 let calendar: i18n.Calendar = i18n.getCalendar('en-US', 'gregory'); 821 calendar.setTime(10540800000); 822 ``` 823 824### set<sup>8+</sup> 825 826set(year: number, month: number, date:number, hour?: number, minute?: number, second?: number): void 827 828Sets the year, month, day, hour, minute, and second for this **Calendar** object. 829 830**Atomic service API**: This API can be used in atomic services since API version 12. 831 832**System capability**: SystemCapability.Global.I18n 833 834**Parameters** 835 836| Name | Type | Mandatory | Description | 837| ------ | ------ | ---- | ------ | 838| year | number | Yes | Year to set. | 839| month | number | Yes | Month to set. Note: The month starts from **0**. For example, **0** indicates January. | 840| date | number | Yes | Day to set. | 841| hour | number | No | Hour to set. The default value is the system hour.| 842| minute | number | No | Minute to set. The default value is the system minute.| 843| second | number | No | Second to set. The default value is the system second.| 844 845**Example** 846 ```ts 847 let calendar: i18n.Calendar = i18n.getCalendar('zh-Hans'); 848 calendar.set(2021, 10, 1, 8, 0, 0); // Set the date and time to 2021.11.1 08:00:00. 849 ``` 850 851### setTimeZone<sup>8+</sup> 852 853setTimeZone(timezone: string): void 854 855Sets the time zone of this **Calendar** object. 856 857**Atomic service API**: This API can be used in atomic services since API version 12. 858 859**System capability**: SystemCapability.Global.I18n 860 861**Parameters** 862 863| Name | Type | Mandatory | Description | 864| -------- | ------ | ---- | ------------------------- | 865| timezone | string | Yes | Valid time zone ID, for example, Asia/Shanghai.| 866 867**Example** 868 ```ts 869 let calendar: i18n.Calendar = i18n.getCalendar('zh-Hans'); 870 calendar.setTimeZone('Asia/Shanghai'); 871 ``` 872 873 874### getTimeZone<sup>8+</sup> 875 876getTimeZone(): string 877 878Obtains the time zone of this **Calendar** object. 879 880**Atomic service API**: This API can be used in atomic services since API version 12. 881 882**System capability**: SystemCapability.Global.I18n 883 884**Return value** 885 886| Type | Description | 887| ------ | ---------- | 888| string | Time zone ID.| 889 890**Example** 891 ```ts 892 let calendar: i18n.Calendar = i18n.getCalendar('zh-Hans'); 893 calendar.setTimeZone('Asia/Shanghai'); 894 let timezone: string = calendar.getTimeZone(); // timezone = 'Asia/Shanghai' 895 ``` 896 897 898### getFirstDayOfWeek<sup>8+</sup> 899 900getFirstDayOfWeek(): number 901 902Obtains the start day of a week for a **Calendar** object. 903 904**Atomic service API**: This API can be used in atomic services since API version 12. 905 906**System capability**: SystemCapability.Global.I18n 907 908**Return value** 909 910| Type | Description | 911| ------ | --------------------- | 912| number | Start day of a week. The value **1** indicates Sunday, and the value **7** indicates Saturday.| 913 914**Example** 915 ```ts 916 let calendar: i18n.Calendar = i18n.getCalendar('en-US', 'gregory'); 917 let firstDayOfWeek: number = calendar.getFirstDayOfWeek(); // firstDayOfWeek = 1 918 ``` 919 920 921### setFirstDayOfWeek<sup>8+</sup> 922 923setFirstDayOfWeek(value: number): void 924 925Sets the start day of a week for a **Calendar** object. 926 927**Atomic service API**: This API can be used in atomic services since API version 12. 928 929**System capability**: SystemCapability.Global.I18n 930 931**Parameters** 932 933| Name | Type | Mandatory | Description | 934| ----- | ------ | ---- | --------------------- | 935| value | number | Yes | Start day of a week. The value **1** indicates Sunday, and the value **7** indicates Saturday.| 936 937**Example** 938 ```ts 939 let calendar: i18n.Calendar = i18n.getCalendar('zh-Hans'); 940 calendar.setFirstDayOfWeek(3); 941 let firstDayOfWeek: number = calendar.getFirstDayOfWeek(); // firstDayOfWeek = 3 942 ``` 943 944### getMinimalDaysInFirstWeek<sup>8+</sup> 945 946getMinimalDaysInFirstWeek(): number 947 948Obtains the minimum number of days in the first week of a year. 949 950**Atomic service API**: This API can be used in atomic services since API version 12. 951 952**System capability**: SystemCapability.Global.I18n 953 954**Return value** 955 956| Type | Description | 957| ------ | ------------ | 958| number | Minimum number of days in the first week of a year.| 959 960**Example** 961 ```ts 962 let calendar: i18n.Calendar = i18n.getCalendar('zh-Hans'); 963 let minimalDaysInFirstWeek: number = calendar.getMinimalDaysInFirstWeek(); // minimalDaysInFirstWeek = 1 964 ``` 965 966 967### setMinimalDaysInFirstWeek<sup>8+</sup> 968 969setMinimalDaysInFirstWeek(value: number): void 970 971Sets the minimum number of days in the first week of a year. 972 973**Atomic service API**: This API can be used in atomic services since API version 12. 974 975**System capability**: SystemCapability.Global.I18n 976 977**Parameters** 978 979| Name | Type | Mandatory | Description | 980| ----- | ------ | ---- | ------------ | 981| value | number | Yes | Minimum number of days in the first week of a year.| 982 983**Example** 984 ```ts 985 let calendar: i18n.Calendar = i18n.getCalendar('zh-Hans'); 986 calendar.setMinimalDaysInFirstWeek(3); 987 let minimalDaysInFirstWeek: number = calendar.getMinimalDaysInFirstWeek(); // minimalDaysInFirstWeek = 3 988 ``` 989 990 991### get<sup>8+</sup> 992 993get(field: string): number 994 995Obtains the value of the associated field in a **Calendar** object. 996 997**Atomic service API**: This API can be used in atomic services since API version 12. 998 999**System capability**: SystemCapability.Global.I18n 1000 1001**Parameters** 1002 1003| Name | Type | Mandatory | Description | 1004| ----- | ------ | ---- | ---------------------------------------- | 1005| field | string | Yes | Associated field in a **Calendar** object. The following table lists the supported field values.| 1006 1007 1008| Field | Description | 1009| ----- | ---------------------------------------- | 1010| era | Era, for example, AD or BC.| 1011| year | Year.| 1012| month | Month. Note: The month starts from **0**. For example, **0** indicates January.| 1013| date | Date.| 1014| hour | Wall-clock hour.| 1015| hour_of_day | Hour of day.| 1016| minute | Minute.| 1017| second | Second.| 1018| millisecond | Millisecond.| 1019| week_of_year | Week of year. Note that the algorithm for calculating the first week of a year varies according to regions. For example, the first seven days in a year are the first week.| 1020| year_woy | Year used with the week of year field. | 1021| week_of_month | Week of month.| 1022| day_of_week_in_month | Day of week in month.| 1023| day_of_year | Day of year.| 1024| day_of_week | Day of week.| 1025| milliseconds_in_day | Milliseconds in day.| 1026| zone_offset | Fixed time zone offset in milliseconds (excluding DST).| 1027| dst_offset | DST offset in milliseconds.| 1028| dow_local | Localized day of week.| 1029| extended_year | Extended year, which can be a negative number.| 1030| julian_day | Julian day.| 1031| is_leap_month | Whether a month is a leap month.| 1032 1033**Return value** 1034 1035| Type | Description | 1036| ------ | ---------------------------------------- | 1037| number | Value of the specified field. For example, if the year in the internal date of this **Calendar** object is **1990**, the **get('year')** function will return **1990**.| 1038 1039**Example** 1040 ```ts 1041 let calendar: i18n.Calendar = i18n.getCalendar('zh-Hans'); 1042 calendar.set(2021, 10, 1, 8, 0, 0); // Set the date and time to 2021.11.1 08:00:00. 1043 let hourOfDay: number = calendar.get('hour_of_day'); // hourOfDay = 8 1044 ``` 1045 1046 1047### getDisplayName<sup>8+</sup> 1048 1049getDisplayName(locale: string): string 1050 1051Obtains the displayed name of the **Calendar** object for the specified locale. 1052 1053**Atomic service API**: This API can be used in atomic services since API version 12. 1054 1055**System capability**: SystemCapability.Global.I18n 1056 1057**Parameters** 1058 1059| Name | Type | Mandatory | Description | 1060| ------ | ------ | ---- | ---------------------------------------- | 1061| locale | string | Yes | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region.| 1062 1063**Return value** 1064 1065| Type | Description | 1066| ------ | ------------------- | 1067| string | Name of the **Calendar** object displayed for the specified locale. For example, **buddhist** is displayed as **Buddhist Calendar** if the locale is **en-US**.| 1068 1069**Example** 1070 ```ts 1071 let calendar: i18n.Calendar = i18n.getCalendar('en-US', 'buddhist'); 1072 let calendarName: string = calendar.getDisplayName('zh'); // calendarName = 'Buddhist' 1073 ``` 1074 1075 1076### isWeekend<sup>8+</sup> 1077 1078isWeekend(date?: Date): boolean 1079 1080Checks whether a given date is a weekend in the calendar. 1081 1082**Atomic service API**: This API can be used in atomic services since API version 12. 1083 1084**System capability**: SystemCapability.Global.I18n 1085 1086**Parameters** 1087 1088| Name | Type | Mandatory | Description | 1089| ---- | ---- | ---- | ---------------------------------------- | 1090| date | Date | No | Date and time. Note: The month starts from **0**. For example, **0** indicates January.<br>The default value is the system date. If this parameter is left empty, the system checks whether the current date is a weekend.| 1091 1092**Return value** 1093 1094| Type | Description | 1095| ------- | ----------------------------------- | 1096| boolean | The value **true** indicates that the specified date is a weekend, and the value **false** indicates the opposite.| 1097 1098**Example** 1099 ```ts 1100 let calendar: i18n.Calendar = i18n.getCalendar('zh-Hans'); 1101 calendar.set(2021, 11, 11, 8, 0, 0); // Set the time to 2021.12.11 08:00:00. 1102 let isWeekend: boolean = calendar.isWeekend(); // isWeekend = true 1103 let date: Date = new Date(2011, 11, 6, 9, 0, 0); // The date and time is 2011-12-06 09:00:00. 1104 isWeekend = calendar.isWeekend(date); // isWeekend = false 1105 ``` 1106 1107 1108### add<sup>11+</sup> 1109 1110add(field: string, amount: number): void 1111 1112Adds or subtracts some fields in a **Calendar** object. 1113 1114**Atomic service API**: This API can be used in atomic services since API version 12. 1115 1116**System capability**: SystemCapability.Global.I18n 1117 1118**Parameters** 1119 1120| Name | Type | Mandatory | Description | 1121| ---- | ---- | ---- | ---------------------------------------- | 1122| field | string | Yes | Specified field in the **Calendar** object. The value can be any of the following: **year**, **month**, **week_of_year**, **week_of_month**, **date**, **day_of_year**, **day_of_week**, **day_of_week_in_month**, **hour**, **hour_of_day**, **minute**, **second**, **millisecond**.<br>For details about the values, see [get](#get8).| 1123| amount | number | Yes | Addition or subtraction amount.| 1124 1125**Error codes** 1126 1127For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 1128 1129| ID | Error Message | 1130| ------ | ---------------------- | 1131| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1132| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 1133 1134**Example** 1135 ```ts 1136 import { BusinessError } from '@kit.BasicServicesKit'; 1137 1138 try { 1139 let calendar: i18n.Calendar = i18n.getCalendar('zh-Hans'); 1140 calendar.set(2021, 11, 11, 8, 0, 0); // Set the date and time to 2021.12.11 08:00:00. 1141 calendar.add('year', 8); // 2021 + 8 1142 let year: number = calendar.get('year'); // year = 2029 1143 } catch (error) { 1144 let err: BusinessError = error as BusinessError; 1145 console.error(`call Calendar.add failed, error code: ${err.code}, message: ${err.message}.`); 1146 } 1147 ``` 1148 1149 1150### getTimeInMillis<sup>11+</sup> 1151 1152getTimeInMillis(): number 1153 1154Obtains number of milliseconds that have elapsed since the Unix epoch in the current **Calendar** object. 1155 1156**Atomic service API**: This API can be used in atomic services since API version 12. 1157 1158**System capability**: SystemCapability.Global.I18n 1159 1160**Return value** 1161 1162| Type | Description | 1163| ------- | ----------------------------------- | 1164| number | Number of milliseconds that have elapsed since the Unix epoch.| 1165 1166**Example** 1167 ```ts 1168 let calendar: i18n.Calendar = i18n.getCalendar('zh-Hans'); 1169 calendar.setTime(5000); 1170 let millisecond: number = calendar.getTimeInMillis(); // millisecond = 5000 1171 ``` 1172 1173 1174### compareDays<sup>11+</sup> 1175 1176compareDays(date: Date): number 1177 1178Compares the **Calendar** object and the specified date for the difference in the number of days. 1179 1180**Atomic service API**: This API can be used in atomic services since API version 12. 1181 1182**System capability**: SystemCapability.Global.I18n 1183 1184**Parameters** 1185 1186| Name | Type | Mandatory | Description | 1187| ---- | ---- | ---- | ---------------------------------------- | 1188| date | Date | Yes | Date and time. Note: The month starts from **0**. For example, **0** indicates January.| 1189 1190**Return value** 1191 1192| Type | Description | 1193| ------- | ----------------------------------- | 1194| number | Difference in the number of days between the calendar date and the specified date. A positive number indicates that the calendar date is earlier, and a negative number indicates the opposite.<br>The value is accurate to milliseconds. If the value is less than one day, it is considered as one day.| 1195 1196**Error codes** 1197 1198For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 1199 1200| ID | Error Message | 1201| ------ | ---------------------- | 1202| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1203 1204**Example** 1205 ```ts 1206 import { BusinessError } from '@kit.BasicServicesKit'; 1207 1208 try { 1209 let calendar: i18n.Calendar = i18n.getCalendar('zh-Hans'); 1210 calendar.setTime(5000); 1211 let date: Date = new Date(6000); 1212 let diff: number = calendar.compareDays(date); // diff = 1 1213 } catch (error) { 1214 let err: BusinessError = error as BusinessError; 1215 console.error(`call Calendar.compareDays failed, error code: ${err.code}, message: ${err.message}.`); 1216 } 1217 ``` 1218 1219## PhoneNumberFormat<sup>8+</sup> 1220 1221 1222### constructor<sup>8+</sup> 1223 1224constructor(country: string, options?: PhoneNumberFormatOptions) 1225 1226Creates a **PhoneNumberFormat** object. 1227 1228**Atomic service API**: This API can be used in atomic services since API version 12. 1229 1230**System capability**: SystemCapability.Global.I18n 1231 1232**Parameters** 1233 1234| Name | Type | Mandatory | Description | 1235| ------- | ---------------------------------------- | ---- | ---------------- | 1236| country | string | Yes | Country or region to which the phone number to be formatted belongs.| 1237| options | [PhoneNumberFormatOptions](#phonenumberformatoptions8) | No | Options for **PhoneNumberFormat** object initialization. The default value is **NATIONAL**. | 1238 1239**Example** 1240 ```ts 1241 let option: i18n.PhoneNumberFormatOptions = { type: 'E164' }; 1242 let phoneNumberFormat: i18n.PhoneNumberFormat = new i18n.PhoneNumberFormat('CN', option); 1243 ``` 1244 1245### isValidNumber<sup>8+</sup> 1246 1247isValidNumber(number: string): boolean 1248 1249Checks whether the format of the specified phone number is valid. 1250 1251**Atomic service API**: This API can be used in atomic services since API version 12. 1252 1253**System capability**: SystemCapability.Global.I18n 1254 1255**Parameters** 1256 1257| Name | Type | Mandatory | Description | 1258| ------ | ------ | ---- | --------- | 1259| number | string | Yes | Phone number to be checked.| 1260 1261**Return value** 1262 1263| Type | Description | 1264| ------- | ------------------------------------- | 1265| boolean | **true** if the phone number format is valid, and **false** otherwise.| 1266 1267**Example** 1268 ```ts 1269 let phonenumberfmt: i18n.PhoneNumberFormat = new i18n.PhoneNumberFormat('CN'); 1270 let isValidNumber: boolean = phonenumberfmt.isValidNumber('158****2312'); // isValidNumber = true 1271 ``` 1272 1273 1274### format<sup>8+</sup> 1275 1276format(number: string): string 1277 1278Formats a phone number. 1279 1280> **Description** 1281> Formatting dialed phone numbers is supported since API version 12. 1282 1283**Atomic service API**: This API can be used in atomic services since API version 12. 1284 1285**System capability**: SystemCapability.Global.I18n 1286 1287**Parameters** 1288 1289| Name | Type | Mandatory | Description | 1290| ------ | ------ | ---- | ---------- | 1291| number | string | Yes | Phone number to be formatted.| 1292 1293**Return value** 1294 1295| Type | Description | 1296| ------ | ---------- | 1297| string | Formatted phone number.| 1298 1299**Example** 1300 ```ts 1301 let phonenumberfmt: i18n.PhoneNumberFormat = new i18n.PhoneNumberFormat('CN'); 1302 // formattedPhoneNumber = '158 **** 2312' 1303 let formattedPhoneNumber: string = phonenumberfmt.format('158****2312'); 1304 1305 // Format the dialed phone number. 1306 let option: i18n.PhoneNumberFormatOptions = { type: 'TYPING' }; 1307 let phoneNumberFmt: i18n.PhoneNumberFormat = new i18n.PhoneNumberFormat('CN', option); 1308 let phoneNumber: string = '130493'; 1309 let formatResult: string = ''; 1310 for (let i = 0; i < phoneNumber.length; i++) { 1311 formatResult += phoneNumber.charAt(i); 1312 formatResult = phoneNumberFmt.format(formatResult); // formatResult = '130 493' 1313 } 1314 ``` 1315 1316### getLocationName<sup>9+</sup> 1317 1318getLocationName(number: string, locale: string): string 1319 1320Obtains the home location of a phone number. 1321 1322**Atomic service API**: This API can be used in atomic services since API version 12. 1323 1324**System capability**: SystemCapability.Global.I18n 1325 1326**Parameters** 1327 1328| Name | Type | Mandatory | Description | 1329| ------ | ------ | ---- | ---- | 1330| number | string | Yes | Phone number. To obtain the home location of a number in other countries/regions, you need to prefix the number with **00** and the country code.| 1331| locale | string | Yes | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region.| 1332 1333**Return value** 1334 1335| Type | Description | 1336| ------ | -------- | 1337| string | Home location of the phone number.| 1338 1339**Example** 1340 ```ts 1341 let phonenumberfmt: i18n.PhoneNumberFormat = new i18n.PhoneNumberFormat('CN'); 1342 let locationName: string = phonenumberfmt.getLocationName('158****2345', 'zh-CN'); // locationName = 'Zhanjiang, Guangdong Province' 1343 let locName: string = phonenumberfmt.getLocationName('0039312****789', 'zh-CN'); // locName = 'Italy' 1344 ``` 1345 1346 1347## PhoneNumberFormatOptions<sup>8+</sup> 1348 1349Options for **PhoneNumberFormat** object initialization. 1350 1351**Atomic service API**: This API can be used in atomic services since API version 12. 1352 1353**System capability**: SystemCapability.Global.I18n 1354 1355| Name | Type | Readable | Writable | Description | 1356| ---- | ------ | ---- | ---- | ---------------------------------------- | 1357| type | string | Yes | Yes | Type of the phone number. The value can be **E164**, **INTERNATIONAL**, **NATIONAL**, **RFC3966**, or **TYPING**.<br>- In API version 8, **type** is mandatory.<br>- In API version 9 or later, **type** is optional.<br>- **TYPING** is supported since API version 12.| 1358 1359 1360## UnitInfo<sup>8+</sup> 1361 1362Defines the measurement unit information. 1363 1364**Atomic service API**: This API can be used in atomic services since API version 12. 1365 1366**System capability**: SystemCapability.Global.I18n 1367 1368| Name | Type | Readable | Writable | Description | 1369| ------------- | ------ | ---- | ---- | ---------------------------------------- | 1370| unit | string | Yes | Yes | Name of the measurement unit, for example, **meter**, **inch**, or **cup**.| 1371| measureSystem | string | Yes | Yes | Measurement system. The value can be **SI**, **US**, or **UK**.| 1372 1373 1374## i18n.getInstance<sup>8+</sup> 1375 1376getInstance(locale?: string): IndexUtil 1377 1378Creates an **IndexUtil** object. 1379 1380**Atomic service API**: This API can be used in atomic services since API version 12. 1381 1382**System capability**: SystemCapability.Global.I18n 1383 1384**Parameters** 1385 1386| Name | Type | Mandatory | Description | 1387| ------ | ------ | ---- | ---------------------------- | 1388| locale | string | No | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region.<br>The default value is the system locale.| 1389 1390**Return value** 1391 1392| Type | Description | 1393| ------------------------ | --------------------- | 1394| [IndexUtil](#indexutil8) | **IndexUtil** object mapping to the **locale** object.| 1395 1396**Example** 1397 ```ts 1398 let indexUtil: i18n.IndexUtil = i18n.getInstance('zh-CN'); 1399 ``` 1400 1401 1402## IndexUtil<sup>8+</sup> 1403 1404**Atomic service API**: This API can be used in atomic services since API version 12. 1405 1406### getIndexList<sup>8+</sup> 1407 1408getIndexList(): Array<string> 1409 1410Obtains the index list of the current locale. 1411 1412**Atomic service API**: This API can be used in atomic services since API version 12. 1413 1414**System capability**: SystemCapability.Global.I18n 1415 1416**Return value** 1417 1418| Type | Description | 1419| ------------------- | ------------------ | 1420| Array<string> | Index list of the current locale.| 1421 1422**Example** 1423 ```ts 1424 let indexUtil: i18n.IndexUtil = i18n.getInstance('zh-CN'); 1425 // indexList = [ '...', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 1426 // 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', '...' ] 1427 let indexList: Array<string> = indexUtil.getIndexList(); 1428 ``` 1429 1430 1431### addLocale<sup>8+</sup> 1432 1433addLocale(locale: string): void 1434 1435Adds the index list of a new locale to the index list of the current locale to form a composite list. 1436 1437**Atomic service API**: This API can be used in atomic services since API version 12. 1438 1439**System capability**: SystemCapability.Global.I18n 1440 1441**Parameters** 1442 1443| Name | Type | Mandatory | Description | 1444| ------ | ------ | ---- | ---------------------------- | 1445| locale | string | Yes | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region.| 1446 1447**Example** 1448 ```ts 1449 let indexUtil: i18n.IndexUtil = i18n.getInstance('zh-CN'); 1450 indexUtil.addLocale('en-US'); 1451 ``` 1452 1453### getIndex<sup>8+</sup> 1454 1455getIndex(text: string): string 1456 1457Obtains the index of a **text** object. 1458 1459**Atomic service API**: This API can be used in atomic services since API version 12. 1460 1461**System capability**: SystemCapability.Global.I18n 1462 1463**Parameters** 1464 1465| Name | Type | Mandatory | Description | 1466| ---- | ------ | ---- | ------------ | 1467| text | string | Yes | **text** object whose index is to be obtained.| 1468 1469**Return value** 1470 1471| Type | Description | 1472| ------ | ----------- | 1473| string | Index of the **text** object.| 1474 1475**Example** 1476 ```ts 1477 let indexUtil: i18n.IndexUtil = i18n.getInstance('zh-CN'); 1478 let index: string = indexUtil.getIndex('hi'); // index = 'H' 1479 ``` 1480 1481 1482## i18n.getLineInstance<sup>8+</sup> 1483 1484getLineInstance(locale: string): BreakIterator 1485 1486Obtains a [BreakIterator](#breakiterator8) object for text segmentation. 1487 1488**Atomic service API**: This API can be used in atomic services since API version 12. 1489 1490**System capability**: SystemCapability.Global.I18n 1491 1492**Parameters** 1493 1494| Name | Type | Mandatory | Description | 1495| ------ | ------ | ---- | ---------------------------------------- | 1496| locale | string | Yes | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region.<br>The [BreakIterator](#breakiterator8) object segments text according to the rules of the specified locale.| 1497 1498**Return value** 1499 1500| Type | Description | 1501| -------------------------------- | ----------- | 1502| [BreakIterator](#breakiterator8) | Break iterator used for text segmentation.| 1503 1504**Example** 1505 ```ts 1506 let iterator: i18n.BreakIterator = i18n.getLineInstance('en'); 1507 ``` 1508 1509 1510## BreakIterator<sup>8+</sup> 1511 1512 1513### setLineBreakText<sup>8+</sup> 1514 1515setLineBreakText(text: string): void 1516 1517Sets the text to be processed by the **BreakIterator** object. 1518 1519**Atomic service API**: This API can be used in atomic services since API version 12. 1520 1521**System capability**: SystemCapability.Global.I18n 1522 1523**Parameters** 1524 1525| Name | Type | Mandatory | Description | 1526| ---- | ------ | ---- | ----------------------- | 1527| text | string | Yes | Text to be processed by the **BreakIterator** object.| 1528 1529**Example** 1530 ```ts 1531 let iterator: i18n.BreakIterator = i18n.getLineInstance('en'); 1532 iterator.setLineBreakText('Apple is my favorite fruit.'); // Set a short sentence as the text to be processed by the BreakIterator object. 1533 ``` 1534 1535 1536### getLineBreakText<sup>8+</sup> 1537 1538getLineBreakText(): string 1539 1540Obtains the text being processed by the **BreakIterator** object. 1541 1542**Atomic service API**: This API can be used in atomic services since API version 12. 1543 1544**System capability**: SystemCapability.Global.I18n 1545 1546**Return value** 1547 1548| Type | Description | 1549| ------ | ---------------------- | 1550| string | Text being processed by the **BreakIterator** object.| 1551 1552**Example** 1553 ```ts 1554 let iterator: i18n.BreakIterator = i18n.getLineInstance('en'); 1555 iterator.setLineBreakText('Apple is my favorite fruit.'); 1556 let breakText: string = iterator.getLineBreakText(); // breakText = 'Apple is my favorite fruit.' 1557 ``` 1558 1559 1560### current<sup>8+</sup> 1561 1562current(): number 1563 1564Obtains the position of a **BreakIterator** object in the processed text. 1565 1566**Atomic service API**: This API can be used in atomic services since API version 12. 1567 1568**System capability**: SystemCapability.Global.I18n 1569 1570**Return value** 1571 1572| Type | Description | 1573| ------ | --------------------------- | 1574| number | Position of the **BreakIterator** object in the text being processed.| 1575 1576**Example** 1577 ```ts 1578 let iterator: i18n.BreakIterator = i18n.getLineInstance('en'); 1579 iterator.setLineBreakText('Apple is my favorite fruit.'); 1580 let currentPos: number = iterator.current(); // currentPos = 0 1581 ``` 1582 1583 1584### first<sup>8+</sup> 1585 1586first(): number 1587 1588Moves a **BreakIterator** object to the first break point, which is always at the beginning of the processed text. 1589 1590**Atomic service API**: This API can be used in atomic services since API version 12. 1591 1592**System capability**: SystemCapability.Global.I18n 1593 1594**Return value** 1595 1596| Type | Description | 1597| ------ | ----------------- | 1598| number | Offset to the first break point of the processed text.| 1599 1600**Example** 1601 ```ts 1602 let iterator: i18n.BreakIterator = i18n.getLineInstance('en'); 1603 iterator.setLineBreakText('Apple is my favorite fruit.'); 1604 let firstPos: number = iterator.first(); // firstPos = 0 1605 ``` 1606 1607 1608### last<sup>8+</sup> 1609 1610last(): number 1611 1612Moves a **BreakIterator** object to the last break point, which is always the next position after the end of the processed text. 1613 1614**Atomic service API**: This API can be used in atomic services since API version 12. 1615 1616**System capability**: SystemCapability.Global.I18n 1617 1618**Return value** 1619 1620| Type | Description | 1621| ------ | ------------------ | 1622| number | Offset to the last break point of the processed text.| 1623 1624**Example** 1625 ```ts 1626 let iterator: i18n.BreakIterator = i18n.getLineInstance('en'); 1627 iterator.setLineBreakText('Apple is my favorite fruit.'); 1628 let lastPos: number = iterator.last(); // lastPos = 27 1629 ``` 1630 1631 1632### next<sup>8+</sup> 1633 1634next(index?: number): number 1635 1636Moves the **BreakIterator** object backward by the corresponding number of break points. 1637 1638**Atomic service API**: This API can be used in atomic services since API version 12. 1639 1640**System capability**: SystemCapability.Global.I18n 1641 1642**Parameters** 1643 1644| Name | Type | Mandatory | Description | 1645| ----- | ------ | ---- | ---------------------------------------- | 1646| index | number | No | Number of break points to be moved by the **BreakIterator** object.<br>A positive value indicates that the break point is moved backward by the specified number of break points, and a negative value indicates the opposite.<br>The default value is **1**.| 1647 1648**Return value** 1649 1650| Type | Description | 1651| ------ | ---------------------------------------- | 1652| number | Position of the **BreakIterator** object in the text after it is moved by the specified number of break points.<br>The value **-1** is returned if the position of the **BreakIterator** object is outside of the processed text after movement.| 1653 1654**Example** 1655 ```ts 1656 let iterator: i18n.BreakIterator = i18n.getLineInstance('en'); 1657 iterator.setLineBreakText('Apple is my favorite fruit.'); 1658 let pos: number = iterator.first(); // pos = 0 1659 pos = iterator.next(); // pos = 6 1660 pos = iterator.next(10); // pos = -1 1661 ``` 1662 1663 1664### previous<sup>8+</sup> 1665 1666previous(): number 1667 1668Moves the **BreakIterator** object forward by one break point. 1669 1670**Atomic service API**: This API can be used in atomic services since API version 12. 1671 1672**System capability**: SystemCapability.Global.I18n 1673 1674**Return value** 1675 1676| Type | Description | 1677| ------ | ---------------------------------------- | 1678| number | Position of the **BreakIterator** object in the text after it is moved to the previous break point.<br>The value **-1** is returned if the position of the **BreakIterator** object is outside of the processed text after movement.| 1679 1680**Example** 1681 ```ts 1682 let iterator: i18n.BreakIterator = i18n.getLineInstance('en'); 1683 iterator.setLineBreakText('Apple is my favorite fruit.'); 1684 let pos: number = iterator.first(); // pos = 0 1685 pos = iterator.next(3); // pos = 12 1686 pos = iterator.previous(); // pos = 9 1687 ``` 1688 1689 1690### following<sup>8+</sup> 1691 1692following(offset: number): number 1693 1694Moves a **BreakIterator** object to the break point following the specified position. 1695 1696**Atomic service API**: This API can be used in atomic services since API version 12. 1697 1698**System capability**: SystemCapability.Global.I18n 1699 1700**Parameters** 1701 1702| Name | Type | Mandatory | Description | 1703| ------ | ------ | ---- | ---------------------------------------- | 1704| offset | number | Yes | Offset to the break point following the specified position.| 1705 1706**Return value** 1707 1708| Type | Description | 1709| ------ | ---------------------------------------- | 1710| number | Position of the **BreakIterator** object after movement. The value **-1** is returned if the position of the **BreakIterator** object is outside of the processed text after movement.| 1711 1712**Example** 1713 ```ts 1714 let iterator: i18n.BreakIterator = i18n.getLineInstance('en'); 1715 iterator.setLineBreakText('Apple is my favorite fruit.'); 1716 let pos: number = iterator.following(0); // pos = 6 1717 pos = iterator.following(100); // pos = -1 1718 pos = iterator.current(); // pos = 27 1719 ``` 1720 1721 1722### isBoundary<sup>8+</sup> 1723 1724isBoundary(offset: number): boolean 1725 1726Checks whether the specified position is a break point. 1727 1728**Atomic service API**: This API can be used in atomic services since API version 12. 1729 1730**System capability**: SystemCapability.Global.I18n 1731 1732**Parameters** 1733 1734| Name | Type | Mandatory | Description | 1735| ------ | ------ | ---- | ----------- | 1736| offset | number | Yes | Specified position.| 1737 1738**Return value** 1739 1740| Type | Description | 1741| ------- | ------------------------------- | 1742| boolean | **true** if the text position specified by offset is a split point, and **false** otherwise.<br>If **true** is returned, the **BreakIterator** object is moved to the position specified by **offset**. Otherwise, **following** is called.| 1743 1744**Example** 1745 ```ts 1746 let iterator: i18n.BreakIterator = i18n.getLineInstance('en'); 1747 iterator.setLineBreakText('Apple is my favorite fruit.'); 1748 let isBoundary: boolean = iterator.isBoundary(0); // isBoundary = true; 1749 isBoundary = iterator.isBoundary(5); // isBoundary = false; 1750 ``` 1751 1752 1753## i18n.getTimeZone 1754 1755getTimeZone(zoneID?: string): TimeZone 1756 1757Obtains the **TimeZone** object corresponding to the specified time zone ID. 1758 1759**Atomic service API**: This API can be used in atomic services since API version 12. 1760 1761**System capability**: SystemCapability.Global.I18n 1762 1763**Parameters** 1764 1765| Name | Type | Mandatory | Description | 1766| ------ | ------ | ---- | ----- | 1767| zoneID | string | No | Time zone ID. The default value is the system time zone.| 1768 1769**Return value** 1770 1771| Type | Description | 1772| -------- | ------------ | 1773| [TimeZone](#timezone) | **TimeZone** object corresponding to the time zone ID.| 1774 1775**Example** 1776 ```ts 1777 let timezone: i18n.TimeZone = i18n.getTimeZone('Asia/Shanghai'); 1778 ``` 1779 1780## TimeZone 1781 1782### getID 1783 1784getID(): string 1785 1786Obtains the ID of the specified **TimeZone** object. 1787 1788**Atomic service API**: This API can be used in atomic services since API version 12. 1789 1790**System capability**: SystemCapability.Global.I18n 1791 1792**Return value** 1793 1794| Type | Description | 1795| ------ | ------------ | 1796| string | Time zone ID corresponding to the **TimeZone** object.| 1797 1798**Example** 1799 ```ts 1800 let timezone: i18n.TimeZone = i18n.getTimeZone('Asia/Shanghai'); 1801 let timezoneID: string = timezone.getID(); // timezoneID = 'Asia/Shanghai' 1802 ``` 1803 1804 1805### getDisplayName 1806 1807getDisplayName(locale?: string, isDST?: boolean): string 1808 1809Obtains the localized representation of a **TimeZone** object. 1810 1811**Atomic service API**: This API can be used in atomic services since API version 12. 1812 1813**System capability**: SystemCapability.Global.I18n 1814 1815**Parameters** 1816 1817| Name | Type | Mandatory | Description | 1818| ------ | ------- | ---- | -------------------- | 1819| locale | string | No | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region. The default value is the system locale. | 1820| isDST | boolean | No | **true** if DST is considered in the localized representation of the **TimeZone** object, and **false** otherwise. The default value is **false**.| 1821 1822**Return value** 1823 1824| Type | Description | 1825| ------ | ------------- | 1826| string | Localized display of the **TimeZone** object in the specified locale.| 1827 1828**Example** 1829 ```ts 1830 let timezone: i18n.TimeZone = i18n.getTimeZone('Asia/Shanghai'); 1831 let timezoneName: string = timezone.getDisplayName('zh-CN', false); // timezoneName = 'China Standard Time' 1832 ``` 1833 1834 1835### getRawOffset 1836 1837getRawOffset(): number 1838 1839Obtains the offset between the time zone represented by a **TimeZone** object and the UTC time zone. 1840 1841**Atomic service API**: This API can be used in atomic services since API version 12. 1842 1843**System capability**: SystemCapability.Global.I18n 1844 1845**Return value** 1846 1847| Type | Description | 1848| ------ | ------------------- | 1849| number | Offset between the time zone represented by a **TimeZone** object and the UTC time zone, in milliseconds.| 1850 1851**Example** 1852 ```ts 1853 let timezone: i18n.TimeZone = i18n.getTimeZone('Asia/Shanghai'); 1854 let offset: number = timezone.getRawOffset(); // offset = 28800000 1855 ``` 1856 1857 1858### getOffset 1859 1860getOffset(date?: number): number 1861 1862Obtains the offset between the time zone represented by a **TimeZone** object and the UTC time zone at a certain time. 1863 1864**Atomic service API**: This API can be used in atomic services since API version 12. 1865 1866**System capability**: SystemCapability.Global.I18n 1867 1868**Parameters** 1869 1870| Name | Type | Mandatory | Description | 1871| ------ | ------ | ---- | ------ | 1872| date | number | No | Time for calculating the offset, in milliseconds. The default value is the system time.| 1873 1874**Return value** 1875 1876| Type | Description | 1877| ------ | ----------------------- | 1878| number | Offset between the time zone represented by the **TimeZone** object and the UTC time zone at a certain time.| 1879 1880**Example** 1881 ```ts 1882 let timezone: i18n.TimeZone = i18n.getTimeZone('Asia/Shanghai'); 1883 let offset: number = timezone.getOffset(1234567890); // offset = 28800000 1884 ``` 1885 1886 1887### getAvailableIDs<sup>9+</sup> 1888 1889static getAvailableIDs(): Array<string> 1890 1891Obtains the list of time zone IDs supported by the system. 1892 1893**Atomic service API**: This API can be used in atomic services since API version 12. 1894 1895**System capability**: SystemCapability.Global.I18n 1896 1897**Return value** 1898 1899| Type | Description | 1900| ------------------- | ----------- | 1901| Array<string> | List of time zone IDs supported by the system.| 1902 1903**Example** 1904 ```ts 1905 // ids = ['America/Adak', 'America/Anchorage', 'America/Bogota', 'America/Denver', 'America/Los_Angeles', 'America/Montevideo', 'America/Santiago', 'America/Sao_Paulo', 'Asia/Ashgabat', 'Asia/Hovd', 'Asia/Jerusalem', 'Asia/Magadan', 'Asia/Omsk', 'Asia/Shanghai', 'Asia/Tokyo', 'Asia/Yerevan', 'Atlantic/Cape_Verde', 'Australia/Lord_Howe', 'Europe/Dublin', 'Europe/London', 'Europe/Moscow', 'Pacific/Auckland', 'Pacific/Easter', 'Pacific/Pago-Pago'] 1906 let ids: Array<string> = i18n.TimeZone.getAvailableIDs(); 1907 ``` 1908 1909 1910### getAvailableZoneCityIDs<sup>9+</sup> 1911 1912static getAvailableZoneCityIDs(): Array<string> 1913 1914Obtains the list of time zone city IDs supported by the system. 1915 1916**Atomic service API**: This API can be used in atomic services since API version 12. 1917 1918**System capability**: SystemCapability.Global.I18n 1919 1920**Return value** 1921 1922| Type | Description | 1923| ------------------- | ------------- | 1924| Array<string> | List of time zone city IDs supported by the system.| 1925 1926**Example** 1927 ```ts 1928 // cityIDs = ['Auckland', 'Magadan', 'Lord Howe Island', 'Tokyo', 'Shanghai', 'Hovd', 'Omsk', 'Ashgabat', 'Yerevan', 'Moscow', 'Tel Aviv', 'Dublin', 'London', 'Praia', 'Montevideo', 'Brasília', 'Santiago', 'Bogotá', 'Easter Island', 'Salt Lake City', 'Los Angeles', 'Anchorage', 'Adak', 'Pago Pago'] 1929 let cityIDs: Array<string> = i18n.TimeZone.getAvailableZoneCityIDs(); 1930 ``` 1931 1932### getCityDisplayName<sup>9+</sup> 1933 1934static getCityDisplayName(cityID: string, locale: string): string 1935 1936Obtains the localized representation of a time zone city in the specified locale. 1937 1938**Atomic service API**: This API can be used in atomic services since API version 12. 1939 1940**System capability**: SystemCapability.Global.I18n 1941 1942**Parameters** 1943 1944| Name | Type | Mandatory | Description | 1945| ------ | ------ | ---- | ------ | 1946| cityID | string | Yes | Time zone city ID.| 1947| locale | string | Yes | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region. | 1948 1949**Return value** 1950 1951| Type | Description | 1952| ------ | ------------------ | 1953| string | Localized display of the time zone city in the specified locale.| 1954 1955**Example** 1956 ```ts 1957 let displayName: string = i18n.TimeZone.getCityDisplayName('Shanghai', 'zh-CN'); // displayName = 'Shanghai (China)' 1958 ``` 1959 1960 1961### getTimezoneFromCity<sup>9+</sup> 1962 1963static getTimezoneFromCity(cityID: string): TimeZone 1964 1965Obtains the **TimeZone** object corresponding to the specified time zone city ID. 1966 1967**Atomic service API**: This API can be used in atomic services since API version 12. 1968 1969**System capability**: SystemCapability.Global.I18n 1970 1971**Parameters** 1972 1973| Name | Type | Mandatory | Description | 1974| ------ | ------ | ---- | ------ | 1975| cityID | string | Yes | Time zone city ID.| 1976 1977**Return value** 1978 1979| Type | Description | 1980| -------- | ----------- | 1981| TimeZone | **TimeZone** object corresponding to the specified time zone city ID.| 1982 1983**Example** 1984 ```ts 1985 let timezone: i18n.TimeZone = i18n.TimeZone.getTimezoneFromCity('Shanghai'); 1986 ``` 1987 1988### getTimezonesByLocation<sup>10+</sup> 1989 1990static getTimezonesByLocation(longitude: number, latitude: number): Array<TimeZone> 1991 1992Creates an array of **TimeZone** objects corresponding to the specified longitude and latitude. 1993 1994**Atomic service API**: This API can be used in atomic services since API version 12. 1995 1996**System capability**: SystemCapability.Global.I18n 1997 1998**Parameters** 1999 2000| Name | Type | Mandatory | Description | 2001| --------- | ------ | ---- | ------ | 2002| longitude | number | Yes | Longitude. The value range is [-180, 179.9). A positive value is used for east longitude and a negative value is used for west longitude.| 2003| latitude | number | Yes | Latitude. The value range is [-90, 89.9). A positive value is used for north latitude and a negative value is used for south latitude.| 2004 2005**Return value** 2006 2007| Type | Description | 2008| -------- | ----------- | 2009| Array<[TimeZone](#timezone)> | **TimeZone** object array.| 2010 2011**Error codes** 2012 2013For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 2014 2015| ID | Error Message | 2016| ------ | ---------------------- | 2017| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2018| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 2019 2020 2021> **Description** 2022> 2023> The error message of 890001 is subject to the actual error. 2024 2025**Example** 2026 ```ts 2027 import { BusinessError } from '@kit.BasicServicesKit'; 2028 2029 try { 2030 let timezoneArray: Array<i18n.TimeZone> = i18n.TimeZone.getTimezonesByLocation(-118.1, 34.0); 2031 } catch (error) { 2032 let err: BusinessError = error as BusinessError; 2033 console.error(`call TimeZone.getTimezonesByLocation failed, error code: ${err.code}, message: ${err.message}.`); 2034 } 2035 ``` 2036 2037 2038## Transliterator<sup>9+</sup> 2039 2040 2041### getAvailableIDs<sup>9+</sup> 2042 2043static getAvailableIDs(): string[] 2044 2045Obtains a list of IDs supported by the **Transliterator** object. 2046 2047**Atomic service API**: This API can be used in atomic services since API version 12. 2048 2049**System capability**: SystemCapability.Global.I18n 2050 2051**Return value** 2052 2053| Type | Description | 2054| -------- | ---------- | 2055| string[] | List of IDs supported by the **Transliterator** object.| 2056 2057**Example** 2058 ```ts 2059 // A total of 742 IDs are supported. One ID is comprised of two parts separated by a hyphen (-) in the format of source-destination. For example, in **ids = ["Han-Latin","Latin-ASCII", "Amharic-Latin/BGN","Accents-Any", ...]**, **Han-Latin** indicates conversion from Chinese to Latin, and **Amharic-Latin** indicates conversion from Amharic to Latin. 2060 // For more information, see ISO-15924. 2061 let ids: string[] = i18n.Transliterator.getAvailableIDs(); 2062 ``` 2063 2064 2065### getInstance<sup>9+</sup> 2066 2067static getInstance(id: string): Transliterator 2068 2069Creates a **Transliterator** object. 2070 2071**Atomic service API**: This API can be used in atomic services since API version 12. 2072 2073**System capability**: SystemCapability.Global.I18n 2074 2075**Parameters** 2076 2077| Name | Type | Mandatory | Description | 2078| ---- | ------ | ---- | -------- | 2079| id | string | Yes | ID supported by the **Transliterator** object.| 2080 2081**Return value** 2082 2083| Type | Description | 2084| ---------------------------------- | ----- | 2085| [Transliterator](#transliterator9) | **Transliterator** object.| 2086 2087**Example** 2088 ```ts 2089 let transliterator: i18n.Transliterator = i18n.Transliterator.getInstance('Any-Latn'); 2090 ``` 2091 2092 2093### transform<sup>9+</sup> 2094 2095transform(text: string): string 2096 2097Converts the input string from the source format to the target format. 2098 2099**Atomic service API**: This API can be used in atomic services since API version 12. 2100 2101**System capability**: SystemCapability.Global.I18n 2102 2103**Parameters** 2104 2105| Name | Type | Mandatory | Description | 2106| ---- | ------ | ---- | ------ | 2107| text | string | Yes | Input string.| 2108 2109**Return value** 2110 2111| Type | Description | 2112| ------ | -------- | 2113| string | Target string.| 2114 2115**Example** 2116 ```ts 2117 let transliterator: i18n.Transliterator = i18n.Transliterator.getInstance('Any-Latn'); 2118 let wordArray = ['China', 'Germany', 'US', 'France"] 2119 for (let i = 0; i < wordArray.length; i++) { 2120 let transliterLatn = 2121 transliterator.transform(wordArray[i]); // transliterLatn: 'zhōng guó', 'dé guó', 'měi guó', 'fǎ guó' 2122 } 2123 2124 // Chinese transliteration and tone removal 2125 let transliter = i18n.Transliterator.getInstance('Any-Latn;Latin-Ascii'); 2126 let transliterAscii = transliter.transform('中国'); // transliterAscii ='zhong guo' 2127 2128 // Chinese surname pronunciation 2129 let nameTransliter = i18n.Transliterator.getInstance('Han-Latin/Names'); 2130 let transliterNames = nameTransliter.transform('单老师'); // transliterNames = 'shàn lǎo shī' 2131 transliterNames = nameTransliter.transform('长孙无忌'); // transliterNames = 'zhǎng sūn wú jì' 2132 ``` 2133 2134 2135## Unicode<sup>9+</sup> 2136 2137**Atomic service API**: This API can be used in atomic services since API version 12. 2138 2139### isDigit<sup>9+</sup> 2140 2141static isDigit(char: string): boolean 2142 2143Checks whether the input string is composed of digits. 2144 2145**Atomic service API**: This API can be used in atomic services since API version 12. 2146 2147**System capability**: SystemCapability.Global.I18n 2148 2149**Parameters** 2150 2151| Name | Type | Mandatory | Description | 2152| ---- | ------ | ---- | ----- | 2153| char | string | Yes | Input string.| 2154 2155**Return value** 2156 2157| Type | Description | 2158| ------- | ------------------------------------ | 2159| boolean | **true** if the input character is a digit, and **false** otherwise.| 2160 2161**Example** 2162 ```ts 2163 let isDigit: boolean = i18n.Unicode.isDigit('1'); // isDigit = true 2164 ``` 2165 2166 2167### isSpaceChar<sup>9+</sup> 2168 2169static isSpaceChar(char: string): boolean 2170 2171Checks whether the input character is a space. 2172 2173**Atomic service API**: This API can be used in atomic services since API version 12. 2174 2175**System capability**: SystemCapability.Global.I18n 2176 2177**Parameters** 2178 2179| Name | Type | Mandatory | Description | 2180| ---- | ------ | ---- | ----- | 2181| char | string | Yes | Input string.| 2182 2183**Return value** 2184 2185| Type | Description | 2186| ------- | -------------------------------------- | 2187| boolean | **true** if the input character is a space, and **false** otherwise.| 2188 2189**Example** 2190 ```ts 2191 let isSpacechar: boolean = i18n.Unicode.isSpaceChar('a'); // isSpacechar = false 2192 ``` 2193 2194 2195### isWhitespace<sup>9+</sup> 2196 2197static isWhitespace(char: string): boolean 2198 2199Checks whether the input character is a white space. 2200 2201**Atomic service API**: This API can be used in atomic services since API version 12. 2202 2203**System capability**: SystemCapability.Global.I18n 2204 2205**Parameters** 2206 2207| Name | Type | Mandatory | Description | 2208| ---- | ------ | ---- | ----- | 2209| char | string | Yes | String obtained.| 2210 2211**Return value** 2212 2213| Type | Description | 2214| ------- | -------------------------------------- | 2215| boolean | **true** if the input character is a white space, and **false** otherwise.| 2216 2217**Example** 2218 ```ts 2219 let isWhitespace: boolean = i18n.Unicode.isWhitespace('a'); // isWhitespace = false 2220 ``` 2221 2222 2223### isRTL<sup>9+</sup> 2224 2225static isRTL(char: string): boolean 2226 2227Checks whether the input character is of the right to left (RTL) language. 2228 2229**Atomic service API**: This API can be used in atomic services since API version 12. 2230 2231**System capability**: SystemCapability.Global.I18n 2232 2233**Parameters** 2234 2235| Name | Type | Mandatory | Description | 2236| ---- | ------ | ---- | ----- | 2237| char | string | Yes | Input character.| 2238 2239**Return value** 2240 2241| Type | Description | 2242| ------- | ---------------------------------------- | 2243| boolean | **true** if the input character is of the RTL language, and **false** otherwise.| 2244 2245**Example** 2246 ```ts 2247 let isRtl: boolean = i18n.Unicode.isRTL('a'); // isRtl = false 2248 ``` 2249 2250 2251### isIdeograph<sup>9+</sup> 2252 2253static isIdeograph(char: string): boolean 2254 2255Checks whether the input character is an ideographic character. 2256 2257**Atomic service API**: This API can be used in atomic services since API version 12. 2258 2259**System capability**: SystemCapability.Global.I18n 2260 2261**Parameters** 2262 2263| Name | Type | Mandatory | Description | 2264| ---- | ------ | ---- | ----- | 2265| char | string | Yes | Input character.| 2266 2267**Return value** 2268 2269| Type | Description | 2270| ------- | ---------------------------------------- | 2271| boolean | **true** if the input character an ideographic character, and **false** otherwise.| 2272 2273**Example** 2274 ```ts 2275 let isIdeograph: boolean = i18n.Unicode.isIdeograph('a'); // isIdeograph = false 2276 ``` 2277 2278 2279### isLetter<sup>9+</sup> 2280 2281static isLetter(char: string): boolean 2282 2283Checks whether the input character is a letter. 2284 2285**Atomic service API**: This API can be used in atomic services since API version 12. 2286 2287**System capability**: SystemCapability.Global.I18n 2288 2289**Parameters** 2290 2291| Name | Type | Mandatory | Description | 2292| ---- | ------ | ---- | ----- | 2293| char | string | Yes | Input character.| 2294 2295**Return value** 2296 2297| Type | Description | 2298| ------- | ------------------------------------ | 2299| boolean | **true** if the input character a letter, and **false** otherwise.| 2300 2301**Example** 2302 ```ts 2303 let isLetter: boolean = i18n.Unicode.isLetter('a'); // isLetter = true 2304 ``` 2305 2306 2307### isLowerCase<sup>9+</sup> 2308 2309static isLowerCase(char: string): boolean 2310 2311Checks whether the input character is a lowercase letter. 2312 2313**Atomic service API**: This API can be used in atomic services since API version 12. 2314 2315**System capability**: SystemCapability.Global.I18n 2316 2317**Parameters** 2318 2319| Name | Type | Mandatory | Description | 2320| ---- | ------ | ---- | ----- | 2321| char | string | Yes | Input character.| 2322 2323**Return value** 2324 2325| Type | Description | 2326| ------- | ---------------------------------------- | 2327| boolean | **true** if the input character a lowercase letter, and **false** otherwise.| 2328 2329**Example** 2330 ```ts 2331 let isLowercase: boolean = i18n.Unicode.isLowerCase('a'); // isLowercase = true 2332 ``` 2333 2334 2335### isUpperCase<sup>9+</sup> 2336 2337static isUpperCase(char: string): boolean 2338 2339Checks whether the input character is an uppercase letter. 2340 2341**Atomic service API**: This API can be used in atomic services since API version 12. 2342 2343**System capability**: SystemCapability.Global.I18n 2344 2345**Parameters** 2346 2347| Name | Type | Mandatory | Description | 2348| ---- | ------ | ---- | ----- | 2349| char | string | Yes | Input character.| 2350 2351**Return value** 2352 2353| Type | Description | 2354| ------- | ---------------------------------------- | 2355| boolean | **true** if the input character an uppercase letter, and **false** otherwise.| 2356 2357**Example** 2358 ```ts 2359 let isUppercase: boolean = i18n.Unicode.isUpperCase('a'); // isUppercase = false 2360 ``` 2361 2362 2363### getType<sup>9+</sup> 2364 2365static getType(char: string): string 2366 2367Obtains the type of the input string. 2368 2369**Atomic service API**: This API can be used in atomic services since API version 12. 2370 2371**System capability**: SystemCapability.Global.I18n 2372 2373**Parameters** 2374 2375| Name | Type | Mandatory | Description | 2376| ---- | ------ | ---- | ----- | 2377| char | string | Yes | Input character.| 2378 2379**Return value** 2380 2381| Type | Description | 2382| ------ | ----------- | 2383| string | Type of the input character.| 2384 2385The following table lists only the common types. For more details, see the Unicode Standard. 2386 2387| Name| Value| Description| 2388| ---- | -------- | ---------- | 2389| U_UNASSIGNED | U_UNASSIGNED | Non-category for unassigned and non-character code points.| 2390| U_GENERAL_OTHER_TYPES | U_GENERAL_OTHER_TYPES | Same as **U_UNASSIGNED**.| 2391| U_UPPERCASE_LETTER | U_UPPERCASE_LETTER | Uppercase letter.| 2392| U_LOWERCASE_LETTER | U_LOWERCASE_LETTER | Lowercase letter. | 2393| U_TITLECASE_LETTER | U_TITLECASE_LETTER | Title case letter.| 2394| U_MODIFIER_LETTER | U_MODIFIER_LETTER | Modifier letter.| 2395| U_OTHER_LETTER | U_OTHER_LETTER | Letters other than the uppercase letter, lowercase letter, title case letter, and modifier letter.| 2396| U_NON_SPACING_MARK | U_NON_SPACING_MARK | Non-spacing mark, such as the accent symbol **'** and the variable symbol **#**.| 2397| U_ENCLOSING_MARK | U_ENCLOSING_MARK | Enclosing mark, for example, a circle or a box.| 2398| U_COMBINING_SPACING_MARK | U_COMBINING_SPACING_MARK | Spacing mark, for example, the vowel symbol **[]**.| 2399| U_DECIMAL_DIGIT_NUMBER | U_DECIMAL_DIGIT_NUMBER | Decimal number.| 2400| U_LETTER_NUMBER | U_LETTER_NUMBER | Letter and number (including Roman numeral).| 2401| U_OTHER_NUMBER | U_OTHER_NUMBER | Other numbers, which are used as encryption symbols, marker symbols, or non-Arabic numerals, such as **@**, **#**, **(1)**, and **①**.| 2402| U_SPACE_SEPARATOR | U_SPACE_SEPARATOR | Space separator, for example, a space character, uninterrupted space character, or space character with a fixed width.| 2403| U_LINE_SEPARATOR | U_LINE_SEPARATOR | Line separator.| 2404| U_PARAGRAPH_SEPARATOR | U_PARAGRAPH_SEPARATOR | Paragraph separator.| 2405| U_CONTROL_CHAR | U_CONTROL_CHAR | Control character.| 2406| U_FORMAT_CHAR | U_FORMAT_CHAR | Format character.| 2407| U_PRIVATE_USE_CHAR | U_PRIVATE_USE_CHAR | Privately used character, for example, a company logo.| 2408| U_SURROGATE | U_SURROGATE | Surrogate, which is used to represent supplementary characters in UTF-16.| 2409| U_DASH_PUNCTUATION | U_DASH_PUNCTUATION | Dash punctuation.| 2410| U_START_PUNCTUATION | U_START_PUNCTUATION | Start punctuation, for example, the left parenthesis.| 2411| U_END_PUNCTUATION | U_END_PUNCTUATION | End punctuation, for example, the right parenthesis.| 2412| U_INITIAL_PUNCTUATION | U_INITIAL_PUNCTUATION | Initial punctuation, for example, the left double quotation mark or left single quotation mark.| 2413| U_FINAL_PUNCTUATION | U_FINAL_PUNCTUATION | Final punctuation, for example, the right double quotation mark or right single quotation mark.| 2414| U_CONNECTOR_PUNCTUATION | U_CONNECTOR_PUNCTUATION | Connector punctuation.| 2415| U_OTHER_PUNCTUATION | U_OTHER_PUNCTUATION | Other punctuations.| 2416| U_MATH_SYMBOL | U_MATH_SYMBOL | Mathematical symbol.| 2417| U_CURRENCY_SYMBOL | U_CURRENCY_SYMBOL | Currency symbol.| 2418| U_MODIFIER_SYMBOL | U_MODIFIER_SYMBOL | Modifier symbol.| 2419| U_OTHER_SYMBOL | U_OTHER_SYMBOL | Other symbols.| 2420 2421**Example** 2422 ```ts 2423 let unicodeType: string = i18n.Unicode.getType('a'); // unicodeType = 'U_LOWERCASE_LETTER' 2424 ``` 2425 2426## I18NUtil<sup>9+</sup> 2427 2428 2429### unitConvert<sup>9+</sup> 2430 2431static unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale: string, style?: string): string 2432 2433Converts one measurement unit into another and formats the unit based on the specified locale and style. 2434 2435**Atomic service API**: This API can be used in atomic services since API version 12. 2436 2437**System capability**: SystemCapability.Global.I18n 2438 2439**Parameters** 2440 2441| Name | Type | Mandatory | Description | 2442| -------- | ---------------------- | ---- | ---------------------------------------- | 2443| fromUnit | [UnitInfo](#unitinfo8) | Yes | Measurement unit to be converted. | 2444| toUnit | [UnitInfo](#unitinfo8) | Yes | Measurement unit to be converted to. | 2445| value | number | Yes | Value of the measurement unit to be converted. | 2446| locale | string | Yes | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region, for example, **zh-Hans-CN**. | 2447| style | string | No | Style used for formatting. The value can be **long**, **short**, or **narrow**. The default value is **short**.<br>For details about the meaning or display effect of different values, see [Number and Unit of Measurement Formatting](../../internationalization/i18n-numbers-weights-measures.md).| 2448 2449**Return value** 2450 2451| Type | Description | 2452| ------ | ----------------------- | 2453| string | String obtained after formatting based on the measurement unit specified by **toUnit**.| 2454 2455**Example** 2456 ```ts 2457 let fromUnit: i18n.UnitInfo = { unit: 'cup', measureSystem: 'US' }; 2458 let toUnit: i18n.UnitInfo = { unit: 'liter', measureSystem: 'SI' }; 2459 let convertResult: string = 2460 i18n.I18NUtil.unitConvert(fromUnit, toUnit, 1000, 'en-US', 'long'); // convertResult = '236.588 liters' 2461 ``` 2462 2463### getDateOrder<sup>9+</sup> 2464 2465static getDateOrder(locale: string): string 2466 2467Obtains the sequence of the year, month, and day in the specified locale. 2468 2469**Atomic service API**: This API can be used in atomic services since API version 12. 2470 2471**System capability**: SystemCapability.Global.I18n 2472 2473**Parameters** 2474 2475| Name | Type | Mandatory | Description | 2476| ------ | ------ | ---- | ------------------------- | 2477| locale | string | Yes | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region, for example, **zh-Hans-CN**.| 2478 2479**Return value** 2480 2481| Type | Description | 2482| ------ | ------------------- | 2483| string | Sequence of the year, month, and day in the locale.| 2484 2485**Example** 2486 ```ts 2487 let order: string = i18n.I18NUtil.getDateOrder('zh-CN'); // order = 'y-L-d' 2488 ``` 2489 2490 2491### getTimePeriodName<sup>11+</sup> 2492 2493static getTimePeriodName(hour:number, locale?: string): string 2494 2495Obtains the localized expression for the specified time of the specified locale. 2496 2497**Atomic service API**: This API can be used in atomic services since API version 12. 2498 2499**System capability**: SystemCapability.Global.I18n 2500 2501**Parameters** 2502 2503| Name | Type | Mandatory | Description | 2504| ------ | ------ | ---- | ------------------------- | 2505| hour | number | Yes | Specified time, for example, **16**.| 2506| locale | string | No | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region. for example, **zh-Hans-CN**.<br>The default value is the current locale.| 2507 2508**Return value** 2509 2510| Type | Description | 2511| ------ | ------------------- | 2512| string | Localized expression for the specified time of the specified locale.| 2513 2514**Error codes** 2515 2516For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 2517 2518| ID | Error Message | 2519| ------ | ---------------------- | 2520| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2521| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 2522 2523**Example** 2524 ```ts 2525 import { BusinessError } from '@kit.BasicServicesKit'; 2526 2527 try { 2528 let name: string = i18n.I18NUtil.getTimePeriodName(2, 'zh-CN'); // name = 'a.m.' 2529 } catch (error) { 2530 let err: BusinessError = error as BusinessError; 2531 console.error(`call I18NUtil.getTimePeriodName failed, error code: ${err.code}, message: ${err.message}.`); 2532 } 2533 ``` 2534 2535### getBestMatchLocale<sup>12+</sup> 2536 2537static getBestMatchLocale(locale: string, localeList: string[]): string 2538 2539Obtains the locale that best matches a region from the specified locale list. 2540 2541**Atomic service API**: This API can be used in atomic services since API version 12. 2542 2543**System capability**: SystemCapability.Global.I18n 2544 2545**Parameters** 2546 2547| Name | Type | Mandatory | Description | 2548| ------ | ------ | ---- | ------------------------- | 2549| locale | string | Yes | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), for example, **zh-Hans-CN**.| 2550| localeList | string[] | Yes | Locale list.| 2551 2552**Return value** 2553 2554| Type | Description | 2555| ------ | ------------------- | 2556| string | ID of the locale that best matches a region. If no matching locale is found, an empty string is returned.| 2557 2558**Error codes** 2559 2560For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 2561 2562| ID | Error Message | 2563| ------ | ---------------------- | 2564| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2565| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 2566 2567**Example** 2568 2569 ```ts 2570 import { BusinessError } from '@kit.BasicServicesKit'; 2571 2572 try { 2573 let matchedLocaleId: string = i18n.I18NUtil.getBestMatchLocale('zh-Hans-CN', 2574 ['en-Latn-US', 'en-GB', 'zh-Hant-CN', 'zh-Hans-MO']); // matchedLocaleId = 'zh-Hans-MO' 2575 } catch (error) { 2576 let err: BusinessError = error as BusinessError; 2577 console.error(`call I18NUtil.getBestMatchLocale failed, error code: ${err.code}, message: ${err.message}.`); 2578 } 2579 ``` 2580 2581### getThreeLetterLanguage<sup>12+</sup> 2582 2583static getThreeLetterLanguage(locale: string): string 2584 2585Converts a language code from two letters to three letters.<br>For example, the two-letter language code of Chinese is **zh**, and the corresponding three-letter language code is **zho**. For details, see [ISO 639](https://www.iso.org/iso-639-language-code). 2586 2587**Atomic service API**: This API can be used in atomic services since API version 12. 2588 2589**System capability**: SystemCapability.Global.I18n 2590 2591**Parameters** 2592 2593| Name| Type | Mandatory| Description | 2594| ------ | ------ | ---- | ------------------------ | 2595| locale | string | Yes | Two-letter code of the language to be converted, for example, **zh**.| 2596 2597**Error codes** 2598 2599For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 2600 2601| ID| Error Message | 2602| -------- | ------------------------------------------------------------ | 2603| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2604| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 2605 2606**Example** 2607 2608 ```ts 2609 import { BusinessError } from '@kit.BasicServicesKit'; 2610 2611 try { 2612 let language: string = i18n.I18NUtil.getThreeLetterLanguage('zh') // language = 'zho' 2613 } catch (error) { 2614 let err: BusinessError = error as BusinessError; 2615 console.error(`call I18NUtil.getThreeLetterLanguage failed, error code: ${err.code}, message: ${err.message}.`); 2616 } 2617 ``` 2618 2619### getThreeLetterRegion<sup>12+</sup> 2620 2621static getThreeLetterRegion(locale: string): string 2622 2623Converts a country/region code from two letters to three letters.<br>For example, the two-letter country/region code of China is **CN**, and the three-letter country/region code is **CHN**. For details, see [ISO 3166](https://www.iso.org/iso-3166-country-codes.html). 2624 2625**Atomic service API**: This API can be used in atomic services since API version 12. 2626 2627**System capability**: SystemCapability.Global.I18n 2628 2629**Parameters** 2630 2631| Name| Type | Mandatory| Description | 2632| ------ | ------ | ---- | ------------------------ | 2633| locale | string | Yes | Two-letter country/region code to be converted, for example, **CN**.| 2634 2635**Error codes** 2636 2637For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 2638 2639| ID| Error Message | 2640| -------- | ------------------------------------------------------------ | 2641| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2642| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 2643 2644**Example** 2645 2646 ```ts 2647 import { BusinessError } from '@kit.BasicServicesKit'; 2648 2649 try { 2650 let region: string = i18n.I18NUtil.getThreeLetterRegion('CN') // region = 'CHN' 2651 } catch (error) { 2652 let err: BusinessError = error as BusinessError; 2653 console.error(`call I18NUtil.getThreeLetterRegion failed, error code: ${err.code}, message: ${err.message}.`); 2654 } 2655 ``` 2656 2657### getUnicodeWrappedFilePath<sup>18+</sup> 2658 2659static getUnicodeWrappedFilePath(path: string, delimiter?: string, locale?: intl.Locale): string 2660 2661Performs file path mirroring.<br>For example, **/data/out/tmp** is changed to **tmp/out/data/** after mirroring. 2662 2663**Atomic service API**: This API can be used in atomic services since API version 18. 2664 2665**System capability**: SystemCapability.Global.I18n 2666 2667**Parameters** 2668 2669| Name| Type | Mandatory| Description | 2670| ------ | ------ | ---- | ------------------------ | 2671| path | string | Yes | Path to mirror, for example, **/data/out/tmp**.| 2672| delimiter | string | No | Path delimiter. The default value is **/**.| 2673| locale | [intl.Locale](./js-apis-intl.md#locale) | No | **intl.Locale** object. The default value is **new intl.Locale([i18n.System.getSystemLocale()](#getsystemlocale9))**.| 2674 2675**Error codes** 2676 2677For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 2678 2679| ID| Error Message | 2680| -------- | ------------------------------------------------------------ | 2681| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2682| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 2683 2684**Example** 2685 2686 ```ts 2687 import { BusinessError } from '@kit.BasicServicesKit'; 2688 import { intl } from '@kit.LocalizationKit'; 2689 2690 try { 2691 let path: string = '/data/out/tmp'; 2692 let delimiter: string = '/'; 2693 let locale: intl.Locale = new intl.Locale('ar'); 2694 let mirrorPath: string = 2695 i18n.I18NUtil.getUnicodeWrappedFilePath(path, delimiter, locale); // mirrorPath is displayed as tmp/out/data/. 2696 } catch (error) { 2697 let err: BusinessError = error as BusinessError; 2698 console.error(`call I18NUtil.getUnicodeWrappedFilePath failed, error code: ${err.code}, message: ${err.message}.`); 2699 } 2700 ``` 2701 2702## Normalizer<sup>10+</sup> 2703 2704 2705### getInstance<sup>10+</sup> 2706 2707static getInstance(mode: NormalizerMode): Normalizer 2708 2709Obtains a **Normalizer** object for text normalization. 2710 2711**Atomic service API**: This API can be used in atomic services since API version 12. 2712 2713**System capability**: SystemCapability.Global.I18n 2714 2715**Parameters** 2716 2717| Name | Type | Mandatory | Description | 2718| ------ | ------ | ---- | ------------------------- | 2719| mode | [NormalizerMode](#normalizermode10) | Yes | Text normalization mode.| 2720 2721**Return value** 2722 2723| Type | Description | 2724| ------ | ------------------- | 2725| [Normalizer](#normalizer10) | **Normalizer** object for text normalization.| 2726 2727**Error codes** 2728 2729For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2730 2731| ID | Error Message | 2732| ------ | ---------------------- | 2733| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2734 2735**Example** 2736 ```ts 2737 import { BusinessError } from '@kit.BasicServicesKit'; 2738 2739 try { 2740 let normalizer: i18n.Normalizer = i18n.Normalizer.getInstance(i18n.NormalizerMode.NFC); 2741 } catch (error) { 2742 let err: BusinessError = error as BusinessError; 2743 console.error(`call Normalizer.getInstance failed, error code: ${err.code}, message: ${err.message}.`); 2744 } 2745 ``` 2746 2747 2748### normalize<sup>10+</sup> 2749 2750normalize(text: string): string 2751 2752Normalizes text strings. 2753 2754**Atomic service API**: This API can be used in atomic services since API version 12. 2755 2756**System capability**: SystemCapability.Global.I18n 2757 2758**Parameters** 2759 2760| Name | Type | Mandatory | Description | 2761| ------ | ------ | ---- | ------------------------- | 2762| text | string | Yes | Text strings to be normalized.| 2763 2764**Return value** 2765 2766| Type | Description | 2767| ------ | ------------------- | 2768| string | Normalized text strings.| 2769 2770**Error codes** 2771 2772For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2773 2774| ID | Error Message | 2775| ------ | ---------------------- | 2776| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2777 2778**Example** 2779 ```ts 2780 import { BusinessError } from '@kit.BasicServicesKit'; 2781 2782 try { 2783 let normalizer: i18n.Normalizer = i18n.Normalizer.getInstance(i18n.NormalizerMode.NFC); 2784 let normalizedText: string = normalizer.normalize('\u1E9B\u0323'); // normalizedText = 'ẛ̣' 2785 } catch (error) { 2786 let err: BusinessError = error as BusinessError; 2787 console.error(`call Normalizer.getInstance failed, error code: ${err.code}, message: ${err.message}.`); 2788 } 2789 ``` 2790 2791## NormalizerMode<sup>10+</sup> 2792 2793Enumerates text normalization modes. 2794 2795**Atomic service API**: This API can be used in atomic services since API version 12. 2796 2797**System capability**: SystemCapability.Global.I18n 2798 2799| Name| Value| Description| 2800| -------- | -------- | -------- | 2801| NFC | 1 | NFC.| 2802| NFD | 2 | NFD.| 2803| NFKC | 3 | NFKC.| 2804| NFKD | 4 | NFKD.| 2805 2806 2807## HolidayManager<sup>11+</sup> 2808 2809 2810### constructor<sup>11+</sup> 2811 2812constructor(icsPath: String) 2813 2814Creates a **HolidayManager** object. 2815 2816**Atomic service API**: This API can be used in atomic services since API version 12. 2817 2818**System capability**: SystemCapability.Global.I18n 2819 2820**Parameters** 2821 2822| Name | Type | Mandatory| Description | 2823| --------- | ------------- | ---- | ------------- | 2824| icsPath | String | Yes | Path of the **.ics** file with the read permission granted for applications. | 2825 2826**Error codes** 2827 2828For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 2829 2830| ID | Error Message | 2831| ------ | ---------------------- | 2832| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2833| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 2834 2835**Example** 2836 ```ts 2837 import { BusinessError } from '@kit.BasicServicesKit'; 2838 2839 try { 2840 let holidayManager = new i18n.HolidayManager('/system/lib/US.ics'); 2841 } catch (error) { 2842 let err: BusinessError = error as BusinessError; 2843 console.error(`call i18n.HolidayManager failed, error code: ${err.code}, message: ${err.message}.`); 2844 } 2845 ``` 2846 2847### isHoliday<sup>11+</sup> 2848 2849isHoliday(date?: Date): boolean 2850 2851Determines whether the specified date is a holiday. 2852 2853**Atomic service API**: This API can be used in atomic services since API version 12. 2854 2855**System capability**: SystemCapability.Global.I18n 2856 2857**Parameters** 2858 2859| Name | Type | Mandatory| Description | 2860| --------- | ---------------| ---- | ------------- | 2861| date | Date | No | Date and time. Note: The month starts from **0**. For example, **0** indicates January.<br>If no date is specified, the current date is used by default.| 2862 2863**Return value** 2864 2865| Type | Description | 2866| ----------------- | ----------------------| 2867| boolean | **true** if the specified date is a holiday, and **false** otherwise.| 2868 2869**Error codes** 2870 2871For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 2872 2873| ID | Error Message | 2874| ------ | ---------------------- | 2875| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2876 2877**Example** 2878 ```ts 2879 import { BusinessError } from '@kit.BasicServicesKit'; 2880 2881 try { 2882 // Replace /system/lib/US.ics with the actual ICS file path. 2883 let holidayManager: i18n.HolidayManager = new i18n.HolidayManager('/system/lib/US.ics'); 2884 let isHoliday: boolean = holidayManager.isHoliday(); 2885 isHoliday = holidayManager.isHoliday(new Date(2023, 5, 25)); // The date is 2023.06.25. 2886 } catch (error) { 2887 let err: BusinessError = error as BusinessError; 2888 console.error(`call holidayManager.isHoliday failed, error code: ${err.code}, message: ${err.message}.`); 2889 } 2890 ``` 2891 2892 2893### getHolidayInfoItemArray<sup>11+</sup> 2894 2895getHolidayInfoItemArray(year?: number): Array<[HolidayInfoItem](#holidayinfoitem11)> 2896 2897Obtains the holiday information list of the specified year. 2898 2899**Atomic service API**: This API can be used in atomic services since API version 12. 2900 2901**System capability**: SystemCapability.Global.I18n 2902 2903**Parameters** 2904 2905| Name | Type | Mandatory| Description | 2906| --------- | ------------- | ---- | ------------- | 2907| year | number | No | Specified year, for example, 2023.<br>If no year is specified, the current year is used by default.| 2908 2909**Return value** 2910 2911| Type | Description | 2912| ----------------- | -------------------- | 2913| Array<[HolidayInfoItem](#holidayinfoitem11)> | Holiday information list.| 2914 2915**Error codes** 2916 2917For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 2918 2919| ID | Error Message | 2920| ------ | ---------------------- | 2921| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2922| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 2923 2924**Example** 2925 ```ts 2926 import { BusinessError } from '@kit.BasicServicesKit'; 2927 2928 try { 2929 // Replace /system/lib/US.ics with the actual ICS file path. 2930 let holidayManager: i18n.HolidayManager = new i18n.HolidayManager('/system/lib/US.ics'); 2931 let holidayInfoItemArray: Array<i18n.HolidayInfoItem> = holidayManager.getHolidayInfoItemArray(2023); 2932 } catch (error) { 2933 let err: BusinessError = error as BusinessError; 2934 console.error(`call holidayManager.getHolidayInfoItemArray failed, error code: ${err.code}, message: ${err.message}.`); 2935 } 2936 ``` 2937 2938## HolidayInfoItem<sup>11+</sup> 2939 2940Represents the holiday information. 2941 2942**Atomic service API**: This API can be used in atomic services since API version 12. 2943 2944**System capability**: SystemCapability.Global.I18n 2945 2946| Name | Type | Mandatory | Description | 2947| --------------- | --------------- | ------ | --------------------------------------- | 2948| baseName | string | Yes | Holiday name. | 2949| year | number | Yes | Year of the holiday. | 2950| month | number | Yes | Month of the holiday. | 2951| day | number | Yes | Day of the holiday. | 2952| localNames | Array<[HolidayLocalName](#holidaylocalname11)> | No | Local names of the holiday. | 2953 2954## HolidayLocalName<sup>11+</sup> 2955 2956Defines the local names of a holiday. 2957 2958**Atomic service API**: This API can be used in atomic services since API version 12. 2959 2960**System capability**: SystemCapability.Global.I18n 2961 2962| Name | Type | Mandatory | Description | 2963| --------------- | -----------------| ------ | --------------------------------------- | 2964| language | string | Yes | Local language of a holiday, for example, **ar**, **en**, or **tr**. | 2965| name | string | Yes | Local name of a holiday. For example, the Turkish name of Sacrifice Feast is Kurban Bayrami. | 2966 2967 2968## i18n.getSimpleDateTimeFormatByPattern<sup>18+</sup> 2969 2970getSimpleDateTimeFormatByPattern(pattern: string, locale?: intl.Locale): SimpleDateTimeFormat 2971 2972Obtains a **SimpleDateTimeFormat** object based on the specified pattern string. For details about the display differences between the objects obtained by this API and **getSimpleDateTimeFormatBySkeleton**, see [SimpleDateTimeFormat] (#simpledatetimeformat18). 2973 2974**Atomic service API**: This API can be used in atomic services since API version 18. 2975 2976**System capability**: SystemCapability.Global.I18n 2977 2978**Parameters** 2979 2980| Name | Type | Mandatory | Description | 2981| ------- | ----------- | ----- | ---------------------------------------- | 2982| pattern | string | Yes | Valid pattern. For details about the supported characters and their meanings, see [Date Field Symbol Table](https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table). This parameter also supports custom text enclosed in single quotation marks (').| 2983| locale | [intl.Locale](./js-apis-intl.md#locale) | No | Valid locale. The default value is the system locale.| 2984 2985**Return value** 2986 2987| Type | Description | 2988| ---------------------- | ----- | 2989| [SimpleDateTimeFormat](#simpledatetimeformat18) | **SimpleDateTimeFormat** object.| 2990 2991**Error codes** 2992 2993For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 2994 2995| ID | Error Message | 2996| ------ | ---------------------- | 2997| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2998| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 2999 3000**Example** 3001 ```ts 3002 import { BusinessError } from '@kit.BasicServicesKit'; 3003 import { intl } from '@kit.LocalizationKit'; 3004 3005 try { 3006 let locale: intl.Locale = new intl.Locale('zh-Hans-CN'); 3007 let formatter: i18n.SimpleDateTimeFormat = i18n.getSimpleDateTimeFormatByPattern("'month('M')'", locale); 3008 } catch (error) { 3009 let err: BusinessError = error as BusinessError; 3010 console.error(`call i18n.getSimpleDateTimeFormatByPattern failed, error code: ${err.code}, message: ${err.message}.`); 3011 } 3012 ``` 3013 3014## i18n.getSimpleDateTimeFormatBySkeleton<sup>18+</sup> 3015 3016getSimpleDateTimeFormatBySkeleton(skeleton: string, locale?: intl.Locale): SimpleDateTimeFormat 3017 3018Obtains a **SimpleDateTimeFormat** object based on the specified skeleton. For details about the display differences between the objects obtained by this API and **getSimpleDateTimeFormatByPattern**, see [SimpleDateTimeFormat] (#simpledatetimeformat18). 3019 3020**Atomic service API**: This API can be used in atomic services since API version 18. 3021 3022**System capability**: SystemCapability.Global.I18n 3023 3024**Parameters** 3025 3026| Name | Type | Mandatory | Description | 3027| ------- | ----------- | ----- | ---------------------------------------- | 3028| skeleton | string | Yes | Valid skeleton. For details about the supported characters and their meanings, see [Date Field Symbol Table](https://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table). This parameter does not support custom text.| 3029| locale | [intl.Locale](./js-apis-intl.md#locale) | No | Valid locale. The default value is the system locale.| 3030 3031**Return value** 3032 3033| Type | Description | 3034| ---------------------- | ----- | 3035| [SimpleDateTimeFormat](#simpledatetimeformat18) | **SimpleDateTimeFormat** object.| 3036 3037**Error codes** 3038 3039For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 3040 3041| ID | Error Message | 3042| ------ | ---------------------- | 3043| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3044| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 3045 3046**Example** 3047 ```ts 3048 import { BusinessError } from '@kit.BasicServicesKit'; 3049 import { intl } from '@kit.LocalizationKit'; 3050 3051 try { 3052 let locale: intl.Locale = new intl.Locale('zh-Hans-CN'); 3053 let formatter: i18n.SimpleDateTimeFormat = i18n.getSimpleDateTimeFormatBySkeleton('yMd', locale); 3054 } catch (error) { 3055 let err: BusinessError = error as BusinessError; 3056 console.error(`call i18n.getSimpleDateTimeFormatBySkeleton failed, error code: ${err.code}, message: ${err.message}.`); 3057 } 3058 ``` 3059 3060## SimpleDateTimeFormat<sup>18+</sup> 3061 3062### format<sup>18+</sup> 3063 3064format(date: Date): string 3065 3066Formats the date and time. 3067 3068**Atomic service API**: This API can be used in atomic services since API version 18. 3069 3070**System capability**: SystemCapability.Global.I18n 3071 3072**Parameters** 3073 3074| Name | Type | Mandatory | Description | 3075| ---- | ---- | ---- | ----------------- | 3076| date | Date | Yes | Date and time. Note: The month starts from **0**. For example, **0** indicates January.| 3077 3078**Return value** 3079 3080| Type | Description | 3081| ---------------------- | ----- | 3082| string | A string containing the formatted date and time.| 3083 3084**Error codes** 3085 3086For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3087 3088| ID | Error Message | 3089| ------ | ---------------------- | 3090| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3091 3092**Example** 3093 ```ts 3094 import { BusinessError } from '@kit.BasicServicesKit'; 3095 import { intl } from '@kit.LocalizationKit'; 3096 3097 try { 3098 let locale : intl.Locale = new intl.Locale("zh-Hans-CN"); 3099 let date: Date = new Date(2024, 11, 13); // Set the date to 2024.12.13. 3100 3101 let formatterWithText: i18n.SimpleDateTimeFormat = 3102 i18n.getSimpleDateTimeFormatByPattern("'month('M')'", locale); 3103 let formattedDate: string = formatterWithText.format(date); // formattedDate = 'month(12)' 3104 3105 let patternFormatter: i18n.SimpleDateTimeFormat = i18n.getSimpleDateTimeFormatByPattern('yMd', locale); 3106 formattedDate = patternFormatter.format(date); // formattedDate = '20241213' 3107 3108 let skeletonFormatter: i18n.SimpleDateTimeFormat = i18n.getSimpleDateTimeFormatBySkeleton('yMd', locale); 3109 formattedDate = skeletonFormatter.format(date); // formattedDate = '2024/12/13' 3110 } catch (error) { 3111 let err: BusinessError = error as BusinessError; 3112 console.error(`call SimpleDateTimeFormat.format failed, error code: ${err.code}, message: ${err.message}.`); 3113 } 3114 ``` 3115 3116 3117## i18n.getSimpleNumberFormatBySkeleton<sup>18+</sup> 3118 3119getSimpleNumberFormatBySkeleton(skeleton: string, locale?: intl.Locale): SimpleNumberFormat 3120 3121Obtains a **SimpleNumberFormat** object based on the specified skeleton. 3122 3123**Atomic service API**: This API can be used in atomic services since API version 18. 3124 3125**System capability**: SystemCapability.Global.I18n 3126 3127**Parameters** 3128 3129| Name | Type | Mandatory | Description | 3130| ------- | ----------- | ----- | ---------------------------------------- | 3131| skeleton | string | Yes | Valid skeleton. For details about the supported characters and their meanings, see [Number Skeletons](https://unicode-org.github.io/icu/userguide/format_parse/numbers/skeletons.html#number-skeletons).| 3132| locale | [intl.Locale](./js-apis-intl.md#locale) | No | Valid locale. The default value is the system locale.| 3133 3134**Return value** 3135 3136| Type | Description | 3137| ---------------------- | ----- | 3138| [SimpleNumberFormat](#simplenumberformat18) | **SimpleNumberFormat** object.| 3139 3140**Error codes** 3141 3142For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 3143 3144| ID | Error Message | 3145| ------ | ---------------------- | 3146| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3147| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 3148 3149**Example** 3150 ```ts 3151 import { BusinessError } from '@kit.BasicServicesKit'; 3152 import { intl } from '@kit.LocalizationKit'; 3153 3154 try { 3155 let locale: intl.Locale = new intl.Locale('zh-Hans-CN'); 3156 let formatter: i18n.SimpleNumberFormat = i18n.getSimpleNumberFormatBySkeleton('%', locale); 3157 } catch (error) { 3158 let err: BusinessError = error as BusinessError; 3159 console.error(`call SimpleDateTimeFormat.getSimpleNumberFormatBySkeleton failed, error code: ${err.code}, message: ${err.message}.`); 3160 } 3161 ``` 3162 3163## SimpleNumberFormat<sup>18+</sup> 3164 3165### format<sup>18+</sup> 3166 3167format(value: number): string 3168 3169Formats a number. 3170 3171**Atomic service API**: This API can be used in atomic services since API version 18. 3172 3173**System capability**: SystemCapability.Global.I18n 3174 3175**Parameters** 3176 3177| Name | Type | Mandatory | Description | 3178| ---- | ---- | ---- | ----------------- | 3179| value | number | Yes | Number to be formatted.| 3180 3181**Return value** 3182 3183| Type | Description | 3184| ---------------------- | ----- | 3185| string | Formatted number.| 3186 3187**Error codes** 3188 3189For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3190 3191| ID | Error Message | 3192| ------ | ---------------------- | 3193| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3194 3195**Example** 3196 ```ts 3197 import { BusinessError } from '@kit.BasicServicesKit'; 3198 import { intl } from '@kit.LocalizationKit'; 3199 3200 try { 3201 let locale: intl.Locale = new intl.Locale('zh-Hans-CN'); 3202 let formatter: i18n.SimpleNumberFormat = i18n.getSimpleNumberFormatBySkeleton('%', locale); 3203 let formattedNumber: string = formatter.format(10); // formattedNumber = '10%' 3204 } catch (error) { 3205 let err: BusinessError = error as BusinessError; 3206 console.error(`call SimpleNumberFormat.format failed, error code: ${err.code}, message: ${err.message}.`); 3207 } 3208 ``` 3209 3210## StyledNumberFormat<sup>18+</sup> 3211 3212### constructor<sup>18+</sup> 3213 3214constructor(numberFormat: intl.NumberFormat | SimpleNumberFormat, options?: StyledNumberFormatOptions) 3215 3216Creates a **NumberFormat** object for rich text display. 3217 3218**Atomic service API**: This API can be used in atomic services since API version 18. 3219 3220**System capability**: SystemCapability.Global.I18n 3221 3222**Parameters** 3223 3224| Name | Type | Mandatory| Description | 3225| --------- | ------------- | ---- | ------------- | 3226| numberFormat | [intl.NumberFormat](js-apis-intl.md#numberformat) \| [SimpleNumberFormat](#simplenumberformat18) | Yes | **NumberFormat** object. | 3227| options | [StyledNumberFormatOptions](#stylednumberformatoptions18) | No| Configuration options of the **NumberFormat** object. The default value is the default text style. | 3228 3229**Error codes** 3230 3231For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3232 3233| ID | Error Message | 3234| ------ | ---------------------- | 3235| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3236 3237**Example** 3238 ```ts 3239 import { BusinessError } from '@kit.BasicServicesKit'; 3240 import { intl } from '@kit.LocalizationKit'; 3241 3242 try { 3243 let integerTextStyle: TextStyle = new TextStyle({ fontColor: Color.Red }); 3244 let decimalTextStyle: TextStyle = new TextStyle({ fontColor: Color.Brown }); 3245 let fractionTextStyle: TextStyle = new TextStyle({ fontColor: Color.Blue }); 3246 let unitTextStyle: TextStyle = new TextStyle({ fontColor: Color.Green }); 3247 3248 // Create a StyledNumberFormat object through intl.NumberFormat. 3249 let numFmt: intl.NumberFormat = new intl.NumberFormat('zh', { style: 'unit', unit: 'percent' }); 3250 let styledNumFmt: i18n.StyledNumberFormat = new i18n.StyledNumberFormat(numFmt, { 3251 integer: integerTextStyle, 3252 decimal: decimalTextStyle, 3253 fraction: fractionTextStyle, 3254 unit: unitTextStyle 3255 }); 3256 3257 // Create a StyledNumberFormat object through SimpleNumberFormat. 3258 let locale: intl.Locale = new intl.Locale('zh'); 3259 let simpleNumFmt: i18n.SimpleNumberFormat = i18n.getSimpleNumberFormatBySkeleton('percent', locale); 3260 let styledSimpleNumFmt: i18n.StyledNumberFormat = new i18n.StyledNumberFormat(simpleNumFmt, { 3261 integer: integerTextStyle, 3262 decimal: decimalTextStyle, 3263 fraction: fractionTextStyle, 3264 unit: unitTextStyle 3265 }); 3266 } catch (error) { 3267 let err: BusinessError = error as BusinessError; 3268 console.error(`call i18n.StyledNumberFormat failed, error code: ${err.code}, message: ${err.message}.`); 3269 } 3270 ``` 3271 3272### format<sup>18+</sup> 3273 3274format(value: number): StyledString 3275 3276Formats a number to a rich text object. 3277 3278**Atomic service API**: This API can be used in atomic services since API version 18. 3279 3280**System capability**: SystemCapability.Global.I18n 3281 3282**Parameters** 3283 3284| Name | Type | Mandatory| Description | 3285| --------- | ------------- | ---- | ------------- | 3286| value | number | Yes| Number to be formatted. | 3287 3288**Return value** 3289 3290| Type | Description | 3291| ----------------- | ----------------------| 3292| [StyledString](../apis-arkui/arkui-ts/ts-universal-styled-string.md#styledstring) | Rich text object.| 3293 3294 3295**Error codes** 3296 3297For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 3298 3299| ID | Error Message | 3300| ------ | ---------------------- | 3301| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3302 3303**Example** 3304 ```ts 3305 import { BusinessError } from '@kit.BasicServicesKit'; 3306 import { intl } from '@kit.LocalizationKit'; 3307 3308 try { 3309 let integerTextStyle: TextStyle = new TextStyle({ fontColor: Color.Red }); 3310 let decimalTextStyle: TextStyle = new TextStyle({ fontColor: Color.Brown }); 3311 let fractionTextStyle: TextStyle = new TextStyle({ fontColor: Color.Blue }); 3312 let unitTextStyle: TextStyle = new TextStyle({ fontColor: Color.Green }); 3313 3314 // Create a StyledNumberFormat object through intl.NumberFormat. 3315 let numFmt: intl.NumberFormat = new intl.NumberFormat('zh', { style: 'unit', unit: 'percent' }); 3316 let styledNumFmt: i18n.StyledNumberFormat = new i18n.StyledNumberFormat(numFmt, { 3317 integer: integerTextStyle, 3318 decimal: decimalTextStyle, 3319 fraction: fractionTextStyle, 3320 unit: unitTextStyle 3321 }); 3322 // formattedNumber.getString () is 1,234.568%. In the formatted number, 1,234 is in red, . in brown, 568 in blue, and % in green. 3323 let formattedNumber: StyledString = styledNumFmt.format(1234.5678); 3324 3325 // Create a StyledNumberFormat object through SimpleNumberFormat. 3326 let locale: intl.Locale = new intl.Locale('zh'); 3327 let simpleNumFmt: i18n.SimpleNumberFormat = i18n.getSimpleNumberFormatBySkeleton('percent', locale); 3328 let styledSimpleNumFmt: i18n.StyledNumberFormat = new i18n.StyledNumberFormat(simpleNumFmt, { 3329 integer: integerTextStyle, 3330 decimal: decimalTextStyle, 3331 fraction: fractionTextStyle, 3332 unit: unitTextStyle 3333 }); 3334 // formattedSimpleNumber.getString () is 1,234.5678%. In the formatted number, '1,234' is in red, . in brown, 5678 in blue, and % in green. 3335 let formattedSimpleNumber: StyledString = styledSimpleNumFmt.format(1234.5678); 3336 } catch (error) { 3337 let err: BusinessError = error as BusinessError; 3338 console.error(`call StyledNumberFormat.format failed, error code: ${err.code}, message: ${err.message}.`); 3339 } 3340 ``` 3341 3342## StyledNumberFormatOptions<sup>18+</sup> 3343 3344Defines the options for creating a **NumberFormat** object for rich text display. 3345 3346**Atomic service API**: This API can be used in atomic services since API version 18. 3347 3348**System capability**: SystemCapability.Global.I18n 3349 3350| Name | Type | Mandatory | Description | 3351| --------------- | --------------- | ------ | --------------------------------------- | 3352| integer | [TextStyle](../apis-arkui/arkui-ts/ts-universal-styled-string.md#textstyle) | No | Text style for the integer part. The default value is the default text style. | 3353| decimal | [TextStyle](../apis-arkui/arkui-ts/ts-universal-styled-string.md#textstyle) | No | Text style for the decimal point. The default value is the default text style. | 3354| fraction | [TextStyle](../apis-arkui/arkui-ts/ts-universal-styled-string.md#textstyle) | No | Text style for the fraction part. The default value is the default text style. | 3355| unit | [TextStyle](../apis-arkui/arkui-ts/ts-universal-styled-string.md#textstyle) | No | Text style for the unit. The default value is the default text style. | 3356 3357## i18n.getDisplayCountry<sup>(deprecated)</sup> 3358 3359getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): string 3360 3361Obtains the localized script for the specified country. 3362 3363This API is deprecated since API version 9. You are advised to use [System.getDisplayCountry](#getdisplaycountry9). 3364 3365**System capability**: SystemCapability.Global.I18n 3366 3367**Parameters** 3368 3369| Name | Type | Mandatory | Description | 3370| ------------ | ------- | ---- | ---------------- | 3371| country | string | Yes | Specified country. | 3372| locale | string | Yes | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region. | 3373| sentenceCase | boolean | No | Whether to use sentence case to display the text. The value **true** means to display the text in title case format, and the value **false** means to display the text in the default case format of the locale. The default value is **true**.| 3374 3375**Return value** 3376 3377| Type | Description | 3378| ------ | ------------- | 3379| string | Localized script for the specified country.| 3380 3381**Example** 3382 ```ts 3383 let countryName: string = i18n.getDisplayCountry('zh-CN', 'en-GB', true); // countryName = 'China' 3384 countryName = i18n.getDisplayCountry('zh-CN', 'en-GB'); // countryName = 'China' 3385 ``` 3386 3387## i18n.getDisplayCountry<sup>(deprecated)</sup> 3388 3389getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): string 3390 3391Obtains the localized script for the specified country. 3392 3393This API is deprecated since API version 9. You are advised to use [System.getDisplayCountry](#getdisplaycountry9). 3394 3395**System capability**: SystemCapability.Global.I18n 3396 3397**Parameters** 3398 3399| Name | Type | Mandatory | Description | 3400| ------------ | ------- | ---- | ---------------- | 3401| country | string | Yes | Specified country. | 3402| locale | string | Yes | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region. | 3403| sentenceCase | boolean | No | Whether to use sentence case to display the text. The value **true** means to display the text in title case format, and the value **false** means to display the text in the default case format of the locale. The default value is **true**.| 3404 3405**Return value** 3406 3407| Type | Description | 3408| ------ | ------------- | 3409| string | Localized script for the specified country.| 3410 3411**Example** 3412 ```ts 3413 let countryName: string = i18n.getDisplayCountry('zh-CN', 'en-GB', true); // countryName = 'China' 3414 countryName = i18n.getDisplayCountry('zh-CN', 'en-GB'); // countryName = 'China' 3415 ``` 3416 3417 3418## i18n.getDisplayLanguage<sup>(deprecated)</sup> 3419 3420getDisplayLanguage(language: string, locale: string, sentenceCase?: boolean): string 3421 3422Obtains the localized script for the specified language. 3423 3424This API is deprecated since API version 9. You are advised to use [System.getDisplayLanguage](#getdisplaylanguage9). 3425 3426**System capability**: SystemCapability.Global.I18n 3427 3428**Parameters** 3429 3430| Name | Type | Mandatory | Description | 3431| ------------ | ------- | ---- | ---------------- | 3432| language | string | Yes | Specified language. | 3433| locale | string | Yes | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region. | 3434| sentenceCase | boolean | No | Whether to use sentence case to display the text. The value **true** means to display the text in title case format, and the value **false** means to display the text in the default case format of the locale. The default value is **true**.| 3435 3436**Return value** 3437 3438| Type | Description | 3439| ------ | ------------- | 3440| string | Localized script for the specified language.| 3441 3442**Example** 3443 ```ts 3444 let languageName: string = i18n.getDisplayLanguage('zh', 'en-GB', true); // languageName = 'Chinese' 3445 languageName = i18n.getDisplayLanguage('zh', 'en-GB'); // languageName = 'Chinese' 3446 ``` 3447 3448 3449## i18n.getSystemLanguage<sup>(deprecated)</sup> 3450 3451getSystemLanguage(): string 3452 3453Obtains the system language. 3454 3455This API is deprecated since API version 9. You are advised to use [System.getSystemLanguage](#getsystemlanguage9). 3456 3457**System capability**: SystemCapability.Global.I18n 3458 3459**Return value** 3460 3461| Type | Description | 3462| ------ | ------- | 3463| string | System language ID.| 3464 3465**Example** 3466 ```ts 3467 let systemLanguage: string = i18n.getSystemLanguage(); 3468 ``` 3469 3470 3471## i18n.getSystemRegion<sup>(deprecated)</sup> 3472 3473getSystemRegion(): string 3474 3475Obtains the system region. 3476 3477This API is deprecated since API version 9. You are advised to use [System.getSystemRegion](#getsystemregion9). 3478 3479**System capability**: SystemCapability.Global.I18n 3480 3481**Return value** 3482 3483| Type | Description | 3484| ------ | ------- | 3485| string | System region ID.| 3486 3487**Example** 3488 ```ts 3489 let region: string = i18n.getSystemRegion(); 3490 ``` 3491 3492 3493## i18n.getSystemLocale<sup>(deprecated)</sup> 3494 3495getSystemLocale(): string 3496 3497Obtains the system locale. 3498 3499This API is deprecated since API version 9. You are advised to use [System.getSystemLocale](#getsystemlocale9). 3500 3501**System capability**: SystemCapability.Global.I18n 3502 3503**Return value** 3504 3505| Type | Description | 3506| ------ | ------- | 3507| string | System locale ID.| 3508 3509**Example** 3510 ```ts 3511 let locale: string = i18n.getSystemLocale(); 3512 ``` 3513 3514 3515## i18n.is24HourClock<sup>(deprecated)</sup> 3516 3517is24HourClock(): boolean 3518 3519Checks whether the 24-hour clock is used. 3520 3521This API is deprecated since API version 9. You are advised to use [System.is24HourClock](#is24hourclock9). 3522 3523**System capability**: SystemCapability.Global.I18n 3524 3525**Return value** 3526 3527| Type | Description | 3528| ------- | ---------------------------------------- | 3529| boolean | **true** if the 24-hour clock is used, and **false** otherwise.| 3530 3531**Example** 3532 ```ts 3533 let is24HourClock: boolean = i18n.is24HourClock(); 3534 ``` 3535 3536 3537## i18n.set24HourClock<sup>(deprecated)</sup> 3538 3539set24HourClock(option: boolean): boolean 3540 3541Sets the 24-hour clock. 3542 3543This API is deprecated since API version 9. The substitute API is available only for system applications. 3544 3545**Permission required**: ohos.permission.UPDATE_CONFIGURATION 3546 3547**System capability**: SystemCapability.Global.I18n 3548 3549**Parameters** 3550 3551| Name | Type | Mandatory | Description | 3552| ------ | ------- | ---- | ---------------------------------------- | 3553| option | boolean | Yes | Whether to enable the 24-hour clock. The value **true** means to enable the 24-hour clock, and the value **false** means the opposite.| 3554 3555**Return value** 3556 3557| Type | Description | 3558| ------- | ----------------------------- | 3559| boolean | **true** if the setting is successful, and **false** otherwise.| 3560 3561**Example** 3562 ```ts 3563 // Set the system time to the 24-hour clock. 3564 let success: boolean = i18n.set24HourClock(true); 3565 ``` 3566 3567 3568## i18n.addPreferredLanguage<sup>(deprecated)</sup> 3569 3570addPreferredLanguage(language: string, index?: number): boolean 3571 3572Adds a preferred language to the specified position on the preferred language list. 3573 3574This API is supported since API version 8 and is deprecated since API version 9. The substitute API is available only for system applications. 3575 3576**Permission required**: ohos.permission.UPDATE_CONFIGURATION 3577 3578**System capability**: SystemCapability.Global.I18n 3579 3580**Parameters** 3581 3582| Name | Type | Mandatory | Description | 3583| -------- | ------ | ---- | ---------- | 3584| language | string | Yes | Preferred language to add. | 3585| index | number | No | Position to which the preferred language is added. The default value is the length of the preferred language list.| 3586 3587**Return value** 3588 3589| Type | Description | 3590| ------- | ----------------------------- | 3591| boolean | **true** if the operation is successful, and **false** otherwise.| 3592 3593**Example** 3594 ```ts 3595 // Add zh-CN to the preferred language list. 3596 let language: string = 'zh-CN'; 3597 let index: number = 0; 3598 let success: boolean = i18n.addPreferredLanguage(language, index); 3599 ``` 3600 3601 3602## i18n.removePreferredLanguage<sup>(deprecated)</sup> 3603 3604removePreferredLanguage(index: number): boolean 3605 3606Deletes a preferred language from the specified position on the preferred language list. 3607 3608This API is supported since API version 8 and is deprecated since API version 9. The substitute API is available only for system applications. 3609 3610**Permission required**: ohos.permission.UPDATE_CONFIGURATION 3611 3612**System capability**: SystemCapability.Global.I18n 3613 3614**Parameters** 3615 3616| Name | Type | Mandatory | Description | 3617| ----- | ------ | ---- | --------------------- | 3618| index | number | Yes | Position of the preferred language to delete.| 3619 3620**Return value** 3621 3622| Type | Description | 3623| ------- | ----------------------------- | 3624| boolean | **true** if the operation is successful, and **false** otherwise.| 3625 3626**Example** 3627 ```ts 3628 // Delete the first preferred language from the preferred language list. 3629 let index: number = 0; 3630 let success: boolean = i18n.removePreferredLanguage(index); 3631 ``` 3632 3633 3634## i18n.getPreferredLanguageList<sup>(deprecated)</sup> 3635 3636getPreferredLanguageList(): Array<string> 3637 3638Obtains the list of preferred languages. 3639 3640This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [System.getPreferredLanguageList](#getpreferredlanguagelist9). 3641 3642**System capability**: SystemCapability.Global.I18n 3643 3644**Return value** 3645 3646| Type | Description | 3647| ------------------- | --------- | 3648| Array<string> | List of preferred languages.| 3649 3650**Example** 3651 ```ts 3652 let preferredLanguageList: Array<string> = i18n.getPreferredLanguageList(); 3653 ``` 3654 3655 3656## i18n.getFirstPreferredLanguage<sup>(deprecated)</sup> 3657 3658getFirstPreferredLanguage(): string 3659 3660Obtains the first language in the preferred language list. 3661 3662This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [System.getFirstPreferredLanguage](#getfirstpreferredlanguage9). 3663 3664**System capability**: SystemCapability.Global.I18n 3665 3666**Return value** 3667 3668| Type | Description | 3669| ------ | -------------- | 3670| string | First language in the preferred language list.| 3671 3672**Example** 3673 ```ts 3674 let firstPreferredLanguage: string = i18n.getFirstPreferredLanguage(); 3675 ``` 3676 3677 3678## Util<sup>(deprecated)</sup> 3679 3680 3681### unitConvert<sup>(deprecated)</sup> 3682 3683unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale: string, style?: string): string 3684 3685Converts one measurement unit into another and formats the unit based on the specified locale and style. 3686 3687This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [unitConvert](#unitconvert9). 3688 3689**System capability**: SystemCapability.Global.I18n 3690 3691**Parameters** 3692 3693| Name | Type | Mandatory | Description | 3694| -------- | ---------------------- | ---- | ---------------------------------------- | 3695| fromUnit | [UnitInfo](#unitinfo8) | Yes | Measurement unit to be converted. | 3696| toUnit | [UnitInfo](#unitinfo8) | Yes | Measurement unit to be converted to. | 3697| value | number | Yes | Value of the measurement unit to be converted. | 3698| locale | string | Yes | Locale used for formatting, for example, **zh-Hans-CN**. | 3699| style | string | No | Style used for formatting. The value can be **long**, **short**, or **narrow**. The default value is **short**.| 3700 3701**Return value** 3702 3703| Type | Description | 3704| ------ | ----------------------- | 3705| string | String obtained after formatting based on the measurement unit specified by **toUnit**.| 3706 3707 3708## Character<sup>(deprecated)</sup> 3709 3710 3711### isDigit<sup>(deprecated)</sup> 3712 3713isDigit(char: string): boolean 3714 3715Checks whether the input string is composed of digits. 3716 3717This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [isDigit](#isdigit9). 3718 3719**System capability**: SystemCapability.Global.I18n 3720 3721**Parameters** 3722 3723| Name | Type | Mandatory | Description | 3724| ---- | ------ | ---- | ----- | 3725| char | string | Yes | Input character.| 3726 3727**Return value** 3728 3729| Type | Description | 3730| ------- | ------------------------------------ | 3731| boolean | **true** if the input character is a digit, and **false** otherwise.| 3732 3733 3734### isSpaceChar<sup>(deprecated)</sup> 3735 3736isSpaceChar(char: string): boolean 3737 3738Checks whether the input character is a space. 3739 3740This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [isSpaceChar](#isspacechar9). 3741 3742**System capability**: SystemCapability.Global.I18n 3743 3744**Parameters** 3745 3746| Name | Type | Mandatory | Description | 3747| ---- | ------ | ---- | ----- | 3748| char | string | Yes | Input character.| 3749 3750**Return value** 3751 3752| Type | Description | 3753| ------- | -------------------------------------- | 3754| boolean | **true** if the input character is a space, and **false** otherwise.| 3755 3756 3757### isWhitespace<sup>(deprecated)</sup> 3758 3759isWhitespace(char: string): boolean 3760 3761Checks whether the input character is a white space. 3762 3763This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [isWhitespace](#iswhitespace9). 3764 3765**System capability**: SystemCapability.Global.I18n 3766 3767**Parameters** 3768 3769| Name | Type | Mandatory | Description | 3770| ---- | ------ | ---- | ----- | 3771| char | string | Yes | Input character.| 3772 3773**Return value** 3774 3775| Type | Description | 3776| ------- | -------------------------------------- | 3777| boolean | **true** if the input character is a white space, and **false** otherwise.| 3778 3779 3780### isRTL<sup>(deprecated)</sup> 3781 3782isRTL(char: string): boolean 3783 3784Checks whether the input character is of the right to left (RTL) language. 3785 3786This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [isRTL](#isrtl9). 3787 3788**System capability**: SystemCapability.Global.I18n 3789 3790**Parameters** 3791 3792| Name | Type | Mandatory | Description | 3793| ---- | ------ | ---- | ----- | 3794| char | string | Yes | Input character.| 3795 3796**Return value** 3797 3798| Type | Description | 3799| ------- | ---------------------------------------- | 3800| boolean | **true** if the input character is of the RTL language, and **false** otherwise.| 3801 3802 3803### isIdeograph<sup>(deprecated)</sup> 3804 3805isIdeograph(char: string): boolean 3806 3807Checks whether the input character is an ideographic character. 3808 3809This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [isIdeograph](#isideograph9). 3810 3811**System capability**: SystemCapability.Global.I18n 3812 3813**Parameters** 3814 3815| Name | Type | Mandatory | Description | 3816| ---- | ------ | ---- | ----- | 3817| char | string | Yes | Input character.| 3818 3819**Return value** 3820 3821| Type | Description | 3822| ------- | ---------------------------------------- | 3823| boolean | **true** if the input character an ideographic character, and **false** otherwise.| 3824 3825 3826### isLetter<sup>(deprecated)</sup> 3827 3828isLetter(char: string): boolean 3829 3830Checks whether the input character is a letter. 3831 3832This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [isLetter](#isletter9). 3833 3834**System capability**: SystemCapability.Global.I18n 3835 3836**Parameters** 3837 3838| Name | Type | Mandatory | Description | 3839| ---- | ------ | ---- | ----- | 3840| char | string | Yes | Input character.| 3841 3842**Return value** 3843 3844| Type | Description | 3845| ------- | ------------------------------------ | 3846| boolean | **true** if the input character a letter, and **false** otherwise.| 3847 3848 3849### isLowerCase<sup>(deprecated)</sup> 3850 3851isLowerCase(char: string): boolean 3852 3853Checks whether the input character is a lowercase letter. 3854 3855This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [isLowerCase](#islowercase9). 3856 3857**System capability**: SystemCapability.Global.I18n 3858 3859**Parameters** 3860 3861| Name | Type | Mandatory | Description | 3862| ---- | ------ | ---- | ----- | 3863| char | string | Yes | Input character.| 3864 3865**Return value** 3866 3867| Type | Description | 3868| ------- | ---------------------------------------- | 3869| boolean | **true** if the input character a lowercase letter, and **false** otherwise.| 3870 3871 3872### isUpperCase<sup>(deprecated)</sup> 3873 3874isUpperCase(char: string): boolean 3875 3876Checks whether the input character is an uppercase letter. 3877 3878This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [isUpperCase](#isuppercase9). 3879 3880**System capability**: SystemCapability.Global.I18n 3881 3882**Parameters** 3883 3884| Name | Type | Mandatory | Description | 3885| ---- | ------ | ---- | ----- | 3886| char | string | Yes | Input character.| 3887 3888**Return value** 3889 3890| Type | Description | 3891| ------- | ---------------------------------------- | 3892| boolean | **true** if the input character an uppercase letter, and **false** otherwise.| 3893 3894 3895### getType<sup>(deprecated)</sup> 3896 3897getType(char: string): string 3898 3899Obtains the type of the input string. 3900 3901This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [getType](#gettype9). 3902 3903**System capability**: SystemCapability.Global.I18n 3904 3905**Parameters** 3906 3907| Name | Type | Mandatory | Description | 3908| ---- | ------ | ---- | ----- | 3909| char | string | Yes | Input character.| 3910 3911**Return value** 3912 3913| Type | Description | 3914| ------ | ----------- | 3915| string | Type of the input character.| 3916 3917<!--no_check-->