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 the first letter of the text is capitalized. 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("zh-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 the first letter of the text is capitalized. 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    let displayLanguage: string = i18n.System.getDisplayLanguage("zh", "en-GB"); // Display Chinese in English.
110  } catch(error) {
111    let err: BusinessError = error as BusinessError;
112    console.error(`call System.getDisplayLanguage failed, error code: ${err.code}, message: ${err.message}.`);
113  }
114  ```
115
116### getSystemLanguages<sup>9+</sup>
117
118static getSystemLanguages(): Array&lt;string&gt;
119
120Obtains the list of system languages.
121
122Since API version 11, this API is supported in ArkTS widgets.
123
124**Atomic service API**: This API can be used in atomic services since API version 12.
125
126**System capability**: SystemCapability.Global.I18n
127
128**Return value**
129
130| Type                 | Description          |
131| ------------------- | ------------ |
132| Array&lt;string&gt; | List of the IDs of system languages.|
133
134**Example**
135  ```ts
136  let systemLanguages: Array<string> = i18n.System.getSystemLanguages(); // [ "ug", "bo", "zh-Hant", "en-Latn-US", "zh-Hans" ]
137  ```
138
139### getSystemCountries<sup>9+</sup>
140
141static getSystemCountries(language: string): Array&lt;string&gt;
142
143Obtains the list of countries and regions supported for the specified language.
144
145**Atomic service API**: This API can be used in atomic services since API version 12.
146
147**System capability**: SystemCapability.Global.I18n
148
149**Parameters**
150
151| Name     | Type    | Mandatory  | Description   |
152| -------- | ------ | ---- | ----- |
153| language | string | Yes   | Valid language ID.|
154
155**Return value**
156
157| Type                 | Description          |
158| ------------------- | ------------ |
159| Array&lt;string&gt; | List of countries or regions supported for the specified language.|
160
161**Error codes**
162
163For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md).
164
165| ID | Error Message                  |
166| ------ | ---------------------- |
167| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
168| 890001 | Invalid parameter. Possible causes: Parameter verification failed. |
169
170> **Description**
171>
172> The error message of 890001 is subject to the actual error.
173
174**Example**
175  ```ts
176  import { BusinessError } from '@kit.BasicServicesKit';
177
178  try {
179    let systemCountries: Array<string> = i18n.System.getSystemCountries('zh'); // systemCountries = [ "ZW", "YT", "YE", ..., "ER", "CN", "DE" ]
180  } catch(error) {
181    let err: BusinessError = error as BusinessError;
182    console.error(`call System.getSystemCountries failed, error code: ${err.code}, message: ${err.message}.`);
183  }
184  ```
185
186### isSuggested<sup>9+</sup>
187
188static isSuggested(language: string, region?: string): boolean
189
190Checks whether the system language matches the specified region.
191
192**Atomic service API**: This API can be used in atomic services since API version 12.
193
194**System capability**: SystemCapability.Global.I18n
195
196**Parameters**
197
198| Name     | Type    | Mandatory  | Description           |
199| -------- | ------ | ---- | ------------- |
200| language | string | Yes   | Valid language ID, for example, **zh**.|
201| region   | string | No   | Valid region ID, for example, **CN**.<br>The default value is the country or region where the SIM card is used. |
202
203**Return value**
204
205| Type     | Description                                      |
206| ------- | ---------------------------------------- |
207| boolean | The value **true** indicates that the language matches the specified country or region,<br>and the value **false** indicates the opposite.|
208
209**Error codes**
210
211For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md).
212
213| ID | Error Message                  |
214| ------ | ---------------------- |
215| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
216| 890001 | Invalid parameter. Possible causes: Parameter verification failed. |
217
218
219> **Description**
220>
221> The error message of 890001 is subject to the actual error.
222
223**Example**
224  ```ts
225  import { BusinessError } from '@kit.BasicServicesKit';
226
227  try {
228    let res: boolean = i18n.System.isSuggested('zh', 'CN');  // res = true
229  } catch(error) {
230    let err: BusinessError = error as BusinessError;
231    console.error(`call System.isSuggested failed, error code: ${err.code}, message: ${err.message}.`);
232  }
233  ```
234
235### getSystemLanguage<sup>9+</sup>
236
237static getSystemLanguage(): string
238
239Obtains the system language.
240
241**Atomic service API**: This API can be used in atomic services since API version 11.
242
243**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
244
245**System capability**: SystemCapability.Global.I18n
246
247**Return value**
248
249| Type    | Description     |
250| ------ | ------- |
251| string | System language ID.|
252
253**Example**
254  ```ts
255  let systemLanguage: string = i18n.System.getSystemLanguage();  // systemLanguage indicates the current system language.
256  ```
257
258### getSystemRegion<sup>9+</sup>
259
260static getSystemRegion(): string
261
262Obtains the system region.
263
264**Atomic service API**: This API can be used in atomic services since API version 12.
265
266**System capability**: SystemCapability.Global.I18n
267
268**Return value**
269
270| Type    | Description     |
271| ------ | ------- |
272| string | System region ID.|
273
274**Example**
275  ```ts
276  let systemRegion: string = i18n.System.getSystemRegion(); // Obtain the current system region.
277  ```
278
279### getSystemLocale<sup>9+</sup>
280
281static getSystemLocale(): string
282
283Obtains the system locale.
284
285**Atomic service API**: This API can be used in atomic services since API version 11.
286
287**System capability**: SystemCapability.Global.I18n
288
289**Return value**
290
291| Type    | Description     |
292| ------ | ------- |
293| string | Locale information.|
294
295**Example**
296  ```ts
297  let systemLocale: string = i18n.System.getSystemLocale();  // Obtain the current system locale.
298  ```
299
300### is24HourClock<sup>9+</sup>
301
302static is24HourClock(): boolean
303
304Checks whether the 24-hour clock is used.
305
306**Widget capability**: Since API version 11, this feature is supported in ArkTS widgets.
307
308**Atomic service API**: This API can be used in atomic services since API version 12.
309
310**System capability**: SystemCapability.Global.I18n
311
312**Return value**
313
314| Type     | Description                                      |
315| ------- | ---------------------------------------- |
316| boolean | The value **true** indicates that the 24-hour clock is used, and the value **false** indicates the opposite.|
317
318**Example**
319  ```ts
320  let is24HourClock: boolean = i18n.System.is24HourClock();  // Check whether the 24-hour clock is enabled.
321  ```
322
323
324### getPreferredLanguageList<sup>9+</sup>
325
326static getPreferredLanguageList(): Array&lt;string&gt;
327
328Obtains the list of preferred languages.
329
330**Atomic service API**: This API can be used in atomic services since API version 12.
331
332**System capability**: SystemCapability.Global.I18n
333
334**Return value**
335
336| Type                 | Description       |
337| ------------------- | --------- |
338| Array&lt;string&gt; | List of preferred languages.|
339
340**Example**
341  ```ts
342  let preferredLanguageList: Array<string> = i18n.System.getPreferredLanguageList(); // Obtain the current preferred language list.
343  ```
344
345### getFirstPreferredLanguage<sup>9+</sup>
346
347static getFirstPreferredLanguage(): string
348
349Obtains the first language in the preferred language list.
350
351**Atomic service API**: This API can be used in atomic services since API version 12.
352
353**System capability**: SystemCapability.Global.I18n
354
355**Return value**
356
357| Type    | Description            |
358| ------ | -------------- |
359| string | First language in the preferred language list.|
360
361**Example**
362  ```ts
363  let firstPreferredLanguage: string = i18n.System.getFirstPreferredLanguage();  // Obtain the first language in the preferred language list.
364  ```
365
366### setAppPreferredLanguage<sup>11+</sup>
367
368static setAppPreferredLanguage(language: string): void
369
370Sets 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.
371
372**Atomic service API**: This API can be used in atomic services since API version 12.
373
374**System capability**: SystemCapability.Global.I18n
375
376**Parameters**
377
378| Name     | Type    | Mandatory  | Description   |
379| -------- | ------ | ---- | ----- |
380| language | string | Yes   | Valid language ID or **default**.|
381
382**Error codes**
383
384For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md).
385
386| ID | Error Message                  |
387| ------ | ---------------------- |
388| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
389| 890001 | Invalid parameter. Possible causes: Parameter verification failed. |
390
391**Example**
392  ```ts
393  import { BusinessError } from '@kit.BasicServicesKit';
394
395  try {
396    i18n.System.setAppPreferredLanguage('zh'); // Set the preferred language of the application to zh.
397  } catch(error) {
398    let err: BusinessError = error as BusinessError;
399    console.error(`call System.setAppPreferredLanguage failed, error code: ${err.code}, message: ${err.message}.`);
400  }
401  ```
402
403### getAppPreferredLanguage<sup>9+</sup>
404
405static getAppPreferredLanguage(): string
406
407Obtains the preferred language of an application.
408
409**Atomic service API**: This API can be used in atomic services since API version 12.
410
411**System capability**: SystemCapability.Global.I18n
412
413**Return value**
414
415| Type    | Description      |
416| ------ | -------- |
417| string | Preferred language of the application.|
418
419**Example**
420  ```ts
421  let appPreferredLanguage: string = i18n.System.getAppPreferredLanguage(); // Obtain the preferred language of the application.
422  ```
423
424
425### getUsingLocalDigit<sup>9+</sup>
426
427static getUsingLocalDigit(): boolean
428
429Checks whether use of local digits is enabled.
430
431**Atomic service API**: This API can be used in atomic services since API version 12.
432
433**System capability**: SystemCapability.Global.I18n
434
435**Return value**
436
437| Type     | Description                                      |
438| ------- | ---------------------------------------- |
439| boolean | The value **true** indicates that the local digit switch is enabled, and the value **false** indicates the opposite.|
440
441**Example**
442  ```ts
443  let status: boolean = i18n.System.getUsingLocalDigit();  // Check whether the local digit switch is enabled.
444  ```
445
446## i18n.isRTL
447
448isRTL(locale: string): boolean
449
450Checks whether a locale uses a right-to-left (RTL) language.
451
452**Atomic service API**: This API can be used in atomic services since API version 12.
453
454**System capability**: SystemCapability.Global.I18n
455
456**Parameters**
457
458| Name   | Type    | Mandatory  | Description     |
459| ------ | ------ | ---- | ------- |
460| locale | string | Yes   | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region. |
461
462**Return value**
463
464| Type     | Description                                      |
465| ------- | ---------------------------------------- |
466| boolean | The value **true** indicates that the locale uses an RTL language, and the value **false** indicates the opposite.|
467
468**Example**
469  ```ts
470  i18n.isRTL("zh-CN");// Since Chinese is not written from right to left, false is returned.
471  i18n.isRTL("ar-EG");// Since Arabic is written from right to left, true is returned.
472  ```
473
474## i18n.getCalendar<sup>8+</sup>
475
476getCalendar(locale: string, type? : string): Calendar
477
478Obtains a **Calendar** object.
479
480**Atomic service API**: This API can be used in atomic services since API version 12.
481
482**System capability**: SystemCapability.Global.I18n
483
484**Parameters**
485
486| Name   | Type    | Mandatory  | Description                                      |
487| ------ | ------ | ---- | ---------------------------------------- |
488| 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**.                |
489| 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).|
490
491**Return value**
492
493| Type                    | Description   |
494| ---------------------- | ----- |
495| [Calendar](#calendar8) | **Calendar** object.|
496
497**Example**
498  ```ts
499  i18n.getCalendar("zh-Hans", "chinese"); // Obtain the Calendar object for the Chinese lunar calendar.
500  ```
501
502## EntityRecognizer<sup>11+</sup>
503
504### constructor<sup>11+</sup>
505
506constructor(locale?: string)
507
508Creates an **entityRecognizer** object.
509
510**Atomic service API**: This API can be used in atomic services since API version 12.
511
512**System capability**: SystemCapability.Global.I18n
513
514**Parameters**
515
516| Name | Type  | Mandatory  | Description               |
517| ---- | ---- | ---- | ----------------- |
518| 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.|
519
520**Error codes**
521
522For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md).
523
524| ID | Error Message                  |
525| ------ | ---------------------- |
526| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
527| 890001 | Invalid parameter. Possible causes: Parameter verification failed. |
528
529**Example**
530  ```ts
531  let entityRecognizer: i18n.EntityRecognizer = new i18n.EntityRecognizer("zh-CN");
532  ```
533
534### findEntityInfo<sup>11+</sup>
535
536findEntityInfo(text: string): Array&lt;EntityInfoItem&gt;
537
538Recognizes entities in text.
539
540**Atomic service API**: This API can be used in atomic services since API version 12.
541
542**System capability**: SystemCapability.Global.I18n
543
544**Parameters**
545
546| Name | Type  | Mandatory  | Description               |
547| ---- | ---- | ---- | ----------------- |
548| text | string | Yes   | Text to be recognized.|
549
550**Return value**
551
552| Type  | Description               |
553| ---- | ----------------- |
554| Array&lt;[EntityInfoItem](#entityinfoitem11)&gt; | List of entities in the text.|
555
556**Error codes**
557
558For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
559
560| ID | Error Message                  |
561| ------ | ---------------------- |
562| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
563
564**Example**
565  ```ts
566  let entityRecognizer: i18n.EntityRecognizer = new i18n.EntityRecognizer("zh-CN");
567  let text1: string = " If you have any questions, call us by phone 12345678";
568  let result1: Array<i18n.EntityInfoItem> = entityRecognizer.findEntityInfo(text1); // result1[0].type = "phone_number", result1[0].begin = 8, result1[0].end = 19
569  let text2: string = "Let's have dinner on December 1, 2023."
570  let result2: Array<i18n.EntityInfoItem> = entityRecognizer.findEntityInfo(text2); // result2[0].type = "date", result2[0].begin = 2, result2[0].end = 12
571  ```
572
573## EntityInfoItem<sup>11+</sup>
574
575Defines a list of entities.
576
577**Atomic service API**: This API can be used in atomic services since API version 12.
578
579**System capability**: SystemCapability.Global.I18n
580
581| Name | Type  | Readable  | Writable  | Description               |
582| ---- | ---- | ---- | ---- | ----------------- |
583| type | string | Yes   | Yes   | Entity type. The value can be **phone_number** or **date**.|
584| begin | number | Yes   | Yes   | Start position of an entity.|
585| end | number | Yes   | Yes   | End position of an entity.|
586
587## Calendar<sup>8+</sup>
588
589### setTime<sup>8+</sup>
590
591setTime(date: Date): void
592
593Sets the date and time for a **Calendar** object.
594
595**Atomic service API**: This API can be used in atomic services since API version 12.
596
597**System capability**: SystemCapability.Global.I18n
598
599**Parameters**
600
601| Name | Type  | Mandatory  | Description               |
602| ---- | ---- | ---- | ----------------- |
603| date | Date | Yes   | Date and time.|
604
605**Example**
606  ```ts
607  let calendar: i18n.Calendar = i18n.getCalendar("en-US", "gregory");
608  let date: Date = new Date(2021, 10, 7, 8, 0, 0, 0);
609  calendar.setTime(date);
610  ```
611
612
613### setTime<sup>8+</sup>
614
615setTime(time: number): void
616
617Sets the date and time for a **Calendar** object.
618
619**Atomic service API**: This API can be used in atomic services since API version 12.
620
621**System capability**: SystemCapability.Global.I18n
622
623**Parameters**
624
625| Name | Type    | Mandatory  | Description                                      |
626| ---- | ------ | ---- | ---------------------------------------- |
627| time | number | Yes   | Number of milliseconds that have elapsed since the Unix epoch.|
628
629**Example**
630  ```ts
631  let calendar: i18n.Calendar = i18n.getCalendar("en-US", "gregory");
632  calendar.setTime(10540800000);
633  ```
634
635### set<sup>8+</sup>
636
637set(year: number, month: number, date:number, hour?: number, minute?: number, second?: number): void
638
639Sets the year, month, day, hour, minute, and second for this **Calendar** object.
640
641**Atomic service API**: This API can be used in atomic services since API version 12.
642
643**System capability**: SystemCapability.Global.I18n
644
645**Parameters**
646
647| Name   | Type    | Mandatory  | Description    |
648| ------ | ------ | ---- | ------ |
649| year   | number | Yes   | Year to set. |
650| month  | number | Yes   | Month to set. |
651| date   | number | Yes   | Day to set. |
652| hour   | number | No   | Hour to set. The default value is the system hour.|
653| minute | number | No   | Minute to set. The default value is the system minute.|
654| second | number | No   | Second to set. The default value is the system second.|
655
656**Example**
657  ```ts
658  let calendar: i18n.Calendar = i18n.getCalendar("zh-Hans");
659  calendar.set(2021, 10, 1, 8, 0, 0); // set time to 2021.11.1 08:00:00
660  ```
661
662### setTimeZone<sup>8+</sup>
663
664setTimeZone(timezone: string): void
665
666Sets the time zone of this **Calendar** object.
667
668**Atomic service API**: This API can be used in atomic services since API version 12.
669
670**System capability**: SystemCapability.Global.I18n
671
672**Parameters**
673
674| Name     | Type    | Mandatory  | Description                       |
675| -------- | ------ | ---- | ------------------------- |
676| timezone | string | Yes   | Valid time zone ID, for example, Asia/Shanghai.|
677
678**Example**
679  ```ts
680  let calendar: i18n.Calendar = i18n.getCalendar("zh-Hans");
681  calendar.setTimeZone("Asia/Shanghai");
682  ```
683
684
685### getTimeZone<sup>8+</sup>
686
687getTimeZone(): string
688
689Obtains the time zone of this **Calendar** object.
690
691**Atomic service API**: This API can be used in atomic services since API version 12.
692
693**System capability**: SystemCapability.Global.I18n
694
695**Return value**
696
697| Type    | Description        |
698| ------ | ---------- |
699| string | Time zone ID.|
700
701**Example**
702  ```ts
703  let calendar: i18n.Calendar = i18n.getCalendar("zh-Hans");
704  calendar.setTimeZone("Asia/Shanghai");
705  let timezone: string = calendar.getTimeZone(); // timezone = "Asia/Shanghai"
706  ```
707
708
709### getFirstDayOfWeek<sup>8+</sup>
710
711getFirstDayOfWeek(): number
712
713Obtains the start day of a week for a **Calendar** object.
714
715**Atomic service API**: This API can be used in atomic services since API version 12.
716
717**System capability**: SystemCapability.Global.I18n
718
719**Return value**
720
721| Type    | Description                   |
722| ------ | --------------------- |
723| number | Start day of a week. The value **1** indicates Sunday, and the value **7** indicates Saturday.|
724
725**Example**
726  ```ts
727  let calendar: i18n.Calendar = i18n.getCalendar("en-US", "gregory");
728  let firstDayOfWeek: number = calendar.getFirstDayOfWeek(); // firstDayOfWeek = 1
729  ```
730
731
732### setFirstDayOfWeek<sup>8+</sup>
733
734setFirstDayOfWeek(value: number): void
735
736Sets the start day of a week for a **Calendar** object.
737
738**Atomic service API**: This API can be used in atomic services since API version 12.
739
740**System capability**: SystemCapability.Global.I18n
741
742**Parameters**
743
744| Name  | Type    | Mandatory  | Description                   |
745| ----- | ------ | ---- | --------------------- |
746| value | number | Yes   | Start day of a week. The value **1** indicates Sunday, and the value **7** indicates Saturday.|
747
748**Example**
749  ```ts
750  let calendar: i18n.Calendar = i18n.getCalendar("zh-Hans");
751  calendar.setFirstDayOfWeek(3);
752  let firstDayOfWeek: number = calendar.getFirstDayOfWeek(); // firstDayOfWeek = 3
753  ```
754
755### getMinimalDaysInFirstWeek<sup>8+</sup>
756
757getMinimalDaysInFirstWeek(): number
758
759Obtains the minimum number of days in the first week of a year.
760
761**Atomic service API**: This API can be used in atomic services since API version 12.
762
763**System capability**: SystemCapability.Global.I18n
764
765**Return value**
766
767| Type    | Description          |
768| ------ | ------------ |
769| number | Minimum number of days in the first week of a year.|
770
771**Example**
772  ```ts
773  let calendar: i18n.Calendar = i18n.getCalendar("zh-Hans");
774  let minimalDaysInFirstWeek: number = calendar.getMinimalDaysInFirstWeek(); // minimalDaysInFirstWeek = 1
775  ```
776
777
778### setMinimalDaysInFirstWeek<sup>8+</sup>
779
780setMinimalDaysInFirstWeek(value: number): void
781
782Sets the minimum number of days in the first week of a year.
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| value | number | Yes   | Minimum number of days in the first week of a year.|
793
794**Example**
795  ```ts
796  let calendar: i18n.Calendar = i18n.getCalendar("zh-Hans");
797  calendar.setMinimalDaysInFirstWeek(3);
798  let minimalDaysInFirstWeek: number = calendar.getMinimalDaysInFirstWeek(); // minimalDaysInFirstWeek = 3
799  ```
800
801
802### get<sup>8+</sup>
803
804get(field: string): number
805
806Obtains the value of the associated field in 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| field | string | Yes   | Associated field in a **Calendar** object. The following table lists the supported field values.|
817
818
819| Field  | Description                                      |
820| ----- | ---------------------------------------- |
821| era | Era, for example, AD or BC.|
822| year | Year.|
823| month | Month.|
824| date | Date.|
825| hour | Wall-clock hour.|
826| hour_of_day | Hour of day.|
827| minute | Minute.|
828| second | Second.|
829| millisecond | Millisecond.|
830| 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.|
831| year_woy | Year used with the week of year field. |
832| week_of_month | Week of month.|
833| day_of_week_in_month | Day of week in month.|
834| day_of_year | Day of year.|
835| day_of_week | Day of week.|
836| milliseconds_in_day | Milliseconds in day.|
837| zone_offset | Fixed time zone offset in milliseconds (excluding DST).|
838| dst_offset | DST offset in milliseconds.|
839| dow_local | Localized day of week.|
840| extended_year | Extended year, which can be a negative number.|
841| julian_day | Julian day.|
842| is_leap_month | Whether a month is a leap month.|
843
844**Return value**
845
846| Type    | Description                                      |
847| ------ | ---------------------------------------- |
848| 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**.|
849
850**Example**
851  ```ts
852  let calendar: i18n.Calendar = i18n.getCalendar("zh-Hans");
853  calendar.set(2021, 10, 1, 8, 0, 0); // set time to 2021.11.1 08:00:00
854  let hourOfDay: number = calendar.get("hour_of_day"); // hourOfDay = 8
855  ```
856
857
858### getDisplayName<sup>8+</sup>
859
860getDisplayName(locale: string): string
861
862Obtains the displayed name of the **Calendar** object for the specified locale.
863
864**Atomic service API**: This API can be used in atomic services since API version 12.
865
866**System capability**: SystemCapability.Global.I18n
867
868**Parameters**
869
870| Name   | Type    | Mandatory  | Description                                      |
871| ------ | ------ | ---- | ---------------------------------------- |
872| locale | string | Yes   | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region.|
873
874**Return value**
875
876| Type    | Description                 |
877| ------ | ------------------- |
878| 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**.|
879
880**Example**
881  ```ts
882  let calendar: i18n.Calendar = i18n.getCalendar("en-US", "buddhist");
883  let calendarName: string = calendar.getDisplayName("zh"); // calendarName = "Buddhist Calendar"
884  ```
885
886
887### isWeekend<sup>8+</sup>
888
889isWeekend(date?: Date): boolean
890
891Checks whether a given date is a weekend in the calendar.
892
893**Atomic service API**: This API can be used in atomic services since API version 12.
894
895**System capability**: SystemCapability.Global.I18n
896
897**Parameters**
898
899| Name | Type  | Mandatory  | Description                                      |
900| ---- | ---- | ---- | ---------------------------------------- |
901| date | Date | No   | Specified date.<br>The default value is the system date. If this parameter is left empty, the system checks whether the current date is a weekend.|
902
903**Return value**
904
905| Type     | Description                                 |
906| ------- | ----------------------------------- |
907| boolean | The value **true** indicates that the specified date is a weekend, and the value **false** indicates the opposite.|
908
909**Example**
910  ```ts
911  let calendar: i18n.Calendar = i18n.getCalendar("zh-Hans");
912  calendar.set(2021, 11, 11, 8, 0, 0); // set time to 2021.12.11 08:00:00
913  calendar.isWeekend(); // true
914  let date: Date = new Date(2011, 11, 6, 9, 0, 0);
915  calendar.isWeekend(date); // false
916  ```
917
918
919### add<sup>11+</sup>
920
921add(field: string, amount: number): void
922
923Adds or subtracts some fields in a **Calendar** object.
924
925**Atomic service API**: This API can be used in atomic services since API version 12.
926
927**System capability**: SystemCapability.Global.I18n
928
929**Parameters**
930
931| Name | Type  | Mandatory  | Description                                      |
932| ---- | ---- | ---- | ---------------------------------------- |
933| 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).|
934| amount | number | Yes   | Addition or subtraction amount.|
935
936**Error codes**
937
938For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md).
939
940| ID | Error Message                  |
941| ------ | ---------------------- |
942| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
943| 890001 | Invalid parameter. Possible causes: Parameter verification failed. |
944
945**Example**
946  ```ts
947  import { BusinessError } from '@kit.BasicServicesKit';
948
949  try {
950    let calendar: i18n.Calendar = i18n.getCalendar("zh-Hans");
951    calendar.set(2021, 11, 11, 8, 0, 0); // set time to 2021.12.11 08:00:00
952    calendar.add("year", 8); // 2021 + 8
953    let year: number = calendar.get("year"); // year = 2029
954  } catch(error) {
955    let err: BusinessError = error as BusinessError;
956    console.error(`call Calendar.add failed, error code: ${err.code}, message: ${err.message}.`);
957  }
958  ```
959
960
961### getTimeInMillis<sup>11+</sup>
962
963getTimeInMillis(): number
964
965Obtains number of milliseconds that have elapsed since the Unix epoch in the current **Calendar** object.
966
967**Atomic service API**: This API can be used in atomic services since API version 12.
968
969**System capability**: SystemCapability.Global.I18n
970
971**Return value**
972
973| Type     | Description                                 |
974| ------- | ----------------------------------- |
975| number | Number of milliseconds that have elapsed since the Unix epoch.|
976
977**Example**
978  ```ts
979  let calendar: i18n.Calendar = i18n.getCalendar("zh-Hans");
980  calendar.setTime(5000);
981  let millisecond: number = calendar.getTimeInMillis(); // millisecond = 5000
982  ```
983
984
985### compareDays<sup>11+</sup>
986
987compareDays(date: Date): number
988
989Compares the **Calendar** object and the specified date for the difference in the number of days.
990
991**Atomic service API**: This API can be used in atomic services since API version 12.
992
993**System capability**: SystemCapability.Global.I18n
994
995**Parameters**
996
997| Name | Type  | Mandatory  | Description                                      |
998| ---- | ---- | ---- | ---------------------------------------- |
999| date | Date | Yes   | Specified date.|
1000
1001**Return value**
1002
1003| Type     | Description                                 |
1004| ------- | ----------------------------------- |
1005| 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.|
1006
1007**Error codes**
1008
1009For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
1010
1011| ID | Error Message                  |
1012| ------ | ---------------------- |
1013| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
1014
1015**Example**
1016  ```ts
1017  import { BusinessError } from '@kit.BasicServicesKit';
1018
1019  try {
1020    let calendar: i18n.Calendar = i18n.getCalendar("zh-Hans");
1021    calendar.setTime(5000);
1022    let date: Date = new Date(6000);
1023    let diff: number = calendar.compareDays(date); // diff = 1
1024  } catch(error) {
1025    let err: BusinessError = error as BusinessError;
1026    console.error(`call Calendar.compareDays failed, error code: ${err.code}, message: ${err.message}.`);
1027  }
1028  ```
1029
1030## PhoneNumberFormat<sup>8+</sup>
1031
1032
1033### constructor<sup>8+</sup>
1034
1035constructor(country: string, options?: PhoneNumberFormatOptions)
1036
1037Creates a **PhoneNumberFormat** object.
1038
1039**Atomic service API**: This API can be used in atomic services since API version 12.
1040
1041**System capability**: SystemCapability.Global.I18n
1042
1043**Parameters**
1044
1045| Name    | Type                                      | Mandatory  | Description              |
1046| ------- | ---------------------------------------- | ---- | ---------------- |
1047| country | string                                   | Yes   | Country or region to which the phone number to be formatted belongs.|
1048| options | [PhoneNumberFormatOptions](#phonenumberformatoptions8) | No   | Options for initializing the **PhoneNumberFormat** object. The default value is **NATIONAL**. |
1049
1050**Example**
1051  ```ts
1052  let option: i18n.PhoneNumberFormatOptions = {type: "E164"};
1053  let phoneNumberFormat: i18n.PhoneNumberFormat = new i18n.PhoneNumberFormat("CN", option);
1054  ```
1055
1056### isValidNumber<sup>8+</sup>
1057
1058isValidNumber(number: string): boolean
1059
1060Checks whether the format of the specified phone number is valid.
1061
1062**Atomic service API**: This API can be used in atomic services since API version 12.
1063
1064**System capability**: SystemCapability.Global.I18n
1065
1066**Parameters**
1067
1068| Name   | Type    | Mandatory  | Description       |
1069| ------ | ------ | ---- | --------- |
1070| number | string | Yes   | Phone number to be checked.|
1071
1072**Return value**
1073
1074| Type     | Description                                   |
1075| ------- | ------------------------------------- |
1076| boolean | The value **true** indicates that the phone number format is valid, and the value **false** indicates the opposite.|
1077
1078**Example**
1079  ```ts
1080  let phonenumberfmt: i18n.PhoneNumberFormat = new i18n.PhoneNumberFormat("CN");
1081  let isValidNumber: boolean = phonenumberfmt.isValidNumber("158****2312"); // isValidNumber = true
1082  ```
1083
1084
1085### format<sup>8+</sup>
1086
1087format(number: string): string
1088
1089Formats a phone number.
1090
1091> **Description**
1092> Formatting dialed phone numbers is supported since API version 12.
1093
1094**Atomic service API**: This API can be used in atomic services since API version 12.
1095
1096**System capability**: SystemCapability.Global.I18n
1097
1098**Parameters**
1099
1100| Name   | Type    | Mandatory  | Description        |
1101| ------ | ------ | ---- | ---------- |
1102| number | string | Yes   | Phone number to be formatted.|
1103
1104**Return value**
1105
1106| Type    | Description        |
1107| ------ | ---------- |
1108| string | Formatted phone number.|
1109
1110**Example**
1111  ```ts
1112  let phonenumberfmt: i18n.PhoneNumberFormat = new i18n.PhoneNumberFormat("CN");
1113  let formattedPhoneNumber: string = phonenumberfmt.format("158****2312"); // formattedPhoneNumber = "158 **** 2312"
1114
1115  // Format the dialed phone number.
1116  let option: i18n.PhoneNumberFormatOptions = {type: "TYPING"};
1117  let phoneNumberFmt: i18n.PhoneNumberFormat = new i18n.PhoneNumberFormat("CN", option);
1118  let phoneNumber : string = "130493";
1119  let formatResult : string = "";
1120  for (let i = 0; i < phoneNumber.length; i++) {
1121    formatResult += phoneNumber.charAt(i);
1122    formatResult = phoneNumberFmt.format(formatResult);
1123  }
1124  console.log(formatResult); // formatResult: 130 493
1125  ```
1126
1127### getLocationName<sup>9+</sup>
1128
1129getLocationName(number: string, locale: string): string
1130
1131Obtains the home location of a phone number.
1132
1133**Atomic service API**: This API can be used in atomic services since API version 12.
1134
1135**System capability**: SystemCapability.Global.I18n
1136
1137**Parameters**
1138
1139| Name   | Type    | Mandatory  | Description  |
1140| ------ | ------ | ---- | ---- |
1141| 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.|
1142| locale | string | Yes   | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region.|
1143
1144**Return value**
1145
1146| Type    | Description      |
1147| ------ | -------- |
1148| string | Home location of the phone number.|
1149
1150**Example**
1151  ```ts
1152  let phonenumberfmt: i18n.PhoneNumberFormat = new i18n.PhoneNumberFormat("CN");
1153  let locationName: string = phonenumberfmt.getLocationName("158****2345", "zh-CN"); // locationName = "Zhanjiang, Guangdong Province"
1154  let locName: string = phonenumberfmt.getLocationName("0039312****789", "zh-CN"); // locName = "Italy"
1155  ```
1156
1157
1158## PhoneNumberFormatOptions<sup>8+</sup>
1159
1160Options for initializing the **PhoneNumberFormat** object.
1161
1162**Atomic service API**: This API can be used in atomic services since API version 12.
1163
1164**System capability**: SystemCapability.Global.I18n
1165
1166| Name  | Type    | Readable  | Writable  | Description                                      |
1167| ---- | ------ | ---- | ---- | ---------------------------------------- |
1168| 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.|
1169
1170
1171## UnitInfo<sup>8+</sup>
1172
1173Defines the measurement unit information.
1174
1175**Atomic service API**: This API can be used in atomic services since API version 12.
1176
1177**System capability**: SystemCapability.Global.I18n
1178
1179| Name           | Type    | Readable  | Writable  | Description                                      |
1180| ------------- | ------ | ---- | ---- | ---------------------------------------- |
1181| unit          | string | Yes   | Yes   | Name of the measurement unit, for example, **meter**, **inch**, or **cup**.|
1182| measureSystem | string | Yes   | Yes   | Measurement system. The value can be **SI**, **US**, or **UK**.|
1183
1184
1185## getInstance<sup>8+</sup>
1186
1187getInstance(locale?:string): IndexUtil
1188
1189Creates an **IndexUtil** object.
1190
1191**Atomic service API**: This API can be used in atomic services since API version 12.
1192
1193**System capability**: SystemCapability.Global.I18n
1194
1195**Parameters**
1196
1197| Name   | Type    | Mandatory  | Description                          |
1198| ------ | ------ | ---- | ---------------------------- |
1199| 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.|
1200
1201**Return value**
1202
1203| Type                      | Description                   |
1204| ------------------------ | --------------------- |
1205| [IndexUtil](#indexutil8) | **IndexUtil** object mapping to the **locale** object.|
1206
1207**Example**
1208  ```ts
1209  let indexUtil: i18n.IndexUtil = i18n.getInstance("zh-CN");
1210  ```
1211
1212
1213## IndexUtil<sup>8+</sup>
1214
1215**Atomic service API**: This API can be used in atomic services since API version 12.
1216
1217### getIndexList<sup>8+</sup>
1218
1219getIndexList(): Array&lt;string&gt;
1220
1221Obtains the index list of the current locale.
1222
1223**Atomic service API**: This API can be used in atomic services since API version 12.
1224
1225**System capability**: SystemCapability.Global.I18n
1226
1227**Return value**
1228
1229| Type                 | Description                |
1230| ------------------- | ------------------ |
1231| Array&lt;string&gt; | Index list of the current locale.|
1232
1233**Example**
1234  ```ts
1235  let indexUtil: i18n.IndexUtil = i18n.getInstance("zh-CN");
1236  // indexList = [ "...", "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N",
1237  //              "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z", "..." ]
1238  let indexList: Array<string> = indexUtil.getIndexList();
1239  ```
1240
1241
1242### addLocale<sup>8+</sup>
1243
1244addLocale(locale: string): void
1245
1246Adds the index list of a new locale to the index list of the current locale to form a composite list.
1247
1248**Atomic service API**: This API can be used in atomic services since API version 12.
1249
1250**System capability**: SystemCapability.Global.I18n
1251
1252**Parameters**
1253
1254| Name   | Type    | Mandatory  | Description                          |
1255| ------ | ------ | ---- | ---------------------------- |
1256| locale | string | Yes   | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region.|
1257
1258**Example**
1259  ```ts
1260  let indexUtil: i18n.IndexUtil = i18n.getInstance("zh-CN");
1261  indexUtil.addLocale("en-US");
1262  ```
1263
1264### getIndex<sup>8+</sup>
1265
1266getIndex(text: string): string
1267
1268Obtains the index of a **text** object.
1269
1270**Atomic service API**: This API can be used in atomic services since API version 12.
1271
1272**System capability**: SystemCapability.Global.I18n
1273
1274**Parameters**
1275
1276| Name | Type    | Mandatory  | Description          |
1277| ---- | ------ | ---- | ------------ |
1278| text | string | Yes   | **text** object whose index is to be obtained.|
1279
1280**Return value**
1281
1282| Type    | Description         |
1283| ------ | ----------- |
1284| string | Index of the **text** object.|
1285
1286**Example**
1287  ```ts
1288  let indexUtil: i18n.IndexUtil = i18n.getInstance("zh-CN");
1289  let index: string = indexUtil.getIndex("hi");  // index = "H"
1290  ```
1291
1292
1293## i18n.getLineInstance<sup>8+</sup>
1294
1295getLineInstance(locale: string): BreakIterator
1296
1297Obtains a [BreakIterator](#breakiterator8) object for text segmentation.
1298
1299**Atomic service API**: This API can be used in atomic services since API version 12.
1300
1301**System capability**: SystemCapability.Global.I18n
1302
1303**Parameters**
1304
1305| Name   | Type    | Mandatory  | Description                                      |
1306| ------ | ------ | ---- | ---------------------------------------- |
1307| 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.|
1308
1309**Return value**
1310
1311| Type                              | Description         |
1312| -------------------------------- | ----------- |
1313| [BreakIterator](#breakiterator8) | Break iterator used for text segmentation.|
1314
1315**Example**
1316  ```ts
1317  let iterator: i18n.BreakIterator = i18n.getLineInstance("en");
1318  ```
1319
1320
1321## BreakIterator<sup>8+</sup>
1322
1323
1324### setLineBreakText<sup>8+</sup>
1325
1326setLineBreakText(text: string): void
1327
1328Sets the text to be processed by the **BreakIterator** object.
1329
1330**Atomic service API**: This API can be used in atomic services since API version 12.
1331
1332**System capability**: SystemCapability.Global.I18n
1333
1334**Parameters**
1335
1336| Name | Type    | Mandatory  | Description                     |
1337| ---- | ------ | ---- | ----------------------- |
1338| text | string | Yes   | Text to be processed by the **BreakIterator** object.|
1339
1340**Example**
1341  ```ts
1342  let iterator: i18n.BreakIterator = i18n.getLineInstance("en");
1343  iterator.setLineBreakText("Apple is my favorite fruit ."); // Set a short sentence as the text to be processed by the BreakIterator object.
1344  ```
1345
1346
1347### getLineBreakText<sup>8+</sup>
1348
1349getLineBreakText(): string
1350
1351Obtains the text being processed by the **BreakIterator** object.
1352
1353**Atomic service API**: This API can be used in atomic services since API version 12.
1354
1355**System capability**: SystemCapability.Global.I18n
1356
1357**Return value**
1358
1359| Type    | Description                    |
1360| ------ | ---------------------- |
1361| string | Text being processed by the **BreakIterator** object.|
1362
1363**Example**
1364  ```ts
1365  let iterator: i18n.BreakIterator = i18n.getLineInstance("en");
1366  iterator.setLineBreakText("Apple is my favorite fruit.");
1367  let breakText: string = iterator.getLineBreakText(); // breakText = "Apple is my favorite fruit."
1368  ```
1369
1370
1371### current<sup>8+</sup>
1372
1373current(): number
1374
1375Obtains the position of a **BreakIterator** object in the processed text.
1376
1377**Atomic service API**: This API can be used in atomic services since API version 12.
1378
1379**System capability**: SystemCapability.Global.I18n
1380
1381**Return value**
1382
1383| Type    | Description                         |
1384| ------ | --------------------------- |
1385| number | Position of the **BreakIterator** object in the text being processed.|
1386
1387**Example**
1388  ```ts
1389  let iterator: i18n.BreakIterator = i18n.getLineInstance("en");
1390  iterator.setLineBreakText("Apple is my favorite fruit.");
1391  let currentPos: number = iterator.current(); // currentPos = 0
1392  ```
1393
1394
1395### first<sup>8+</sup>
1396
1397first(): number
1398
1399Moves a **BreakIterator** object to the first break point, which is always at the beginning of the processed text.
1400
1401**Atomic service API**: This API can be used in atomic services since API version 12.
1402
1403**System capability**: SystemCapability.Global.I18n
1404
1405**Return value**
1406
1407| Type    | Description               |
1408| ------ | ----------------- |
1409| number | Offset to the first break point of the processed text.|
1410
1411**Example**
1412  ```ts
1413  let iterator: i18n.BreakIterator = i18n.getLineInstance("en");
1414  iterator.setLineBreakText("Apple is my favorite fruit.");
1415  let firstPos: number = iterator.first(); // firstPos = 0
1416  ```
1417
1418
1419### last<sup>8+</sup>
1420
1421last(): number
1422
1423Moves a **BreakIterator** object to the last break point, which is always the next position after the end of the processed text.
1424
1425**Atomic service API**: This API can be used in atomic services since API version 12.
1426
1427**System capability**: SystemCapability.Global.I18n
1428
1429**Return value**
1430
1431| Type    | Description                |
1432| ------ | ------------------ |
1433| number | Offset to the last break point of the processed text.|
1434
1435**Example**
1436  ```ts
1437  let iterator: i18n.BreakIterator = i18n.getLineInstance("en");
1438  iterator.setLineBreakText("Apple is my favorite fruit.");
1439  let lastPos: number = iterator.last(); // lastPos = 27
1440  ```
1441
1442
1443### next<sup>8+</sup>
1444
1445next(index?: number): number
1446
1447Moves the **BreakIterator** object backward by the corresponding number of break points.
1448
1449**Atomic service API**: This API can be used in atomic services since API version 12.
1450
1451**System capability**: SystemCapability.Global.I18n
1452
1453**Parameters**
1454
1455| Name  | Type    | Mandatory  | Description                                      |
1456| ----- | ------ | ---- | ---------------------------------------- |
1457| 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**.|
1458
1459**Return value**
1460
1461| Type    | Description                                      |
1462| ------ | ---------------------------------------- |
1463| 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.|
1464
1465**Example**
1466  ```ts
1467  let iterator: i18n.BreakIterator = i18n.getLineInstance("en");
1468  iterator.setLineBreakText("Apple is my favorite fruit.");
1469  let pos: number = iterator.first(); // pos = 0
1470  pos = iterator.next(); // pos = 6
1471  pos = iterator.next(10); // pos = -1
1472  ```
1473
1474
1475### previous<sup>8+</sup>
1476
1477previous(): number
1478
1479Moves the **BreakIterator** object forward by one break point.
1480
1481**Atomic service API**: This API can be used in atomic services since API version 12.
1482
1483**System capability**: SystemCapability.Global.I18n
1484
1485**Return value**
1486
1487| Type    | Description                                      |
1488| ------ | ---------------------------------------- |
1489| 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.|
1490
1491**Example**
1492  ```ts
1493  let iterator: i18n.BreakIterator = i18n.getLineInstance("en");
1494  iterator.setLineBreakText("Apple is my favorite fruit.");
1495  let pos: number = iterator.first(); // pos = 0
1496  pos = iterator.next(3); // pos = 12
1497  pos = iterator.previous(); // pos = 9
1498  ```
1499
1500
1501### following<sup>8+</sup>
1502
1503following(offset: number): number
1504
1505Moves a **BreakIterator** object to the break point following the specified position.
1506
1507**Atomic service API**: This API can be used in atomic services since API version 12.
1508
1509**System capability**: SystemCapability.Global.I18n
1510
1511**Parameters**
1512
1513| Name   | Type    | Mandatory  | Description                                      |
1514| ------ | ------ | ---- | ---------------------------------------- |
1515| offset | number | Yes   | Offset to the break point following the specified position.|
1516
1517**Return value**
1518
1519| Type    | Description                                      |
1520| ------ | ---------------------------------------- |
1521| 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.|
1522
1523**Example**
1524  ```ts
1525  let iterator: i18n.BreakIterator = i18n.getLineInstance("en");
1526  iterator.setLineBreakText("Apple is my favorite fruit.");
1527  let pos: number = iterator.following(0); // pos = 6
1528  pos = iterator.following(100); // pos = -1
1529  pos = iterator.current(); // pos = 27
1530  ```
1531
1532
1533### isBoundary<sup>8+</sup>
1534
1535isBoundary(offset: number): boolean
1536
1537Checks whether the specified position is a break point.
1538
1539**Atomic service API**: This API can be used in atomic services since API version 12.
1540
1541**System capability**: SystemCapability.Global.I18n
1542
1543**Parameters**
1544
1545| Name   | Type    | Mandatory  | Description         |
1546| ------ | ------ | ---- | ----------- |
1547| offset | number | Yes   | Specified position.|
1548
1549**Return value**
1550
1551| Type     | Description                             |
1552| ------- | ------------------------------- |
1553| boolean | Offset to the specified position of the text. The value **true** is returned if the position specified by **offset** is a break point, and the value **false** is returned otherwise.<br>If **true** is returned, the **BreakIterator** object is moved to the position specified by **offset**. Otherwise, **following** is called.|
1554
1555**Example**
1556  ```ts
1557  let iterator: i18n.BreakIterator = i18n.getLineInstance("en");
1558  iterator.setLineBreakText("Apple is my favorite fruit.");
1559  let isBoundary: boolean = iterator.isBoundary(0); // isBoundary = true;
1560  isBoundary = iterator.isBoundary(5); // isBoundary = false;
1561  ```
1562
1563
1564## i18n.getTimeZone
1565
1566getTimeZone(zoneID?: string): TimeZone
1567
1568Obtains the **TimeZone** object corresponding to the specified time zone ID.
1569
1570**Atomic service API**: This API can be used in atomic services since API version 12.
1571
1572**System capability**: SystemCapability.Global.I18n
1573
1574**Parameters**
1575
1576| Name   | Type    | Mandatory  | Description   |
1577| ------ | ------ | ---- | ----- |
1578| zoneID | string | No   | Time zone ID. The default value is the system time zone.|
1579
1580**Return value**
1581
1582| Type      | Description          |
1583| -------- | ------------ |
1584| [TimeZone](#timezone) | **TimeZone** object corresponding to the time zone ID.|
1585
1586**Example**
1587  ```ts
1588  let timezone: i18n.TimeZone = i18n.getTimeZone();
1589  ```
1590
1591## TimeZone
1592
1593### getID
1594
1595getID(): string
1596
1597Obtains the ID of the specified **TimeZone** object.
1598
1599**Atomic service API**: This API can be used in atomic services since API version 12.
1600
1601**System capability**: SystemCapability.Global.I18n
1602
1603**Return value**
1604
1605| Type    | Description          |
1606| ------ | ------------ |
1607| string | Time zone ID corresponding to the **TimeZone** object.|
1608
1609**Example**
1610  ```ts
1611  let timezone: i18n.TimeZone = i18n.getTimeZone();
1612  let timezoneID: string = timezone.getID(); // timezoneID = "Asia/Shanghai"
1613  ```
1614
1615
1616### getDisplayName
1617
1618getDisplayName(locale?: string, isDST?: boolean): string
1619
1620Obtains the localized representation of a **TimeZone** object.
1621
1622**Atomic service API**: This API can be used in atomic services since API version 12.
1623
1624**System capability**: SystemCapability.Global.I18n
1625
1626**Parameters**
1627
1628| Name   | Type     | Mandatory  | Description                  |
1629| ------ | ------- | ---- | -------------------- |
1630| 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.               |
1631| isDST  | boolean | No   | Whether DST is considered in the localized representation of the **TimeZone** object. The default value is **false**.|
1632
1633**Return value**
1634
1635| Type    | Description           |
1636| ------ | ------------- |
1637| string | Localized display of the **TimeZone** object in the specified locale.|
1638
1639**Example**
1640  ```ts
1641  let timezone: i18n.TimeZone = i18n.getTimeZone();
1642  let timezoneName: string = timezone.getDisplayName("zh-CN", false); // timezoneName = "China Standard Time"
1643  ```
1644
1645
1646### getRawOffset
1647
1648getRawOffset(): number
1649
1650Obtains the offset between the time zone represented by a **TimeZone** object and the UTC time zone.
1651
1652**Atomic service API**: This API can be used in atomic services since API version 12.
1653
1654**System capability**: SystemCapability.Global.I18n
1655
1656**Return value**
1657
1658| Type    | Description                 |
1659| ------ | ------------------- |
1660| number | Offset between the time zone represented by a **TimeZone** object and the UTC time zone, in milliseconds.|
1661
1662**Example**
1663  ```ts
1664  let timezone: i18n.TimeZone = i18n.getTimeZone();
1665  let offset: number = timezone.getRawOffset(); // offset = 28800000
1666  ```
1667
1668
1669### getOffset
1670
1671getOffset(date?: number): number
1672
1673Obtains the offset between the time zone represented by a **TimeZone** object and the UTC time zone at a certain time.
1674
1675**Atomic service API**: This API can be used in atomic services since API version 12.
1676
1677**System capability**: SystemCapability.Global.I18n
1678
1679**Parameters**
1680
1681| Name   | Type    | Mandatory  | Description    |
1682| ------ | ------ | ---- | ------ |
1683| date | number | No   | Time for calculating the offset, in milliseconds. The default value is the system time.|
1684
1685**Return value**
1686
1687| Type    | Description                     |
1688| ------ | ----------------------- |
1689| number | Offset between the time zone represented by the **TimeZone** object and the UTC time zone at a certain time.|
1690
1691**Example**
1692  ```ts
1693  let timezone: i18n.TimeZone = i18n.getTimeZone();
1694  let offset: number = timezone.getOffset(1234567890); // offset = 28800000
1695  ```
1696
1697
1698### getAvailableIDs<sup>9+</sup>
1699
1700static getAvailableIDs(): Array&lt;string&gt;
1701
1702Obtains the list of time zone IDs supported by the system.
1703
1704**Atomic service API**: This API can be used in atomic services since API version 12.
1705
1706**System capability**: SystemCapability.Global.I18n
1707
1708**Return value**
1709
1710| Type                 | Description         |
1711| ------------------- | ----------- |
1712| Array&lt;string&gt; | List of time zone IDs supported by the system.|
1713
1714**Example**
1715  ```ts
1716  // 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"]
1717  let ids: Array<string> = i18n.TimeZone.getAvailableIDs();
1718  ```
1719
1720
1721### getAvailableZoneCityIDs<sup>9+</sup>
1722
1723static getAvailableZoneCityIDs(): Array&lt;string&gt;
1724
1725Obtains the list of time zone city IDs supported by the system.
1726
1727**Atomic service API**: This API can be used in atomic services since API version 12.
1728
1729**System capability**: SystemCapability.Global.I18n
1730
1731**Return value**
1732
1733| Type                 | Description           |
1734| ------------------- | ------------- |
1735| Array&lt;string&gt; | List of time zone city IDs supported by the system.|
1736
1737**Example**
1738  ```ts
1739  // 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"]
1740  let cityIDs: Array<string> = i18n.TimeZone.getAvailableZoneCityIDs();
1741  ```
1742
1743### getCityDisplayName<sup>9+</sup>
1744
1745static getCityDisplayName(cityID: string, locale: string): string
1746
1747Obtains the localized representation of a time zone city in the specified locale.
1748
1749**Atomic service API**: This API can be used in atomic services since API version 12.
1750
1751**System capability**: SystemCapability.Global.I18n
1752
1753**Parameters**
1754
1755| Name   | Type    | Mandatory  | Description    |
1756| ------ | ------ | ---- | ------ |
1757| cityID | string | Yes   | Time zone city ID.|
1758| locale | string | Yes   | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region. |
1759
1760**Return value**
1761
1762| Type    | Description                |
1763| ------ | ------------------ |
1764| string | Localized display of the time zone city in the specified locale.|
1765
1766**Example**
1767  ```ts
1768  let displayName: string = i18n.TimeZone.getCityDisplayName("Shanghai", "zh-CN"); // displayName = "Shanghai (China)"
1769  ```
1770
1771
1772### getTimezoneFromCity<sup>9+</sup>
1773
1774static getTimezoneFromCity(cityID: string): TimeZone
1775
1776Obtains the **TimeZone** object corresponding to the specified time zone city ID.
1777
1778**Atomic service API**: This API can be used in atomic services since API version 12.
1779
1780**System capability**: SystemCapability.Global.I18n
1781
1782**Parameters**
1783
1784| Name   | Type    | Mandatory  | Description    |
1785| ------ | ------ | ---- | ------ |
1786| cityID | string | Yes   | Time zone city ID.|
1787
1788**Return value**
1789
1790| Type      | Description         |
1791| -------- | ----------- |
1792| TimeZone | **TimeZone** object corresponding to the specified time zone city ID.|
1793
1794**Example**
1795  ```ts
1796  let timezone: i18n.TimeZone = i18n.TimeZone.getTimezoneFromCity("Shanghai");
1797  ```
1798
1799### getTimezonesByLocation<sup>10+</sup>
1800
1801static getTimezonesByLocation(longitude: number, latitude: number): Array&lt;TimeZone&gt;
1802
1803Creates an array of **TimeZone** objects corresponding to the specified longitude and latitude.
1804
1805**Atomic service API**: This API can be used in atomic services since API version 12.
1806
1807**System capability**: SystemCapability.Global.I18n
1808
1809**Parameters**
1810
1811| Name    | Type    | Mandatory  | Description    |
1812| --------- | ------ | ---- | ------ |
1813| 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.|
1814| 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.|
1815
1816**Return value**
1817
1818| Type      | Description         |
1819| -------- | ----------- |
1820| Array&lt;[TimeZone](#timezone)&gt; | **TimeZone** object array.|
1821
1822**Error codes**
1823
1824For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md).
1825
1826| ID | Error Message                  |
1827| ------ | ---------------------- |
1828| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
1829| 890001 | Invalid parameter. Possible causes: Parameter verification failed. |
1830
1831
1832> **Description**
1833>
1834> The error message of 890001 is subject to the actual error.
1835
1836**Example**
1837  ```ts
1838  let timezoneArray: Array<i18n.TimeZone> = i18n.TimeZone.getTimezonesByLocation(-118.1, 34.0);
1839  for (let i = 0; i < timezoneArray.length; i++) {
1840      let tzId: string = timezoneArray[i].getID();
1841  }
1842  ```
1843
1844
1845## Transliterator<sup>9+</sup>
1846
1847
1848### getAvailableIDs<sup>9+</sup>
1849
1850static getAvailableIDs(): string[]
1851
1852Obtains a list of IDs supported by the **Transliterator** object.
1853
1854**Atomic service API**: This API can be used in atomic services since API version 12.
1855
1856**System capability**: SystemCapability.Global.I18n
1857
1858**Return value**
1859
1860| Type      | Description        |
1861| -------- | ---------- |
1862| string[] | List of IDs supported by the **Transliterator** object.|
1863
1864**Example**
1865  ```ts
1866  // 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.
1867  // For more information, see ISO-15924.
1868  let ids: string[] = i18n.Transliterator.getAvailableIDs();
1869  ```
1870
1871
1872### getInstance<sup>9+</sup>
1873
1874static getInstance(id: string): Transliterator
1875
1876Creates a **Transliterator** object.
1877
1878**Atomic service API**: This API can be used in atomic services since API version 12.
1879
1880**System capability**: SystemCapability.Global.I18n
1881
1882**Parameters**
1883
1884| Name | Type    | Mandatory  | Description      |
1885| ---- | ------ | ---- | -------- |
1886| id   | string | Yes   | ID supported by the **Transliterator** object.|
1887
1888**Return value**
1889
1890| Type                                | Description   |
1891| ---------------------------------- | ----- |
1892| [Transliterator](#transliterator9) | **Transliterator** object.|
1893
1894**Example**
1895  ```ts
1896  let transliterator: i18n.Transliterator = i18n.Transliterator.getInstance("Any-Latn");
1897  ```
1898
1899
1900### transform<sup>9+</sup>
1901
1902transform(text: string): string
1903
1904Converts the input string from the source format to the target format.
1905
1906**Atomic service API**: This API can be used in atomic services since API version 12.
1907
1908**System capability**: SystemCapability.Global.I18n
1909
1910**Parameters**
1911
1912| Name | Type    | Mandatory  | Description    |
1913| ---- | ------ | ---- | ------ |
1914| text | string | Yes   | Input string.|
1915
1916**Return value**
1917
1918| Type    | Description      |
1919| ------ | -------- |
1920| string | Target string.|
1921
1922**Example**
1923  ```ts
1924  let transliterator: i18n.Transliterator = i18n.Transliterator.getInstance("Any-Latn");
1925  let wordArray = ["中国", "德国", "美国", "法国"]
1926  for (let i = 0; i < wordArray.length; i++) {
1927      let res = transliterator.transform(wordArray[i]); // res: zhōng guó, dé guó, měi guó, fǎ guó
1928  }
1929
1930  // Chinese transliteration and tone removal
1931  let transliter = i18n.Transliterator.getInstance('Any-Latn;Latin-Ascii');
1932  let result = transliter.transform('中国'); // result: zhong guo
1933
1934  // Chinese surname pronunciation
1935  let nameTransliter = i18n.Transliterator.getInstance('Han-Latin/Names');
1936  let result1 = nameTransliter.transform('单老师'); // result1: shàn lǎo shī
1937  let result2 = nameTransliter.transform('长孙无忌'); // result2: zhǎng sūn wú jì
1938  ```
1939
1940
1941## Unicode<sup>9+</sup>
1942
1943**Atomic service API**: This API can be used in atomic services since API version 12.
1944
1945### isDigit<sup>9+</sup>
1946
1947static isDigit(char: string): boolean
1948
1949Checks whether the input string is composed of digits.
1950
1951**Atomic service API**: This API can be used in atomic services since API version 12.
1952
1953**System capability**: SystemCapability.Global.I18n
1954
1955**Parameters**
1956
1957| Name | Type    | Mandatory  | Description   |
1958| ---- | ------ | ---- | ----- |
1959| char | string | Yes   | Input string.|
1960
1961**Return value**
1962
1963| Type     | Description                                  |
1964| ------- | ------------------------------------ |
1965| boolean | The value **true** indicates that the input character is a digit, and the value **false** indicates the opposite.|
1966
1967**Example**
1968  ```ts
1969  let isdigit: boolean = i18n.Unicode.isDigit("1");  // isdigit = true
1970  ```
1971
1972
1973### isSpaceChar<sup>9+</sup>
1974
1975static isSpaceChar(char: string): boolean
1976
1977Checks whether the input character is a space.
1978
1979**Atomic service API**: This API can be used in atomic services since API version 12.
1980
1981**System capability**: SystemCapability.Global.I18n
1982
1983**Parameters**
1984
1985| Name | Type    | Mandatory  | Description   |
1986| ---- | ------ | ---- | ----- |
1987| char | string | Yes   | Input string.|
1988
1989**Return value**
1990
1991| Type     | Description                                    |
1992| ------- | -------------------------------------- |
1993| boolean | The value **true** indicates that the input character is a space, and the value **false** indicates the opposite.|
1994
1995**Example**
1996  ```ts
1997  let isspacechar: boolean = i18n.Unicode.isSpaceChar("a");  // isspacechar = false
1998  ```
1999
2000
2001### isWhitespace<sup>9+</sup>
2002
2003static isWhitespace(char: string): boolean
2004
2005Checks whether the input character is a white space.
2006
2007**Atomic service API**: This API can be used in atomic services since API version 12.
2008
2009**System capability**: SystemCapability.Global.I18n
2010
2011**Parameters**
2012
2013| Name | Type    | Mandatory  | Description   |
2014| ---- | ------ | ---- | ----- |
2015| char | string | Yes   | String obtained.|
2016
2017**Return value**
2018
2019| Type     | Description                                    |
2020| ------- | -------------------------------------- |
2021| boolean | The value **true** indicates that the input character is a white space, and the value **false** indicates the opposite.|
2022
2023**Example**
2024  ```ts
2025  let iswhitespace: boolean = i18n.Unicode.isWhitespace("a");  // iswhitespace = false
2026  ```
2027
2028
2029### isRTL<sup>9+</sup>
2030
2031static isRTL(char: string): boolean
2032
2033Checks whether the input character is of the right to left (RTL) language.
2034
2035**Atomic service API**: This API can be used in atomic services since API version 12.
2036
2037**System capability**: SystemCapability.Global.I18n
2038
2039**Parameters**
2040
2041| Name | Type    | Mandatory  | Description   |
2042| ---- | ------ | ---- | ----- |
2043| char | string | Yes   | Input character.|
2044
2045**Return value**
2046
2047| Type     | Description                                      |
2048| ------- | ---------------------------------------- |
2049| boolean | The value **true** indicates that the input character is of the RTL language, and the value **false** indicates the opposite.|
2050
2051**Example**
2052  ```ts
2053  let isrtl: boolean = i18n.Unicode.isRTL("a");  // isrtl = false
2054  ```
2055
2056
2057### isIdeograph<sup>9+</sup>
2058
2059static isIdeograph(char: string): boolean
2060
2061Checks whether the input character is an ideographic character.
2062
2063**Atomic service API**: This API can be used in atomic services since API version 12.
2064
2065**System capability**: SystemCapability.Global.I18n
2066
2067**Parameters**
2068
2069| Name | Type    | Mandatory  | Description   |
2070| ---- | ------ | ---- | ----- |
2071| char | string | Yes   | Input character.|
2072
2073**Return value**
2074
2075| Type     | Description                                      |
2076| ------- | ---------------------------------------- |
2077| boolean | The value **true** indicates that the input character is an ideographic character, and the value **false** indicates the opposite.|
2078
2079**Example**
2080  ```ts
2081  let isideograph: boolean = i18n.Unicode.isIdeograph("a");  // isideograph = false
2082  ```
2083
2084
2085### isLetter<sup>9+</sup>
2086
2087static isLetter(char: string): boolean
2088
2089Checks whether the input character is a letter.
2090
2091**Atomic service API**: This API can be used in atomic services since API version 12.
2092
2093**System capability**: SystemCapability.Global.I18n
2094
2095**Parameters**
2096
2097| Name | Type    | Mandatory  | Description   |
2098| ---- | ------ | ---- | ----- |
2099| char | string | Yes   | Input character.|
2100
2101**Return value**
2102
2103| Type     | Description                                  |
2104| ------- | ------------------------------------ |
2105| boolean | The value **true** indicates that the input character is a letter, and the value **false** indicates the opposite.|
2106
2107**Example**
2108  ```ts
2109  let isletter: boolean = i18n.Unicode.isLetter("a");  // isletter = true
2110  ```
2111
2112
2113### isLowerCase<sup>9+</sup>
2114
2115static isLowerCase(char: string): boolean
2116
2117Checks whether the input character is a lowercase letter.
2118
2119**Atomic service API**: This API can be used in atomic services since API version 12.
2120
2121**System capability**: SystemCapability.Global.I18n
2122
2123**Parameters**
2124
2125| Name | Type    | Mandatory  | Description   |
2126| ---- | ------ | ---- | ----- |
2127| char | string | Yes   | Input character.|
2128
2129**Return value**
2130
2131| Type     | Description                                      |
2132| ------- | ---------------------------------------- |
2133| boolean | The value **true** indicates that the input character is a lowercase letter, and the value **false** indicates the opposite.|
2134
2135**Example**
2136  ```ts
2137  let islowercase: boolean = i18n.Unicode.isLowerCase("a");  // islowercase = true
2138  ```
2139
2140
2141### isUpperCase<sup>9+</sup>
2142
2143static isUpperCase(char: string): boolean
2144
2145Checks whether the input character is an uppercase letter.
2146
2147**Atomic service API**: This API can be used in atomic services since API version 12.
2148
2149**System capability**: SystemCapability.Global.I18n
2150
2151**Parameters**
2152
2153| Name | Type    | Mandatory  | Description   |
2154| ---- | ------ | ---- | ----- |
2155| char | string | Yes   | Input character.|
2156
2157**Return value**
2158
2159| Type     | Description                                      |
2160| ------- | ---------------------------------------- |
2161| boolean | The value **true** indicates that the input character is an uppercase letter, and the value **false** indicates the opposite.|
2162
2163**Example**
2164  ```ts
2165  let isuppercase: boolean = i18n.Unicode.isUpperCase("a");  // isuppercase = false
2166  ```
2167
2168
2169### getType<sup>9+</sup>
2170
2171static getType(char: string): string
2172
2173Obtains the type of the input string.
2174
2175**Atomic service API**: This API can be used in atomic services since API version 12.
2176
2177**System capability**: SystemCapability.Global.I18n
2178
2179**Parameters**
2180
2181| Name | Type    | Mandatory  | Description   |
2182| ---- | ------ | ---- | ----- |
2183| char | string | Yes   | Input character.|
2184
2185**Return value**
2186
2187| Type    | Description         |
2188| ------ | ----------- |
2189| string | Type of the input character.|
2190
2191The following table lists only the common types. For more details, see the Unicode Standard.
2192
2193| Name| Value| Description|
2194| ---- | -------- | ---------- |
2195| U_UNASSIGNED | U_UNASSIGNED | Non-category for unassigned and non-character code points.|
2196| U_GENERAL_OTHER_TYPES | U_GENERAL_OTHER_TYPES | Same as **U_UNASSIGNED**.|
2197| U_UPPERCASE_LETTER | U_UPPERCASE_LETTER | Uppercase letter.|
2198| U_LOWERCASE_LETTER | U_LOWERCASE_LETTER | Lowercase letter. |
2199| U_TITLECASE_LETTER | U_TITLECASE_LETTER | Title case letter.|
2200| U_MODIFIER_LETTER | U_MODIFIER_LETTER | Modifier letter.|
2201| U_OTHER_LETTER | U_OTHER_LETTER | Letters other than the uppercase letter, lowercase letter, title case letter, and modifier letter.|
2202| U_NON_SPACING_MARK | U_NON_SPACING_MARK | Non-spacing mark, such as the accent symbol **'** and the variable symbol **#**.|
2203| U_ENCLOSING_MARK | U_ENCLOSING_MARK | Enclosing mark, for example, a circle or a box.|
2204| U_COMBINING_SPACING_MARK | U_COMBINING_SPACING_MARK | Spacing mark, for example, the vowel symbol **[]**.|
2205| U_DECIMAL_DIGIT_NUMBER | U_DECIMAL_DIGIT_NUMBER | Decimal number.|
2206| U_LETTER_NUMBER | U_LETTER_NUMBER | Letter and number (including Roman numeral).|
2207| U_OTHER_NUMBER | U_OTHER_NUMBER | Other numbers, which are used as encryption symbols, marker symbols, or non-Arabic numerals, such as **@**, **#**, **(1)**, and **①**.|
2208| U_SPACE_SEPARATOR | U_SPACE_SEPARATOR | Space separator, for example, a space character, uninterrupted space character, or space character with a fixed width.|
2209| U_LINE_SEPARATOR | U_LINE_SEPARATOR | Line separator.|
2210| U_PARAGRAPH_SEPARATOR | U_PARAGRAPH_SEPARATOR | Paragraph separator.|
2211| U_CONTROL_CHAR | U_CONTROL_CHAR | Control character.|
2212| U_FORMAT_CHAR | U_FORMAT_CHAR | Format character.|
2213| U_PRIVATE_USE_CHAR | U_PRIVATE_USE_CHAR | Privately used character, for example, a company logo.|
2214| U_SURROGATE | U_SURROGATE | Surrogate, which is used to represent supplementary characters in UTF-16.|
2215| U_DASH_PUNCTUATION | U_DASH_PUNCTUATION | Dash punctuation.|
2216| U_START_PUNCTUATION | U_START_PUNCTUATION | Start punctuation, for example, the left parenthesis.|
2217| U_END_PUNCTUATION | U_END_PUNCTUATION | End punctuation, for example, the right parenthesis.|
2218| U_INITIAL_PUNCTUATION | U_INITIAL_PUNCTUATION | Initial punctuation, for example, the left double quotation mark or left single quotation mark.|
2219| U_FINAL_PUNCTUATION | U_FINAL_PUNCTUATION | Final punctuation, for example, the right double quotation mark or right single quotation mark.|
2220| U_CONNECTOR_PUNCTUATION | U_CONNECTOR_PUNCTUATION | Connector punctuation.|
2221| U_OTHER_PUNCTUATION | U_OTHER_PUNCTUATION | Other punctuations.|
2222| U_MATH_SYMBOL | U_MATH_SYMBOL | Mathematical symbol.|
2223| U_CURRENCY_SYMBOL | U_CURRENCY_SYMBOL | Currency symbol.|
2224| U_MODIFIER_SYMBOL | U_MODIFIER_SYMBOL | Modifier symbol.|
2225| U_OTHER_SYMBOL | U_OTHER_SYMBOL | Other symbols.|
2226
2227**Example**
2228  ```ts
2229  let type: string = i18n.Unicode.getType("a"); // type = "U_LOWERCASE_LETTER"
2230  ```
2231
2232## I18NUtil<sup>9+</sup>
2233
2234
2235### unitConvert<sup>9+</sup>
2236
2237static unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale: string, style?: string): string
2238
2239Converts one measurement unit into another and formats the unit based on the specified locale and style.
2240
2241**Atomic service API**: This API can be used in atomic services since API version 12.
2242
2243**System capability**: SystemCapability.Global.I18n
2244
2245**Parameters**
2246
2247| Name     | Type                    | Mandatory  | Description                                      |
2248| -------- | ---------------------- | ---- | ---------------------------------------- |
2249| fromUnit | [UnitInfo](#unitinfo8) | Yes   | Measurement unit to be converted.                                |
2250| toUnit   | [UnitInfo](#unitinfo8) | Yes   | Measurement unit to be converted to.                                |
2251| value    | number                 | Yes   | Value of the measurement unit to be converted.                            |
2252| 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**.               |
2253| 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).|
2254
2255**Return value**
2256
2257| Type    | Description                     |
2258| ------ | ----------------------- |
2259| string | String obtained after formatting based on the measurement unit specified by **toUnit**.|
2260
2261**Example**
2262  ```ts
2263  let fromUnit: i18n.UnitInfo = {unit: "cup", measureSystem: "US"};
2264  let toUnit: i18n.UnitInfo = {unit: "liter", measureSystem: "SI"};
2265  let res: string = i18n.I18NUtil.unitConvert(fromUnit, toUnit, 1000, "en-US", "long"); // res = 236.588 liters
2266  ```
2267
2268### getDateOrder<sup>9+</sup>
2269
2270static getDateOrder(locale: string): string
2271
2272Obtains the sequence of the year, month, and day in the specified locale.
2273
2274**Atomic service API**: This API can be used in atomic services since API version 12.
2275
2276**System capability**: SystemCapability.Global.I18n
2277
2278**Parameters**
2279
2280| Name   | Type    | Mandatory  | Description                       |
2281| ------ | ------ | ---- | ------------------------- |
2282| 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**.|
2283
2284**Return value**
2285
2286| Type    | Description                 |
2287| ------ | ------------------- |
2288| string | Sequence of the year, month, and day in the locale.|
2289
2290**Example**
2291  ```ts
2292  let order: string = i18n.I18NUtil.getDateOrder("zh-CN");  // order = "y-L-d"
2293  ```
2294
2295
2296### getTimePeriodName<sup>11+</sup>
2297
2298static getTimePeriodName(hour:number, locale?: string): string
2299
2300Obtains the localized expression for the specified time of the specified locale.
2301
2302**Atomic service API**: This API can be used in atomic services since API version 12.
2303
2304**System capability**: SystemCapability.Global.I18n
2305
2306**Parameters**
2307
2308| Name   | Type    | Mandatory  | Description                       |
2309| ------ | ------ | ---- | ------------------------- |
2310| hour | number | Yes   | Specified time, for example, **16**.|
2311| 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.|
2312
2313**Return value**
2314
2315| Type    | Description                 |
2316| ------ | ------------------- |
2317| string | Localized expression for the specified time of the specified locale.|
2318
2319**Error codes**
2320
2321For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md).
2322
2323| ID | Error Message                  |
2324| ------ | ---------------------- |
2325| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
2326| 890001 | Invalid parameter. Possible causes: Parameter verification failed. |
2327
2328**Example**
2329  ```ts
2330  import { BusinessError } from '@kit.BasicServicesKit';
2331
2332  try {
2333    let name: string = i18n.I18NUtil.getTimePeriodName(2, "zh-CN");  // name = "a.m."
2334  } catch(error) {
2335    let err: BusinessError = error as BusinessError;
2336    console.error(`call I18NUtil.getTimePeriodName failed, error code: ${err.code}, message: ${err.message}.`);
2337  }
2338  ```
2339
2340### getBestMatchLocale<sup>12+</sup>
2341
2342static getBestMatchLocale(locale: string, localeList: string[]): string
2343
2344Obtains the locale that best matches a region from the specified locale list.
2345
2346**Atomic service API**: This API can be used in atomic services since API version 12.
2347
2348**System capability**: SystemCapability.Global.I18n
2349
2350**Parameters**
2351
2352| Name   | Type    | Mandatory  | Description                       |
2353| ------ | ------ | ---- | ------------------------- |
2354| locale | string | Yes   | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), for example, **zh-Hans-CN**.|
2355| localeList | string[] | Yes  | Locale list.|
2356
2357**Return value**
2358
2359| Type    | Description                 |
2360| ------ | ------------------- |
2361| string | ID of the locale that best matches a region. If no matching locale is found, an empty string is returned.|
2362
2363**Error codes**
2364
2365For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md).
2366
2367| ID | Error Message                  |
2368| ------ | ---------------------- |
2369| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
2370| 890001 | Invalid parameter. Possible causes: Parameter verification failed. |
2371
2372**Example**
2373
2374  ```ts
2375  import { BusinessError } from '@kit.BasicServicesKit';
2376
2377  try {
2378    let matchedLocaleId: string = i18n.I18NUtil.getBestMatchLocale("zh-Hans-CN", ["en-Latn-US", "en-GB", "zh-Hant-CN", "zh-Hans-MO"]);  // matchedLocaleId = "zh-Hans-MO"
2379  } catch(error) {
2380    let err: BusinessError = error as BusinessError;
2381    console.error(`call I18NUtil.getBestMatchLocale failed, error code: ${err.code}, message: ${err.message}.`);
2382  }
2383  ```
2384
2385### getThreeLetterLanguage<sup>12+</sup>
2386
2387static getThreeLetterLanguage(locale: string): string
2388
2389Converts 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).
2390
2391**Atomic service API**: This API can be used in atomic services since API version 12.
2392
2393**System capability**: SystemCapability.Global.I18n
2394
2395**Parameters**
2396
2397| Name| Type  | Mandatory| Description                    |
2398| ------ | ------ | ---- | ------------------------ |
2399| locale | string | Yes  | Two-letter code of the language to be converted, for example, **zh**.|
2400
2401**Error codes**
2402
2403For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md).
2404
2405| ID| Error Message                                                    |
2406| -------- | ------------------------------------------------------------ |
2407| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
2408| 890001   | Invalid parameter. Possible causes: Parameter verification failed. |
2409
2410**Example**
2411
2412  ```ts
2413  import { BusinessError } from '@kit.BasicServicesKit';
2414
2415  try {
2416    let language : string = i18n.I18NUtil.getThreeLetterLanguage('zh')  // zho
2417  } catch(error) {
2418    console.error(`call I18NUtil.getThreeLetterLanguage failed, error code: ${error.code}, message: ${error.message}.`);
2419  }
2420  ```
2421
2422### getThreeLetterRegion<sup>12+</sup>
2423
2424static getThreeLetterRegion(locale: string): string
2425
2426Converts 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).
2427
2428**Atomic service API**: This API can be used in atomic services since API version 12.
2429
2430**System capability**: SystemCapability.Global.I18n
2431
2432**Parameters**
2433
2434| Name| Type  | Mandatory| Description                    |
2435| ------ | ------ | ---- | ------------------------ |
2436| locale | string | Yes  | Two-letter country/region code to be converted, for example, **CN**.|
2437
2438**Error codes**
2439
2440For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md).
2441
2442| ID| Error Message                                                    |
2443| -------- | ------------------------------------------------------------ |
2444| 401      | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
2445| 890001   | Invalid parameter. Possible causes: Parameter verification failed. |
2446
2447**Example**
2448
2449  ```ts
2450  import { BusinessError } from '@kit.BasicServicesKit';
2451
2452  try {
2453    let region : string = i18n.I18NUtil.getThreeLetterRegion('CN')  // CHN
2454  } catch(error) {
2455    console.error(`call I18NUtil.getThreeLetterRegion failed, error code: ${error.code}, message: ${error.message}.`);
2456  }
2457  ```
2458
2459## Normalizer<sup>10+</sup>
2460
2461
2462### getInstance<sup>10+</sup>
2463
2464static getInstance(mode: NormalizerMode): Normalizer
2465
2466Obtains a **Normalizer** object for text normalization.
2467
2468**Atomic service API**: This API can be used in atomic services since API version 12.
2469
2470**System capability**: SystemCapability.Global.I18n
2471
2472**Parameters**
2473
2474| Name   | Type    | Mandatory  | Description                       |
2475| ------ | ------ | ---- | ------------------------- |
2476| mode | [NormalizerMode](#normalizermode10) | Yes   | Text normalization mode.|
2477
2478**Return value**
2479
2480| Type    | Description                 |
2481| ------ | ------------------- |
2482| [Normalizer](#normalizer10) | **Normalizer** object for text normalization.|
2483
2484**Error codes**
2485
2486For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
2487
2488| ID | Error Message                  |
2489| ------ | ---------------------- |
2490| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
2491
2492**Example**
2493  ```ts
2494  let normalizer: i18n.Normalizer = i18n.Normalizer.getInstance(i18n.NormalizerMode.NFC);
2495  ```
2496
2497
2498### normalize<sup>10+</sup>
2499
2500normalize(text: string): string
2501
2502Normalizes text strings.
2503
2504**Atomic service API**: This API can be used in atomic services since API version 12.
2505
2506**System capability**: SystemCapability.Global.I18n
2507
2508**Parameters**
2509
2510| Name   | Type    | Mandatory  | Description                       |
2511| ------ | ------ | ---- | ------------------------- |
2512| text | string | Yes   | Text strings to be normalized.|
2513
2514**Return value**
2515
2516| Type    | Description                 |
2517| ------ | ------------------- |
2518| string | Normalized text strings.|
2519
2520**Error codes**
2521
2522For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
2523
2524| ID | Error Message                  |
2525| ------ | ---------------------- |
2526| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
2527
2528**Example**
2529  ```ts
2530  let normalizer: i18n.Normalizer = i18n.Normalizer.getInstance(i18n.NormalizerMode.NFC);
2531  let normalizedText: string = normalizer.normalize('\u1E9B\u0323'); // normalizedText = ẛ̣
2532  ```
2533
2534## NormalizerMode<sup>10+</sup>
2535
2536Enumerates text normalization modes.
2537
2538**Atomic service API**: This API can be used in atomic services since API version 12.
2539
2540**System capability**: SystemCapability.Global.I18n
2541
2542| Name| Value| Description|
2543| -------- | -------- | -------- |
2544| NFC | 1 | NFC.|
2545| NFD | 2 | NFD.|
2546| NFKC | 3 | NFKC.|
2547| NFKD | 4 | NFKD.|
2548
2549
2550## HolidayManager<sup>11+</sup>
2551
2552
2553### constructor<sup>11+</sup>
2554
2555constructor(icsPath: String)
2556
2557Creates a **HolidayManager** object.
2558
2559**Atomic service API**: This API can be used in atomic services since API version 12.
2560
2561**System capability**: SystemCapability.Global.I18n
2562
2563**Parameters**
2564
2565|   Name |      Type     | Mandatory|     Description     |
2566| --------- | ------------- | ---- | ------------- |
2567| icsPath   | String | Yes  | Path of the **.ics** file with the read permission granted for applications. |
2568
2569**Error codes**
2570
2571For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md).
2572
2573| ID | Error Message                  |
2574| ------ | ---------------------- |
2575| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
2576| 890001 | Invalid parameter. Possible causes: Parameter verification failed. |
2577
2578**Example**
2579  ```ts
2580  let holidayManager= new i18n.HolidayManager("/system/lib/US.ics");
2581  ```
2582
2583### isHoliday<sup>11+</sup>
2584
2585isHoliday(date?: Date): boolean
2586
2587Determines whether the specified date is a holiday.
2588
2589**Atomic service API**: This API can be used in atomic services since API version 12.
2590
2591**System capability**: SystemCapability.Global.I18n
2592
2593**Parameters**
2594
2595|   Name |      Type     | Mandatory|     Description     |
2596| --------- | ---------------| ---- | ------------- |
2597| date      | Date           | No  | **Date** object.<br>If no date is specified, the current date is used by default.|
2598
2599**Return value**
2600
2601|       Type       |         Description         |
2602| ----------------- | ----------------------|
2603| boolean           | The value **true** indicates that the specified date is a holiday, and the value **false** indicates the opposite.|
2604
2605**Error codes**
2606
2607For details about the error codes, see [Universal Error Codes](../errorcode-universal.md).
2608
2609| ID | Error Message                  |
2610| ------ | ---------------------- |
2611| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
2612
2613**Example**
2614  ```ts
2615  import { BusinessError } from '@kit.BasicServicesKit';
2616
2617  try {
2618    let holidayManager= new i18n.HolidayManager("/system/lib/US.ics");
2619    let isHoliday = holidayManager.isHoliday();
2620    console.log(isHoliday.toString());
2621    let isHoliday2 = holidayManager.isHoliday(new Date(2023,5,25));
2622    console.log(isHoliday2.toString());
2623  } catch(error) {
2624    let err: BusinessError = error as BusinessError;
2625    console.error(`call holidayManager.isHoliday failed, error code: ${err.code}, message: ${err.message}.`);
2626  }
2627  ```
2628
2629
2630### getHolidayInfoItemArray<sup>11+</sup>
2631
2632getHolidayInfoItemArray(year?: number): Array&lt;[HolidayInfoItem](#holidayinfoitem11)&gt;
2633
2634Obtains the holiday information list of the specified year.
2635
2636**Atomic service API**: This API can be used in atomic services since API version 12.
2637
2638**System capability**: SystemCapability.Global.I18n
2639
2640**Parameters**
2641
2642|   Name |      Type     | Mandatory|     Description     |
2643| --------- | -------------  | ---- | ------------- |
2644| year      | number         | No  | Specified year, for example, 2023.<br>If no year is specified, the current year is used by default.|
2645
2646**Return value**
2647
2648|       Type       |         Description         |
2649| ----------------- | -------------------- |
2650| Array&lt;[HolidayInfoItem](#holidayinfoitem11)&gt; | Holiday information list.|
2651
2652**Error codes**
2653
2654For details about the error codes, see [ohos.i18n Error Codes](errorcode-i18n.md) and [Universal Error Codes](../errorcode-universal.md).
2655
2656| ID | Error Message                  |
2657| ------ | ---------------------- |
2658| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
2659| 890001 | Invalid parameter. Possible causes: Parameter verification failed. |
2660
2661**Example**
2662  ```ts
2663  import { BusinessError } from '@kit.BasicServicesKit';
2664
2665  try {
2666    let holidayManager= new i18n.HolidayManager("/system/lib/US.ics");
2667    let holidayInfoItemArray = holidayManager.getHolidayInfoItemArray(2023);
2668    for (let i =0; i < holidayInfoItemArray.length; i++) {
2669        console.log(JSON.stringify(holidayInfoItemArray[i]));
2670    }
2671  } catch(error) {
2672    let err: BusinessError = error as BusinessError;
2673    console.error(`call holidayManager.getHolidayInfoItemArray failed, error code: ${err.code}, message: ${err.message}.`);
2674  }
2675  ```
2676
2677## HolidayInfoItem<sup>11+</sup>
2678
2679Represents the holiday information.
2680
2681**Atomic service API**: This API can be used in atomic services since API version 12.
2682
2683**System capability**: SystemCapability.Global.I18n
2684
2685| Name           | Type            |  Mandatory  |  Description                                  |
2686| --------------- | --------------- | ------  | --------------------------------------- |
2687| baseName        | string          |   Yes   | Holiday name.             |
2688| year            | number          |   Yes   | Year of the holiday.                  |
2689| month           | number          |   Yes   | Month of the holiday.         |
2690| day             | number          |   Yes   | Day of the holiday.                        |
2691| localNames      | Array&lt;[HolidayLocalName](#holidaylocalname11)&gt;          |   No   | Local names of the holiday.         |
2692
2693## HolidayLocalName<sup>11+</sup>
2694
2695Defines the local names of a holiday.
2696
2697**Atomic service API**: This API can be used in atomic services since API version 12.
2698
2699**System capability**: SystemCapability.Global.I18n
2700
2701| Name           | Type            |  Mandatory  |  Description                                  |
2702| --------------- | -----------------| ------  | --------------------------------------- |
2703| language        | string           |   Yes   | Local language of a holiday, for example, **ar**, **en**, or **tr**.         |
2704| name            | string           |   Yes   | Local name of a holiday. For example, the Turkish name of Sacrifice Feast is Kurban Bayrami.     |
2705
2706
2707## i18n.getDisplayCountry<sup>(deprecated)</sup>
2708
2709getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): string
2710
2711Obtains the localized script for the specified country.
2712
2713This API is deprecated since API version 9. You are advised to use [System.getDisplayCountry](#getdisplaycountry9).
2714
2715**System capability**: SystemCapability.Global.I18n
2716
2717**Parameters**
2718
2719| Name         | Type     | Mandatory  | Description              |
2720| ------------ | ------- | ---- | ---------------- |
2721| country      | string  | Yes   | Specified country.           |
2722| locale       | string  | Yes   | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region.     |
2723| sentenceCase | boolean | No   | Whether to use sentence case for the localized script. The default value is **true**.|
2724
2725**Return value**
2726
2727| Type    | Description           |
2728| ------ | ------------- |
2729| string | Localized script for the specified country.|
2730
2731**Example**
2732  ```ts
2733  let countryName: string = i18n.getDisplayCountry("zh-CN", "en-GB", true); // countryName = China
2734  countryName = i18n.getDisplayCountry("zh-CN", "en-GB"); // countryName = China
2735  ```
2736
2737## i18n.getDisplayCountry<sup>(deprecated)</sup>
2738
2739getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): string
2740
2741Obtains the localized script for the specified country.
2742
2743This API is deprecated since API version 9. You are advised to use [System.getDisplayCountry](#getdisplaycountry9).
2744
2745**System capability**: SystemCapability.Global.I18n
2746
2747**Parameters**
2748
2749| Name         | Type     | Mandatory  | Description              |
2750| ------------ | ------- | ---- | ---------------- |
2751| country      | string  | Yes   | Specified country.           |
2752| locale       | string  | Yes   | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region.     |
2753| sentenceCase | boolean | No   | Whether to use sentence case for the localized script. The default value is **true**.|
2754
2755**Return value**
2756
2757| Type    | Description           |
2758| ------ | ------------- |
2759| string | Localized script for the specified country.|
2760
2761**Example**
2762  ```ts
2763  let countryName: string = i18n.getDisplayCountry("zh-CN", "en-GB", true); // countryName = China
2764  countryName = i18n.getDisplayCountry("zh-CN", "en-GB"); // countryName = China
2765  ```
2766
2767
2768## i18n.getDisplayLanguage<sup>(deprecated)</sup>
2769
2770getDisplayLanguage(language: string, locale: string, sentenceCase?: boolean): string
2771
2772Obtains the localized script for the specified language.
2773
2774This API is deprecated since API version 9. You are advised to use [System.getDisplayLanguage](#getdisplaylanguage9).
2775
2776**System capability**: SystemCapability.Global.I18n
2777
2778**Parameters**
2779
2780| Name         | Type     | Mandatory  | Description              |
2781| ------------ | ------- | ---- | ---------------- |
2782| language     | string  | Yes   | Specified language.           |
2783| locale       | string  | Yes   | [Locale information](../../internationalization/i18n-locale-culture.md#how-it-works), which consists of the language, script, and country/region.     |
2784| sentenceCase | boolean | No   | Whether to use sentence case for the localized script. The default value is **true**.|
2785
2786**Return value**
2787
2788| Type    | Description           |
2789| ------ | ------------- |
2790| string | Localized script for the specified language.|
2791
2792**Example**
2793  ```ts
2794  let languageName: string = i18n.getDisplayLanguage("zh", "en-GB", true); // languageName = "Chinese"
2795  languageName = i18n.getDisplayLanguage("zh", "en-GB"); // languageName = "Chinese"
2796  ```
2797
2798
2799## i18n.getSystemLanguage<sup>(deprecated)</sup>
2800
2801getSystemLanguage(): string
2802
2803Obtains the system language.
2804
2805This API is deprecated since API version 9. You are advised to use [System.getSystemLanguage](#getsystemlanguage9).
2806
2807**System capability**: SystemCapability.Global.I18n
2808
2809**Return value**
2810
2811| Type    | Description     |
2812| ------ | ------- |
2813| string | System language ID.|
2814
2815**Example**
2816  ```ts
2817  let systemLanguage: string = i18n.getSystemLanguage(); // Obtain the current system language.
2818  ```
2819
2820
2821## i18n.getSystemRegion<sup>(deprecated)</sup>
2822
2823getSystemRegion(): string
2824
2825Obtains the system region.
2826
2827This API is deprecated since API version 9. You are advised to use [System.getSystemRegion](#getsystemregion9).
2828
2829**System capability**: SystemCapability.Global.I18n
2830
2831**Return value**
2832
2833| Type    | Description     |
2834| ------ | ------- |
2835| string | System region ID.|
2836
2837**Example**
2838  ```ts
2839  let region: string = i18n.getSystemRegion(); // Obtain the current system region.
2840  ```
2841
2842
2843## i18n.getSystemLocale<sup>(deprecated)</sup>
2844
2845getSystemLocale(): string
2846
2847Obtains the system locale.
2848
2849This API is deprecated since API version 9. You are advised to use [System.getSystemLocale](#getsystemlocale9).
2850
2851**System capability**: SystemCapability.Global.I18n
2852
2853**Return value**
2854
2855| Type    | Description     |
2856| ------ | ------- |
2857| string | System locale ID.|
2858
2859**Example**
2860  ```ts
2861  let locale: string = i18n.getSystemLocale (); // Obtain the system locale.
2862  ```
2863
2864
2865## i18n.is24HourClock<sup>(deprecated)</sup>
2866
2867is24HourClock(): boolean
2868
2869Checks whether the 24-hour clock is used.
2870
2871This API is deprecated since API version 9. You are advised to use [System.is24HourClock](#is24hourclock9).
2872
2873**System capability**: SystemCapability.Global.I18n
2874
2875**Return value**
2876
2877| Type     | Description                                      |
2878| ------- | ---------------------------------------- |
2879| boolean | The value **true** indicates that the 24-hour clock is used, and the value **false** indicates the opposite.|
2880
2881**Example**
2882  ```ts
2883  let is24HourClock: boolean = i18n.is24HourClock();
2884  ```
2885
2886
2887## i18n.set24HourClock<sup>(deprecated)</sup>
2888
2889set24HourClock(option: boolean): boolean
2890
2891Sets the 24-hour clock.
2892
2893This API is deprecated since API version 9. The substitute API is available only for system applications.
2894
2895**Permission required**: ohos.permission.UPDATE_CONFIGURATION
2896
2897**System capability**: SystemCapability.Global.I18n
2898
2899**Parameters**
2900
2901| Name   | Type     | Mandatory  | Description                                      |
2902| ------ | ------- | ---- | ---------------------------------------- |
2903| 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.|
2904
2905**Return value**
2906
2907| Type     | Description                           |
2908| ------- | ----------------------------- |
2909| boolean | The value **true** indicates that the 24-hour clock is enabled, and the value **false** indicates the opposite.|
2910
2911**Example**
2912  ```ts
2913  // Set the system time to the 24-hour clock.
2914  let success: boolean = i18n.set24HourClock(true);
2915  ```
2916
2917
2918## i18n.addPreferredLanguage<sup>(deprecated)</sup>
2919
2920addPreferredLanguage(language: string, index?: number): boolean
2921
2922Adds a preferred language to the specified position on the preferred language list.
2923
2924This API is supported since API version 8 and is deprecated since API version 9. The substitute API is available only for system applications.
2925
2926**Permission required**: ohos.permission.UPDATE_CONFIGURATION
2927
2928**System capability**: SystemCapability.Global.I18n
2929
2930**Parameters**
2931
2932| Name     | Type    | Mandatory  | Description        |
2933| -------- | ------ | ---- | ---------- |
2934| language | string | Yes   | Preferred language to add. |
2935| index    | number | No   | Position to which the preferred language is added. The default value is the length of the preferred language list.|
2936
2937**Return value**
2938
2939| Type     | Description                           |
2940| ------- | ----------------------------- |
2941| boolean | The value **true** indicates that the preferred language is successfully added, and the value **false** indicates the opposite.|
2942
2943**Example**
2944  ```ts
2945  // Add zh-CN to the preferred language list.
2946  let language: string = 'zh-CN';
2947  let index: number = 0;
2948  let success: boolean = i18n.addPreferredLanguage(language, index);
2949  ```
2950
2951
2952## i18n.removePreferredLanguage<sup>(deprecated)</sup>
2953
2954removePreferredLanguage(index: number): boolean
2955
2956Deletes a preferred language from the specified position on the preferred language list.
2957
2958This API is supported since API version 8 and is deprecated since API version 9. The substitute API is available only for system applications.
2959
2960**Permission required**: ohos.permission.UPDATE_CONFIGURATION
2961
2962**System capability**: SystemCapability.Global.I18n
2963
2964**Parameters**
2965
2966| Name  | Type    | Mandatory  | Description                   |
2967| ----- | ------ | ---- | --------------------- |
2968| index | number | Yes   | Position of the preferred language to delete.|
2969
2970**Return value**
2971
2972| Type     | Description                           |
2973| ------- | ----------------------------- |
2974| boolean | The value **true** indicates that the preferred language is deleted, and the value **false** indicates the opposite.|
2975
2976**Example**
2977  ```ts
2978  // Delete the first preferred language from the preferred language list.
2979  let index: number = 0;
2980  let success: boolean = i18n.removePreferredLanguage(index);
2981  ```
2982
2983
2984## i18n.getPreferredLanguageList<sup>(deprecated)</sup>
2985
2986getPreferredLanguageList(): Array&lt;string&gt;
2987
2988Obtains the list of preferred languages.
2989
2990This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [System.getPreferredLanguageList](#getpreferredlanguagelist9).
2991
2992**System capability**: SystemCapability.Global.I18n
2993
2994**Return value**
2995
2996| Type                 | Description       |
2997| ------------------- | --------- |
2998| Array&lt;string&gt; | List of preferred languages.|
2999
3000**Example**
3001  ```ts
3002  let preferredLanguageList: Array<string> = i18n.getPreferredLanguageList(); // Obtain the preferred language list.
3003  ```
3004
3005
3006## i18n.getFirstPreferredLanguage<sup>(deprecated)</sup>
3007
3008getFirstPreferredLanguage(): string
3009
3010Obtains the first language in the preferred language list.
3011
3012This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [System.getFirstPreferredLanguage](#getfirstpreferredlanguage9).
3013
3014**System capability**: SystemCapability.Global.I18n
3015
3016**Return value**
3017
3018| Type    | Description            |
3019| ------ | -------------- |
3020| string | First language in the preferred language list.|
3021
3022**Example**
3023  ```ts
3024  let firstPreferredLanguage: string = i18n.getFirstPreferredLanguage();
3025  ```
3026
3027
3028## Util<sup>(deprecated)</sup>
3029
3030
3031### unitConvert<sup>(deprecated)</sup>
3032
3033unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale: string, style?: string): string
3034
3035Converts one measurement unit into another and formats the unit based on the specified locale and style.
3036
3037This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [unitConvert](#unitconvert9).
3038
3039**System capability**: SystemCapability.Global.I18n
3040
3041**Parameters**
3042
3043| Name     | Type                    | Mandatory  | Description                                      |
3044| -------- | ---------------------- | ---- | ---------------------------------------- |
3045| fromUnit | [UnitInfo](#unitinfo8) | Yes   | Measurement unit to be converted.                                |
3046| toUnit   | [UnitInfo](#unitinfo8) | Yes   | Measurement unit to be converted to.                                |
3047| value    | number                 | Yes   | Value of the measurement unit to be converted.                            |
3048| locale   | string                 | Yes   | Locale used for formatting, for example, **zh-Hans-CN**.               |
3049| style    | string                 | No   | Style used for formatting. The value can be **long**, **short**, or **narrow**. The default value is **short**.|
3050
3051**Return value**
3052
3053| Type    | Description                     |
3054| ------ | ----------------------- |
3055| string | String obtained after formatting based on the measurement unit specified by **toUnit**.|
3056
3057
3058## Character<sup>(deprecated)</sup>
3059
3060
3061### isDigit<sup>(deprecated)</sup>
3062
3063isDigit(char: string): boolean
3064
3065Checks whether the input string is composed of digits.
3066
3067This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [isDigit](#isdigit9).
3068
3069**System capability**: SystemCapability.Global.I18n
3070
3071**Parameters**
3072
3073| Name | Type    | Mandatory  | Description   |
3074| ---- | ------ | ---- | ----- |
3075| char | string | Yes   | Input character.|
3076
3077**Return value**
3078
3079| Type     | Description                                  |
3080| ------- | ------------------------------------ |
3081| boolean | The value **true** indicates that the input character is a digit, and the value **false** indicates the opposite.|
3082
3083
3084### isSpaceChar<sup>(deprecated)</sup>
3085
3086isSpaceChar(char: string): boolean
3087
3088Checks whether the input character is a space.
3089
3090This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [isSpaceChar](#isspacechar9).
3091
3092**System capability**: SystemCapability.Global.I18n
3093
3094**Parameters**
3095
3096| Name | Type    | Mandatory  | Description   |
3097| ---- | ------ | ---- | ----- |
3098| char | string | Yes   | Input character.|
3099
3100**Return value**
3101
3102| Type     | Description                                    |
3103| ------- | -------------------------------------- |
3104| boolean | The value **true** indicates that the input character is a space, and the value **false** indicates the opposite.|
3105
3106
3107### isWhitespace<sup>(deprecated)</sup>
3108
3109isWhitespace(char: string): boolean
3110
3111Checks whether the input character is a white space.
3112
3113This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [isWhitespace](#iswhitespace9).
3114
3115**System capability**: SystemCapability.Global.I18n
3116
3117**Parameters**
3118
3119| Name | Type    | Mandatory  | Description   |
3120| ---- | ------ | ---- | ----- |
3121| char | string | Yes   | Input character.|
3122
3123**Return value**
3124
3125| Type     | Description                                    |
3126| ------- | -------------------------------------- |
3127| boolean | The value **true** indicates that the input character is a white space, and the value **false** indicates the opposite.|
3128
3129
3130### isRTL<sup>(deprecated)</sup>
3131
3132isRTL(char: string): boolean
3133
3134Checks whether the input character is of the right to left (RTL) language.
3135
3136This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [isRTL](#isrtl9).
3137
3138**System capability**: SystemCapability.Global.I18n
3139
3140**Parameters**
3141
3142| Name | Type    | Mandatory  | Description   |
3143| ---- | ------ | ---- | ----- |
3144| char | string | Yes   | Input character.|
3145
3146**Return value**
3147
3148| Type     | Description                                      |
3149| ------- | ---------------------------------------- |
3150| boolean | The value **true** indicates that the input character is of the RTL language, and the value **false** indicates the opposite.|
3151
3152
3153### isIdeograph<sup>(deprecated)</sup>
3154
3155isIdeograph(char: string): boolean
3156
3157Checks whether the input character is an ideographic character.
3158
3159This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [isIdeograph](#isideograph9).
3160
3161**System capability**: SystemCapability.Global.I18n
3162
3163**Parameters**
3164
3165| Name | Type    | Mandatory  | Description   |
3166| ---- | ------ | ---- | ----- |
3167| char | string | Yes   | Input character.|
3168
3169**Return value**
3170
3171| Type     | Description                                      |
3172| ------- | ---------------------------------------- |
3173| boolean | The value **true** indicates that the input character is an ideographic character, and the value **false** indicates the opposite.|
3174
3175
3176### isLetter<sup>(deprecated)</sup>
3177
3178isLetter(char: string): boolean
3179
3180Checks whether the input character is a letter.
3181
3182This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [isLetter](#isletter9).
3183
3184**System capability**: SystemCapability.Global.I18n
3185
3186**Parameters**
3187
3188| Name | Type    | Mandatory  | Description   |
3189| ---- | ------ | ---- | ----- |
3190| char | string | Yes   | Input character.|
3191
3192**Return value**
3193
3194| Type     | Description                                  |
3195| ------- | ------------------------------------ |
3196| boolean | The value **true** indicates that the input character is a letter, and the value **false** indicates the opposite.|
3197
3198
3199### isLowerCase<sup>(deprecated)</sup>
3200
3201isLowerCase(char: string): boolean
3202
3203Checks whether the input character is a lowercase letter.
3204
3205This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [isLowerCase](#islowercase9).
3206
3207**System capability**: SystemCapability.Global.I18n
3208
3209**Parameters**
3210
3211| Name | Type    | Mandatory  | Description   |
3212| ---- | ------ | ---- | ----- |
3213| char | string | Yes   | Input character.|
3214
3215**Return value**
3216
3217| Type     | Description                                      |
3218| ------- | ---------------------------------------- |
3219| boolean | The value **true** indicates that the input character is a lowercase letter, and the value **false** indicates the opposite.|
3220
3221
3222### isUpperCase<sup>(deprecated)</sup>
3223
3224isUpperCase(char: string): boolean
3225
3226Checks whether the input character is an uppercase letter.
3227
3228This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [isUpperCase](#isuppercase9).
3229
3230**System capability**: SystemCapability.Global.I18n
3231
3232**Parameters**
3233
3234| Name | Type    | Mandatory  | Description   |
3235| ---- | ------ | ---- | ----- |
3236| char | string | Yes   | Input character.|
3237
3238**Return value**
3239
3240| Type     | Description                                      |
3241| ------- | ---------------------------------------- |
3242| boolean | The value **true** indicates that the input character is an uppercase letter, and the value **false** indicates the opposite.|
3243
3244
3245### getType<sup>(deprecated)</sup>
3246
3247getType(char: string): string
3248
3249Obtains the type of the input string.
3250
3251This API is supported since API version 8 and is deprecated since API version 9. You are advised to use [getType](#gettype9).
3252
3253**System capability**: SystemCapability.Global.I18n
3254
3255**Parameters**
3256
3257| Name | Type    | Mandatory  | Description   |
3258| ---- | ------ | ---- | ----- |
3259| char | string | Yes   | Input character.|
3260
3261**Return value**
3262
3263| Type    | Description         |
3264| ------ | ----------- |
3265| string | Type of the input character.|
3266
3267<!--no_check-->