1# @ohos.i18n (国际化-I18n)(系统接口)
2
3 本模块提供系统相关的或者增强的国际化能力，包括区域管理、电话号码处理、日历等，相关接口为ECMA 402标准中未定义的补充接口。[Intl模块](js-apis-intl.md)提供了ECMA 402标准定义的基础国际化接口，与本模块共同使用可提供完整地国际化支持能力。
4
5>  **说明：**
6>  - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
7>
8>  - 从API version 11开始，本模块部分接口支持在ArkTS卡片中使用。
9>
10>  - 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.i18n (国际化-I18n)](js-apis-intl.md)。
11
12
13## 导入模块
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
25设置系统语言。当前调用该接口不支持系统界面语言的实时刷新。
26
27若设置系统语言后，需要[监听事件](../apis-basic-services-kit/common_event/commonEventManager-definitions.md#common_event_locale_changed)OHOS::EventFwk::CommonEventSupport::COMMON_EVENT_LOCALE_CHANGED，可以[订阅](../apis-basic-services-kit/js-apis-commonEventManager.md#commoneventmanagercreatesubscriber-1)该事件。
28
29**系统接口**：此接口为系统接口。
30
31**需要权限**：ohos.permission.UPDATE_CONFIGURATION
32
33**系统能力**：SystemCapability.Global.I18n
34
35**参数：**
36
37| 参数名      | 类型     | 必填   | 说明    |
38| -------- | ------ | ---- | ----- |
39| language | string | 是    | 合法的语言ID。 |
40
41**错误码：**
42
43以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
44
45| 错误码ID  | 错误信息                   |
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**示例：**
52  ```ts
53  import { BusinessError, commonEventManager } from '@kit.BasicServicesKit';
54
55  // 设置系统语言
56  try {
57    i18n.System.setSystemLanguage('zh'); // 设置系统当前语言为 "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  // 订阅公共事件
64  let subscriber: commonEventManager.CommonEventSubscriber; // 用于保存创建成功的订阅者对象，后续使用其完成订阅及退订的动作
65  let subscribeInfo: commonEventManager.CommonEventSubscribeInfo = { // 订阅者信息
66    events: [commonEventManager.Support.COMMON_EVENT_LOCALE_CHANGED]
67  };
68  commonEventManager.createSubscriber(subscribeInfo).then((commonEventSubscriber:commonEventManager.CommonEventSubscriber) => { // 创建订阅者
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."); // 订阅的事件发生时执行
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
87设置系统区域。
88
89**系统接口**：此接口为系统接口。
90
91**需要权限**：ohos.permission.UPDATE_CONFIGURATION
92
93**系统能力**：SystemCapability.Global.I18n
94
95**参数：**
96
97| 参数名    | 类型     | 必填   | 说明    |
98| ------ | ------ | ---- | ----- |
99| region | string | 是    | 合法的地区ID。 |
100
101**错误码：**
102
103以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
104
105| 错误码ID  | 错误信息                   |
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**示例：**
112  ```ts
113  import { BusinessError } from '@kit.BasicServicesKit';
114
115  try {
116    i18n.System.setSystemRegion('CN');  // 设置系统当前地区为 "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
129设置系统Locale。
130
131**系统接口**：此接口为系统接口。
132
133**需要权限**：ohos.permission.UPDATE_CONFIGURATION
134
135**系统能力**：SystemCapability.Global.I18n
136
137**参数：**
138
139| 参数名    | 类型     | 必填   | 说明              |
140| ------ | ------ | ---- | --------------- |
141| locale | string | 是    | 合法的区域ID，例如zh-CN。 |
142
143**错误码：**
144
145以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
146
147| 错误码ID  | 错误信息                   |
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**示例：**
154  ```ts
155  import { BusinessError } from '@kit.BasicServicesKit';
156
157  try {
158    i18n.System.setSystemLocale('zh-CN');  // 设置系统当前Locale为 "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
170设置系统时间为24小时。
171
172**系统接口**：此接口为系统接口。
173
174**需要权限**：ohos.permission.UPDATE_CONFIGURATION
175
176**系统能力**：SystemCapability.Global.I18n
177
178**参数：**
179
180| 参数名    | 类型      | 必填   | 说明                                       |
181| ------ | ------- | ---- | ---------------------------------------- |
182| option | boolean | 是    | option为true，表示开启系统24小时制开关；返回false，表示关闭系统24小时开关。 |
183
184**错误码：**
185
186以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
187
188| 错误码ID  | 错误信息                   |
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**示例：**
195  ```ts
196  import { BusinessError } from '@kit.BasicServicesKit';
197
198  // 将系统时间设置为24小时制
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
211在系统偏好语言列表中的指定位置添加偏好语言。
212
213**系统接口**：此接口为系统接口。
214
215**需要权限**：ohos.permission.UPDATE_CONFIGURATION
216
217**系统能力**：SystemCapability.Global.I18n
218
219**参数：**
220
221| 参数名      | 类型     | 必填   | 说明         |
222| -------- | ------ | ---- | ---------- |
223| language | string | 是    | 待添加的偏好语言，要求是合法的语言ID。  |
224| index    | number | 否    | 偏好语言的添加位置。默认值：系统偏好语言列表长度。 |
225
226**错误码：**
227
228以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
229
230| 错误码ID  | 错误信息                   |
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**示例：**
237  ```ts
238  import { BusinessError } from '@kit.BasicServicesKit';
239
240  // 将语言zh-CN添加到系统偏好语言列表中
241  let language = 'zh-CN';
242  let index = 0;
243  try {
244    i18n.System.addPreferredLanguage(language, index); // 将zh-CN添加到系统偏好语言列表的第1位
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
255删除系统偏好语言列表中指定位置的偏好语言。
256
257**系统接口**：此接口为系统接口。
258
259**需要权限**：ohos.permission.UPDATE_CONFIGURATION
260
261**系统能力**：SystemCapability.Global.I18n
262
263**参数：**
264
265| 参数名   | 类型     | 必填   | 说明                    |
266| ----- | ------ | ---- | --------------------- |
267| index | number | 是    | 待删除偏好语言在系统偏好语言列表中的位置。 |
268
269**错误码：**
270
271以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
272
273| 错误码ID  | 错误信息                   |
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**示例：**
280  ```ts
281  import { BusinessError } from '@kit.BasicServicesKit';
282
283  // 删除系统偏好语言列表中的第一个偏好语言
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
297设置系统是否使用本地数字。
298
299**系统接口**：此接口为系统接口。
300
301**需要权限**：ohos.permission.UPDATE_CONFIGURATION
302
303**系统能力**：SystemCapability.Global.I18n
304
305**参数：**
306
307| 参数名  | 类型      | 必填   | 说明                              |
308| ---- | ------- | ---- | ------------------------------- |
309| flag | boolean | 是    | true表示打开本地数字开关，false表示关闭本地数字开关。 |
310
311**错误码：**
312
313以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
314
315| 错误码ID  | 错误信息                   |
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**示例：**
322  ```ts
323  import { BusinessError } from '@kit.BasicServicesKit';
324
325  try {
326    i18n.System.setUsingLocalDigit(true); // 打开本地化数字开关
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
339创建SystemLocaleManager对象。
340
341**系统接口**：此接口为系统接口。
342
343**系统能力**：SystemCapability.Global.I18n
344
345**示例：**
346  ```ts
347  let systemLocaleManager: i18n.SystemLocaleManager = new i18n.SystemLocaleManager();
348  ```
349
350
351### getLanguageInfoArray<sup>10+</sup>
352
353getLanguageInfoArray(languages: Array&lt;string&gt;, options?: SortOptions): Array&lt;LocaleItem&gt;
354
355获取语言排序数组。
356
357**系统接口**：此接口为系统接口。
358
359**系统能力**：SystemCapability.Global.I18n
360
361**参数：**
362
363|   参数名  |      类型      | 必填 |     说明      |
364| --------- | ------------- | ---- | ------------- |
365| languages | Array&lt;string&gt; | 是   | 待排序语言列表，要求是合法的语言ID。|
366| options   | [SortOptions](#sortoptions10)   | 否   | 语言排序选项。 |
367
368**返回值：**
369
370|       类型        |         说明          |
371| ----------------- | -------------------- |
372| Array&lt;[LocaleItem](#localeitem10)&gt; | 排序后的语言列表信息。 |
373
374**错误码：**
375
376以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
377
378| 错误码ID  | 错误信息                   |
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**示例：**
385  ```ts
386  import { BusinessError } from '@kit.BasicServicesKit';
387
388  // 当系统语言为zh-Hans，系统地区为CN，系统Locale为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      // 排序后的语言顺序为: [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&lt;string&gt;, options?: SortOptions): Array&lt;LocaleItem&gt;
405
406获取国家或地区排序数组。
407
408**系统接口**：此接口为系统接口。
409
410**系统能力**：SystemCapability.Global.I18n
411
412**参数：**
413
414|   参数名  |      类型      | 必填 |     说明      |
415| --------- | ------------- | ---- | ------------- |
416| regions   | Array&lt;string&gt; | 是   | 待排序的国家或地区列表，要求是合法的国家或地区ID。|
417| options   | [SortOptions](#sortoptions10)   | 否   | 国家或地区排序选项。默认值：locale的默认值为系统Locale，isUseLocalName的默认值为false，isSuggestedFirst的默认值为true。 |
418
419**返回值：**
420
421|       类型        |         说明          |
422| ----------------- | -------------------- |
423| Array&lt;[LocaleItem](#localeitem10)&gt; | 排序后的国家或地区列表信息。 |
424
425**错误码：**
426
427以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
428
429| 错误码ID  | 错误信息                   |
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**示例：**
436  ```ts
437  import { BusinessError } from '@kit.BasicServicesKit';
438
439  // 当系统语言为zh-Hans，系统地区为CN，系统Locale为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      // 排序后的地区顺序为: [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&lt;TimeZoneCityItem&gt;
455
456获取时区城市组合信息的数组。
457
458**系统接口**：此接口为系统接口。
459
460**系统能力**：SystemCapability.Global.I18n
461
462**返回值：**
463
464|       类型        |         说明          |
465| ----------------- | -------------------- |
466| Array&lt;[TimeZoneCityItem](#timezonecityitem10)&gt; | 排序后的时区城市组合信息数组。 |
467
468**错误码：**
469
470以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
471
472| 错误码ID  | 错误信息                   |
473| ------ | ---------------------- |
474| 202 | Permission verification failed. A non-system application calls a system API. |
475
476**示例：**
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
494SystemLocaleManager对语言或国家地区列表的排序结果信息项。
495
496**系统接口**：此接口为系统接口。
497
498**系统能力**：SystemCapability.Global.I18n
499
500| 名称            | 类型            |  必填   |  说明                                   |
501| --------------- | --------------- | ------ | --------------------------------------- |
502| id              | string          |   是   | 语言代码或国家地区代码，如"zh"、"CN"。    |
503| suggestionType  | [SuggestionType](#suggestiontype10)  |   是  | 语言或国家地区推荐类型。                  |
504| displayName     | string          |  是   | id在SystemLocaleManager的Locale下的表示。|
505| localName       | string          |  否   | id的本地名称。                           |
506
507## TimeZoneCityItem<sup>10+</sup>
508
509时区城市组合信息。
510
511**系统接口**：此接口为系统接口。
512
513**系统能力**：SystemCapability.Global.I18n
514
515| 名称            | 类型             |  必填   |  说明                                   |
516| --------------- | --------------- | ------  | --------------------------------------- |
517| zoneId          | string          |   是    | 时区Id，例如Asia/Shanghai。              |
518| cityId          | string          |   是    | 城市Id，例如Shanghai。                   |
519| cityDisplayName | string          |   是    | 城市Id在系统Locale下显示的名称。          |
520| offset          | int             |   是    | 时区Id的偏移量。                         |
521| zoneDisplayName | string          |   是    | 时区Id在系统Locale下显示的名称。          |
522| rawOffset       | int             |   否    | 时区Id的固定偏移量。                       |
523
524
525## SuggestionType<sup>10+</sup>
526
527语言或国家地区的推荐类型。
528
529**系统接口**：此接口为系统接口。
530
531**系统能力**：SystemCapability.Global.I18n
532
533| 名称                   | 值  | 说明   |
534| ---------------------- | ---- | ---- |
535| SUGGESTION_TYPE_NONE   | 0x00 | 非推荐语言或国家地区。 |
536| SUGGESTION_TYPE_RELATED| 0x01 | 系统语言推荐的国家地区或系统国家地区推荐的语言。 |
537| SUGGESTION_TYPE_SIM    | 0x02 | Sim卡国家地区推荐的语言。 |
538
539
540## SortOptions<sup>10+<sup>
541
542语言或国家地区排序选项。
543
544**系统接口**：此接口为系统接口。
545
546**系统能力**：SystemCapability.Global.I18n
547
548| 名称            | 类型            |  必填 |   说明                                 |
549| --------------- | --------------- | ---- | --------------------------------------- |
550| locale          | string          |  否  | 区域代码，如"zh-Hans-CN"。locale属性默认值为系统Locale。    |
551| isUseLocalName  | boolean         |  否  | 表示是否使用本地名称进行排序。若调用方法为getLanguageInfoArray，isUseLocalName属性默认值为true。若调用方法为getRegionInfoArray，isUseLocalName属性默认值为false。                |
552| isSuggestedFirst | boolean        |  否  | 表示是否将推荐语言或国家地区在排序结果中置顶。isSuggestedFirst属性默认值为true。  |
553