1# @ohos.i18n (Internationalization) (System API) 2 3 This module provides system-related or enhanced i18n capabilities, such as locale management, phone number formatting, and calendar, through supplementary i18n APIs that are not defined in ECMA 402. The [intl](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> - 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. 7> 8> - Since API version 11, some APIs of this module are supported in ArkTS widgets. 9> 10> - This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.i18n (Internationalization)](js-apis-intl.md). 11 12 13## Modules to Import 14 15```ts 16import { i18n } from '@kit.LocalizationKit'; 17``` 18 19## System<sup>9+</sup> 20 21### setSystemLanguage<sup>9+</sup> 22 23static setSystemLanguage(language: string): void 24 25Sets the system language. Currently, this API does not support real-time updating of the system language. 26 27To listen for system language changes, enable listening for [COMMON_EVENT_LOCALE_CHANGED](../apis-basic-services-kit/common_event/commonEventManager-definitions.md#common_event_locale_changed). 28 29**System API**: This is a system API. 30 31**Permission required**: ohos.permission.UPDATE_CONFIGURATION 32 33**System capability**: SystemCapability.Global.I18n 34 35**Parameters** 36 37| Name | Type | Mandatory | Description | 38| -------- | ------ | ---- | ----- | 39| language | string | Yes | Valid language ID.| 40 41**Error codes** 42 43For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 44 45| ID | Error Message | 46| ------ | ---------------------- | 47| 201 | Permission verification failed. The application does not have the permission required to call the API. | 48| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 49| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 50 51**Example** 52 ```ts 53 import { BusinessError, commonEventManager } from '@kit.BasicServicesKit'; 54 55 // Set the system language 56 try { 57 i18n.System.setSystemLanguage('zh'); // Set the current system language to zh. 58 } catch(error) { 59 let err: BusinessError = error as BusinessError; 60 console.error(`call System.setSystemLanguage failed, error code: ${err.code}, message: ${err.message}.`); 61 } 62 63 // Subscribe to a common event. 64 let subscriber: commonEventManager.CommonEventSubscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription. 65 let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = { // Define subscriber information. 66 events: [commonEventManager.Support.COMMON_EVENT_LOCALE_CHANGED] 67 }; 68 commonEventManager.createSubscriber(subscribeInfo).then((commonEventSubscriber:commonEventManager.CommonEventSubscriber) => { // Create a subscriber. 69 console.info("createSubscriber"); 70 subscriber = commonEventSubscriber; 71 commonEventManager.subscribe(subscriber, (err, data) => { 72 if (err) { 73 console.error(`Failed to subscribe common event. error code: ${err.code}, message: ${err.message}.`); 74 return; 75 } 76 console.info("the subscribed event has occurred."); // Triggered when the subscribed event occurs. 77 }) 78 }).catch((err: BusinessError) => { 79 console.error(`createSubscriber failed, code is ${err.code}, message is ${err.message}`); 80 }); 81 ``` 82 83### setSystemRegion<sup>9+</sup> 84 85static setSystemRegion(region: string): void 86 87Sets the system region. 88 89To listen for system region changes, enable listening for [COMMON_EVENT_LOCALE_CHANGED](../apis-basic-services-kit/common_event/commonEventManager-definitions.md#common_event_locale_changed). 90 91**System API**: This is a system API. 92 93**Permission required**: ohos.permission.UPDATE_CONFIGURATION 94 95**System capability**: SystemCapability.Global.I18n 96 97**Parameters** 98 99| Name | Type | Mandatory | Description | 100| ------ | ------ | ---- | ----- | 101| region | string | Yes | Valid region ID.| 102 103**Error codes** 104 105For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 106 107| ID | Error Message | 108| ------ | ---------------------- | 109| 201 | Permission verification failed. The application does not have the permission required to call the API. | 110| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 111| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 112 113**Example** 114 ```ts 115 import { BusinessError } from '@kit.BasicServicesKit'; 116 117 try { 118 i18n.System.setSystemRegion('CN'); // Set the current system region to CN. 119 } catch(error) { 120 let err: BusinessError = error as BusinessError; 121 console.error(`call System.setSystemRegion failed, error code: ${err.code}, message: ${err.message}.`); 122 } 123 ``` 124 125 126 127### setSystemLocale<sup>9+</sup> 128 129static setSystemLocale(locale: string): void 130 131Sets the system locale. 132 133To listen for system locale changes, enable listening for [COMMON_EVENT_LOCALE_CHANGED](../apis-basic-services-kit/common_event/commonEventManager-definitions.md#common_event_locale_changed). 134 135**System API**: This is a system API. 136 137**Permission required**: ohos.permission.UPDATE_CONFIGURATION 138 139**System capability**: SystemCapability.Global.I18n 140 141**Parameters** 142 143| Name | Type | Mandatory | Description | 144| ------ | ------ | ---- | --------------- | 145| locale | string | Yes | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region.| 146 147**Error codes** 148 149For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 150 151| ID | Error Message | 152| ------ | ---------------------- | 153| 201 | Permission verification failed. The application does not have the permission required to call the API. | 154| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 155| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 156 157**Example** 158 ```ts 159 import { BusinessError } from '@kit.BasicServicesKit'; 160 161 try { 162 i18n.System.setSystemLocale('zh-CN'); // Set the current system locale to zh-CN. 163 } catch(error) { 164 let err: BusinessError = error as BusinessError; 165 console.error(`call System.setSystemLocale failed, error code: ${err.code}, message: ${err.message}.`); 166 } 167 ``` 168 169 170### set24HourClock<sup>9+</sup> 171 172static set24HourClock(option: boolean): void 173 174Sets the system time to the 24-hour clock. 175 176**System API**: This is a system API. 177 178**Permission required**: ohos.permission.UPDATE_CONFIGURATION 179 180**System capability**: SystemCapability.Global.I18n 181 182**Parameters** 183 184| Name | Type | Mandatory | Description | 185| ------ | ------- | ---- | ---------------------------------------- | 186| 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.| 187 188**Error codes** 189 190For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 191 192| ID | Error Message | 193| ------ | ---------------------- | 194| 201 | Permission verification failed. The application does not have the permission required to call the API. | 195| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 196| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 197 198**Example** 199 ```ts 200 import { BusinessError } from '@kit.BasicServicesKit'; 201 202 // Set the system time to the 24-hour clock. 203 try { 204 i18n.System.set24HourClock(true); 205 } catch(error) { 206 let err: BusinessError = error as BusinessError; 207 console.error(`call System.set24HourClock failed, error code: ${err.code}, message: ${err.message}.`); 208 } 209 ``` 210 211### addPreferredLanguage<sup>9+</sup> 212 213static addPreferredLanguage(language: string, index?: number): void 214 215Adds a preferred language to the specified position on the preferred language list. 216 217**System API**: This is a system API. 218 219**Permission required**: ohos.permission.UPDATE_CONFIGURATION 220 221**System capability**: SystemCapability.Global.I18n 222 223**Parameters** 224 225| Name | Type | Mandatory | Description | 226| -------- | ------ | ---- | ---------- | 227| language | string | Yes | Valid ID of the language to be added as a preferred language. | 228| index | number | No | Position to which the preferred language is added. The default value is the length of the preferred language list.| 229 230**Error codes** 231 232For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 233 234| ID | Error Message | 235| ------ | ---------------------- | 236| 201 | Permission verification failed. The application does not have the permission required to call the API. | 237| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 238| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 239 240**Example** 241 ```ts 242 import { BusinessError } from '@kit.BasicServicesKit'; 243 244 // Add zh-CN to the preferred language list. 245 let language = 'zh-CN'; 246 let index = 0; 247 try { 248 i18n.System.addPreferredLanguage(language, index); // Add zh-CN to the first place in the preferred language list. 249 } catch(error) { 250 let err: BusinessError = error as BusinessError; 251 console.error(`call System.addPreferredLanguage failed, error code: ${err.code}, message: ${err.message}.`); 252 } 253 ``` 254 255### removePreferredLanguage<sup>9+</sup> 256 257static removePreferredLanguage(index: number): void 258 259Deletes a preferred language from the specified position on the preferred language list. 260 261**System API**: This is a system API. 262 263**Permission required**: ohos.permission.UPDATE_CONFIGURATION 264 265**System capability**: SystemCapability.Global.I18n 266 267**Parameters** 268 269| Name | Type | Mandatory | Description | 270| ----- | ------ | ---- | --------------------- | 271| index | number | Yes | Position of the preferred language to delete.| 272 273**Error codes** 274 275For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 276 277| ID | Error Message | 278| ------ | ---------------------- | 279| 201 | Permission verification failed. The application does not have the permission required to call the API. | 280| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 281| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 282 283**Example** 284 ```ts 285 import { BusinessError } from '@kit.BasicServicesKit'; 286 287 // Delete the first preferred language from the preferred language list. 288 let index: number = 0; 289 try { 290 i18n.System.removePreferredLanguage(index); 291 } catch(error) { 292 let err: BusinessError = error as BusinessError; 293 console.error(`call System.removePreferredLanguage failed, error code: ${err.code}, message: ${err.message}.`); 294 } 295 ``` 296 297### setUsingLocalDigit<sup>9+</sup> 298 299static setUsingLocalDigit(flag: boolean): void 300 301Specifies whether to enable use of local digits. 302 303**System API**: This is a system API. 304 305**Permission required**: ohos.permission.UPDATE_CONFIGURATION 306 307**System capability**: SystemCapability.Global.I18n 308 309**Parameters** 310 311| Name | Type | Mandatory | Description | 312| ---- | ------- | ---- | ------------------------------- | 313| flag | boolean | Yes | Whether to turn on the local digit switch. The value **true** means to turn on the local digit switch, and the value **false** indicates the opposite.| 314 315**Error codes** 316 317For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 318 319| ID | Error Message | 320| ------ | ---------------------- | 321| 201 | Permission verification failed. The application does not have the permission required to call the API. | 322| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 323| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 324 325**Example** 326 ```ts 327 import { BusinessError } from '@kit.BasicServicesKit'; 328 329 try { 330 i18n.System.setUsingLocalDigit(true); // Enable the local digit switch. 331 } catch(error) { 332 let err: BusinessError = error as BusinessError; 333 console.error(`call System.setUsingLocalDigit failed, error code: ${err.code}, message: ${err.message}.`); 334 } 335 ``` 336 337## SystemLocaleManager<sup>10+</sup> 338 339### constructor<sup>10+</sup> 340 341constructor() 342 343Creates a **SystemLocaleManager** object. 344 345**System API**: This is a system API. 346 347**System capability**: SystemCapability.Global.I18n 348 349**Example** 350 ```ts 351 let systemLocaleManager: i18n.SystemLocaleManager = new i18n.SystemLocaleManager(); 352 ``` 353 354 355### getLanguageInfoArray<sup>10+</sup> 356 357getLanguageInfoArray(languages: Array<string>, options?: SortOptions): Array<LocaleItem> 358 359Obtains the language sorting array. 360 361**System API**: This is a system API. 362 363**System capability**: SystemCapability.Global.I18n 364 365**Parameters** 366 367| Name | Type | Mandatory| Description | 368| --------- | ------------- | ---- | ------------- | 369| languages | Array<string> | Yes | Valid IDs of the languages to be sorted.| 370| options | [SortOptions](#sortoptions10) | No | Language sorting option.| 371 372**Return value** 373 374| Type | Description | 375| ----------------- | -------------------- | 376| Array<[LocaleItem](#localeitem10)> | Language list after sorting.| 377 378**Error codes** 379 380For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 381 382| ID | Error Message | 383| ------ | ---------------------- | 384| 202 | Permission verification failed. A non-system application calls a system API. | 385| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 386| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 387 388**Example** 389 ```ts 390 import { BusinessError } from '@kit.BasicServicesKit'; 391 392 // Assume that the system language is zh-Hans, the system region is CN, and the system locale is zh-Hans-CN. 393 let systemLocaleManager: i18n.SystemLocaleManager = new i18n.SystemLocaleManager(); 394 let languages: string[] = ["zh-Hans", "en-US", "pt", "ar"]; 395 let sortOptions: i18n.SortOptions = {locale: "zh-Hans-CN", isUseLocalName: true, isSuggestedFirst: true}; 396 try { 397 // The language list after sorting is [zh-Hans, en-US, pt, ar]. 398 let sortedLanguages: Array<i18n.LocaleItem> = systemLocaleManager.getLanguageInfoArray(languages, sortOptions); 399 } catch(error) { 400 let err: BusinessError = error as BusinessError; 401 console.error(`call systemLocaleManager.getLanguageInfoArray failed, error code: ${err.code}, message: ${err.message}.`); 402 } 403 ``` 404 405 406### getRegionInfoArray<sup>10+</sup> 407 408getRegionInfoArray(regions: Array<string>, options?: SortOptions): Array<LocaleItem> 409 410Obtains the country/region sorting array. 411 412**System API**: This is a system API. 413 414**System capability**: SystemCapability.Global.I18n 415 416**Parameters** 417 418| Name | Type | Mandatory| Description | 419| --------- | ------------- | ---- | ------------- | 420| regions | Array<string> | Yes | Valid IDs of the countries or regions to be sorted.| 421| options | [SortOptions](#sortoptions10) | No | Country/region sorting option.<br>The default value of **locale** is the system locale, the default value of **isUseLocalName** is **false**, and the default value of **isSuggestedFirst** is **true**.| 422 423**Return value** 424 425| Type | Description | 426| ----------------- | -------------------- | 427| Array<[LocaleItem](#localeitem10)> | Country/region list after sorting.| 428 429**Error codes** 430 431For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 432 433| ID | Error Message | 434| ------ | ---------------------- | 435| 202 | Permission verification failed. A non-system application calls a system API. | 436| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 437| 890001 | Invalid parameter. Possible causes: Parameter verification failed. | 438 439**Example** 440 ```ts 441 import { BusinessError } from '@kit.BasicServicesKit'; 442 443 // Assume that the system language is zh-Hans, the system region is CN, and the system locale is zh-Hans-CN. 444 let systemLocaleManager: i18n.SystemLocaleManager = new i18n.SystemLocaleManager(); 445 let regions: string[] = ["CN", "US", "PT", "EG"]; 446 let sortOptions: i18n.SortOptions = {locale: "zh-Hans-CN", isUseLocalName: false, isSuggestedFirst: true}; 447 try { 448 // The country/region list after sorting is [CN, EG, US, PT]. 449 let sortedRegions: Array<i18n.LocaleItem> = systemLocaleManager.getRegionInfoArray(regions, sortOptions); 450 } catch(error) { 451 let err: BusinessError = error as BusinessError; 452 console.error(`call systemLocaleManager.getRegionInfoArray failed, error code: ${err.code}, message: ${err.message}.`); 453 } 454 ``` 455 456### getTimeZoneCityItemArray<sup>10+</sup> 457 458static getTimeZoneCityItemArray(): Array<TimeZoneCityItem> 459 460Obtains the array of time zone city items after sorting. 461 462**System API**: This is a system API. 463 464**System capability**: SystemCapability.Global.I18n 465 466**Return value** 467 468| Type | Description | 469| ----------------- | -------------------- | 470| Array<[TimeZoneCityItem](#timezonecityitem10)> | Array of time zone city items.| 471 472**Error codes** 473 474For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md). 475 476| ID | Error Message | 477| ------ | ---------------------- | 478| 202 | Permission verification failed. A non-system application calls a system API. | 479 480**Example** 481 ```ts 482 import { BusinessError } from '@kit.BasicServicesKit'; 483 484 try { 485 let timeZoneCityItemArray: Array<i18n.TimeZoneCityItem> = i18n.SystemLocaleManager.getTimeZoneCityItemArray(); 486 for (let i = 0; i < timeZoneCityItemArray.length; i++) { 487 console.log(timeZoneCityItemArray[i].zoneId + ", " + timeZoneCityItemArray[i].cityId + ", " + timeZoneCityItemArray[i].cityDisplayName + 488 ", " + timeZoneCityItemArray[i].offset + "\r\n"); 489 } 490 } catch(error) { 491 let err: BusinessError = error as BusinessError; 492 console.error(`call SystemLocaleManager.getTimeZoneCityItemArray failed, error code: ${err.code}, message: ${err.message}.`); 493 } 494 ``` 495 496## LocaleItem<sup>10+</sup> 497 498Represents the list of languages or countries/regions sorted by **SystemLocaleManager**. 499 500**System API**: This is a system API. 501 502**System capability**: SystemCapability.Global.I18n 503 504| Name | Type | Mandatory | Description | 505| --------------- | --------------- | ------ | --------------------------------------- | 506| id | string | Yes | Language code or country/region code, for example, **zh** or **CN**. | 507| suggestionType | [SuggestionType](#suggestiontype10) | Yes | Language or country/region suggestion type. | 508| displayName | string | Yes | Displayed name of ID in the locale of **SystemLocaleManager**.| 509| localName | string | No | Local name of the ID. | 510 511## TimeZoneCityItem<sup>10+</sup> 512 513Represents the time zone and city combination information. 514 515**System API**: This is a system API. 516 517**System capability**: SystemCapability.Global.I18n 518 519| Name | Type | Mandatory | Description | 520| --------------- | --------------- | ------ | --------------------------------------- | 521| zoneId | string | Yes | Time zone ID, for example, **Asia/Shanghai**. | 522| cityId | string | Yes | City ID, for example, **Shanghai**. | 523| cityDisplayName | string | Yes | Displayed name of the city ID in the system locale. | 524| offset | int | Yes | Offset of the time zone ID. | 525| zoneDisplayName | string | Yes | Displayed name of the time zone ID in the system locale. | 526| rawOffset | int | No | Fixed offset of the time zone ID. | 527 528 529## SuggestionType<sup>10+</sup> 530 531Represents the language or country/region suggestion type. 532 533**System API**: This is a system API. 534 535**System capability**: SystemCapability.Global.I18n 536 537| Name | Value | Description | 538| ---------------------- | ---- | ---- | 539| SUGGESTION_TYPE_NONE | 0x00 | Not a recommended language or country/region.| 540| SUGGESTION_TYPE_RELATED| 0x01 | Country/region recommended by the system language or language recommended by the system country/region.| 541| SUGGESTION_TYPE_SIM | 0x02 | Language recommended by the country/region of the SIM card.| 542 543 544## SortOptions<sup>10+<sup> 545 546Represents the language or country/region sorting option. 547 548**System API**: This is a system API. 549 550**System capability**: SystemCapability.Global.I18n 551 552| Name | Type | Mandatory| Description | 553| --------------- | --------------- | ---- | --------------------------------------- | 554| 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 of **locale** is the system locale. | 555| isUseLocalName | boolean | No | Whether to use the local name for sorting.<br>If **getLanguageInfoArray** is called, the default value of **isUseLocalName** is **true**.<br>If **getRegionInfoArray** is called, the default value of **isUseLocalName** is **false**. | 556| isSuggestedFirst | boolean | No | Whether to move the recommended language or country/region to the top in the sorting result.<br>The default value of **isSuggestedFirst** is **true**. | 557