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