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。
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若要监听系统区域变化,可以监听[事件](../apis-basic-services-kit/common_event/commonEventManager-definitions.md#common_event_locale_changed)OHOS::EventFwk::CommonEventSupport::COMMON_EVENT_LOCALE_CHANGED。
90
91**系统接口**:此接口为系统接口。
92
93**需要权限**:ohos.permission.UPDATE_CONFIGURATION
94
95**系统能力**:SystemCapability.Global.I18n
96
97**参数:**
98
99| 参数名    | 类型     | 必填   | 说明    |
100| ------ | ------ | ---- | ----- |
101| region | string | 是    | 合法的地区ID。 |
102
103**错误码:**
104
105以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
106
107| 错误码ID  | 错误信息                   |
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**示例:**
114  ```ts
115  import { BusinessError } from '@kit.BasicServicesKit';
116
117  try {
118    i18n.System.setSystemRegion('CN');  // 设置系统当前地区为 "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
131设置系统Locale。
132
133若要监听系统Locale变化,可以监听[事件](../apis-basic-services-kit/common_event/commonEventManager-definitions.md#common_event_locale_changed)OHOS::EventFwk::CommonEventSupport::COMMON_EVENT_LOCALE_CHANGED。
134
135**系统接口**:此接口为系统接口。
136
137**需要权限**:ohos.permission.UPDATE_CONFIGURATION
138
139**系统能力**:SystemCapability.Global.I18n
140
141**参数:**
142
143| 参数名    | 类型     | 必填   | 说明              |
144| ------ | ------ | ---- | --------------- |
145| locale | string | 是    | [表示区域信息的字符串](../../internationalization/i18n-locale-culture.md#实现原理),由语言、脚本、国家或地区组成。 |
146
147**错误码:**
148
149以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
150
151| 错误码ID  | 错误信息                   |
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**示例:**
158  ```ts
159  import { BusinessError } from '@kit.BasicServicesKit';
160
161  try {
162    i18n.System.setSystemLocale('zh-CN');  // 设置系统当前Locale为 "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
174设置系统时间为24小时。
175
176**系统接口**:此接口为系统接口。
177
178**需要权限**:ohos.permission.UPDATE_CONFIGURATION
179
180**系统能力**:SystemCapability.Global.I18n
181
182**参数:**
183
184| 参数名    | 类型      | 必填   | 说明                                       |
185| ------ | ------- | ---- | ---------------------------------------- |
186| option | boolean | 是    | option为true,表示开启系统24小时制开关;返回false,表示关闭系统24小时开关。 |
187
188**错误码:**
189
190以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
191
192| 错误码ID  | 错误信息                   |
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**示例:**
199  ```ts
200  import { BusinessError } from '@kit.BasicServicesKit';
201
202  // 将系统时间设置为24小时制
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
215在系统偏好语言列表中的指定位置添加偏好语言。
216
217**系统接口**:此接口为系统接口。
218
219**需要权限**:ohos.permission.UPDATE_CONFIGURATION
220
221**系统能力**:SystemCapability.Global.I18n
222
223**参数:**
224
225| 参数名      | 类型     | 必填   | 说明         |
226| -------- | ------ | ---- | ---------- |
227| language | string | 是    | 待添加的偏好语言,要求是合法的语言ID。  |
228| index    | number | 否    | 偏好语言的添加位置。默认值:系统偏好语言列表长度。 |
229
230**错误码:**
231
232以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
233
234| 错误码ID  | 错误信息                   |
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**示例:**
241  ```ts
242  import { BusinessError } from '@kit.BasicServicesKit';
243
244  // 将语言zh-CN添加到系统偏好语言列表中
245  let language = 'zh-CN';
246  let index = 0;
247  try {
248    i18n.System.addPreferredLanguage(language, index); // 将zh-CN添加到系统偏好语言列表的第1位
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
259删除系统偏好语言列表中指定位置的偏好语言。
260
261**系统接口**:此接口为系统接口。
262
263**需要权限**:ohos.permission.UPDATE_CONFIGURATION
264
265**系统能力**:SystemCapability.Global.I18n
266
267**参数:**
268
269| 参数名   | 类型     | 必填   | 说明                    |
270| ----- | ------ | ---- | --------------------- |
271| index | number | 是    | 待删除偏好语言在系统偏好语言列表中的位置。 |
272
273**错误码:**
274
275以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
276
277| 错误码ID  | 错误信息                   |
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**示例:**
284  ```ts
285  import { BusinessError } from '@kit.BasicServicesKit';
286
287  // 删除系统偏好语言列表中的第一个偏好语言
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
301设置系统是否使用本地数字。
302
303**系统接口**:此接口为系统接口。
304
305**需要权限**:ohos.permission.UPDATE_CONFIGURATION
306
307**系统能力**:SystemCapability.Global.I18n
308
309**参数:**
310
311| 参数名  | 类型      | 必填   | 说明                              |
312| ---- | ------- | ---- | ------------------------------- |
313| flag | boolean | 是    | true表示打开本地数字开关,false表示关闭本地数字开关。 |
314
315**错误码:**
316
317以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
318
319| 错误码ID  | 错误信息                   |
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**示例:**
326  ```ts
327  import { BusinessError } from '@kit.BasicServicesKit';
328
329  try {
330    i18n.System.setUsingLocalDigit(true); // 打开本地化数字开关
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
343创建SystemLocaleManager对象。
344
345**系统接口**:此接口为系统接口。
346
347**系统能力**:SystemCapability.Global.I18n
348
349**示例:**
350  ```ts
351  let systemLocaleManager: i18n.SystemLocaleManager = new i18n.SystemLocaleManager();
352  ```
353
354
355### getLanguageInfoArray<sup>10+</sup>
356
357getLanguageInfoArray(languages: Array&lt;string&gt;, options?: SortOptions): Array&lt;LocaleItem&gt;
358
359获取语言排序数组。
360
361**系统接口**:此接口为系统接口。
362
363**系统能力**:SystemCapability.Global.I18n
364
365**参数:**
366
367|   参数名  |      类型      | 必填 |     说明      |
368| --------- | ------------- | ---- | ------------- |
369| languages | Array&lt;string&gt; | 是   | 待排序语言列表,要求是合法的语言ID。|
370| options   | [SortOptions](#sortoptions10)   | 否   | 语言排序选项。 |
371
372**返回值:**
373
374|       类型        |         说明          |
375| ----------------- | -------------------- |
376| Array&lt;[LocaleItem](#localeitem10)&gt; | 排序后的语言列表信息。 |
377
378**错误码:**
379
380以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
381
382| 错误码ID  | 错误信息                   |
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**示例:**
389  ```ts
390  import { BusinessError } from '@kit.BasicServicesKit';
391
392  // 当系统语言为zh-Hans,系统地区为CN,系统Locale为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      // 排序后的语言顺序为: [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&lt;string&gt;, options?: SortOptions): Array&lt;LocaleItem&gt;
409
410获取国家或地区排序数组。
411
412**系统接口**:此接口为系统接口。
413
414**系统能力**:SystemCapability.Global.I18n
415
416**参数:**
417
418|   参数名  |      类型      | 必填 |     说明      |
419| --------- | ------------- | ---- | ------------- |
420| regions   | Array&lt;string&gt; | 是   | 待排序的国家或地区列表,要求是合法的国家或地区ID。|
421| options   | [SortOptions](#sortoptions10)   | 否   | 国家或地区排序选项。<br>locale的默认值为系统Locale,isUseLocalName的默认值为false,isSuggestedFirst的默认值为true。 |
422
423**返回值:**
424
425|       类型        |         说明          |
426| ----------------- | -------------------- |
427| Array&lt;[LocaleItem](#localeitem10)&gt; | 排序后的国家或地区列表信息。 |
428
429**错误码:**
430
431以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
432
433| 错误码ID  | 错误信息                   |
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**示例:**
440  ```ts
441  import { BusinessError } from '@kit.BasicServicesKit';
442
443  // 当系统语言为zh-Hans,系统地区为CN,系统Locale为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      // 排序后的地区顺序为: [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&lt;TimeZoneCityItem&gt;
459
460获取时区城市组合信息的数组。
461
462**系统接口**:此接口为系统接口。
463
464**系统能力**:SystemCapability.Global.I18n
465
466**返回值:**
467
468|       类型        |         说明          |
469| ----------------- | -------------------- |
470| Array&lt;[TimeZoneCityItem](#timezonecityitem10)&gt; | 排序后的时区城市组合信息数组。 |
471
472**错误码:**
473
474以下错误码的详细介绍请参见[ohos.i18n错误码](errorcode-i18n.md)和[通用错误码](../errorcode-universal.md)。
475
476| 错误码ID  | 错误信息                   |
477| ------ | ---------------------- |
478| 202 | Permission verification failed. A non-system application calls a system API. |
479
480**示例:**
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
498SystemLocaleManager对语言或国家地区列表的排序结果信息项。
499
500**系统接口**:此接口为系统接口。
501
502**系统能力**:SystemCapability.Global.I18n
503
504| 名称            | 类型            |  必填   |  说明                                   |
505| --------------- | --------------- | ------ | --------------------------------------- |
506| id              | string          |   是   | 语言代码或国家地区代码,如"zh"、"CN"。    |
507| suggestionType  | [SuggestionType](#suggestiontype10)  |   是  | 语言或国家地区推荐类型。                  |
508| displayName     | string          |  是   | id在SystemLocaleManager的Locale下的表示。|
509| localName       | string          |  否   | id的本地名称。                           |
510
511## TimeZoneCityItem<sup>10+</sup>
512
513时区城市组合信息。
514
515**系统接口**:此接口为系统接口。
516
517**系统能力**:SystemCapability.Global.I18n
518
519| 名称            | 类型             |  必填   |  说明                                   |
520| --------------- | --------------- | ------  | --------------------------------------- |
521| zoneId          | string          |   是    | 时区Id,例如Asia/Shanghai。              |
522| cityId          | string          |   是    | 城市Id,例如Shanghai。                   |
523| cityDisplayName | string          |   是    | 城市Id在系统Locale下显示的名称。          |
524| offset          | int             |   是    | 时区Id的偏移量。                         |
525| zoneDisplayName | string          |   是    | 时区Id在系统Locale下显示的名称。          |
526| rawOffset       | int             |   否    | 时区Id的固定偏移量。                       |
527
528
529## SuggestionType<sup>10+</sup>
530
531语言或国家地区的推荐类型。
532
533**系统接口**:此接口为系统接口。
534
535**系统能力**:SystemCapability.Global.I18n
536
537| 名称                   | 值  | 说明   |
538| ---------------------- | ---- | ---- |
539| SUGGESTION_TYPE_NONE   | 0x00 | 非推荐语言或国家地区。 |
540| SUGGESTION_TYPE_RELATED| 0x01 | 系统语言推荐的国家地区或系统国家地区推荐的语言。 |
541| SUGGESTION_TYPE_SIM    | 0x02 | Sim卡国家地区推荐的语言。 |
542
543
544## SortOptions<sup>10+<sup>
545
546语言或国家地区排序选项。
547
548**系统接口**:此接口为系统接口。
549
550**系统能力**:SystemCapability.Global.I18n
551
552| 名称            | 类型            |  必填 |   说明                                 |
553| --------------- | --------------- | ---- | --------------------------------------- |
554| locale          | string          |  否  | [表示区域信息的字符串](../../internationalization/i18n-locale-culture.md#实现原理),由语言、脚本、国家或地区组成,如"zh-Hans-CN"。<br>默认值为系统Locale。    |
555| isUseLocalName  | boolean         |  否  | 表示是否使用本地名称进行排序。<br>若调用方法为getLanguageInfoArray,isUseLocalName属性默认值为true。<br>若调用方法为getRegionInfoArray,isUseLocalName属性默认值为false。                |
556| isSuggestedFirst | boolean        |  否  | 表示是否将推荐语言或国家地区在排序结果中置顶。<br>isSuggestedFirst属性默认值为true。  |
557