1# Internationalization Development (I18N) 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. For more details about APIs and their usage, see [I18N](../reference/apis/js-apis-i18n.md). 4 5The [Intl](intl-guidelines.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. 6 7## Obtaining System Language and Region Information 8 9You can use APIs provided in the following table to obtain the system language and region information. 10 11 12### Available APIs 13 14| Module | API | Description | 15| -------- | -------- | -------- | 16| ohos.i18n | getSystemLanguage(): string | Obtains the system language. | 17| ohos.i18n | getSystemRegion(): string | Obtains the system region. | 18| ohos.i18n | getSystemLocale(): string | Obtains the system locale. | 19| ohos.i18n | isRTL(locale: string): boolean<sup>7+</sup> | Checks whether the locale uses a right-to-left (RTL) language. | 20| ohos.i18n | is24HourClock(): boolean<sup>7+</sup> | Checks whether the system uses a 24-hour clock. | 21| ohos.i18n | getDisplayLanguage(language: string, locale: string, sentenceCase?: boolean): string | Obtains the localized display of a language. | 22| ohos.i18n | getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): string | Obtains the localized display of a country name. | 23 24 25### How to Develop 26 271. Obtain the system language. 28 29 Call the **getSystemLanguage** method to obtain the system language (**i18n** is the name of the imported module). 30 31 32 ```js 33 var language = i18n.getSystemLanguage(); 34 ``` 35 362. Obtain the system region. 37 38 Call the **getSystemRegion** method to obtain the system region. 39 40 ```js 41 var region = i18n.getSystemRegion(); 42 ``` 43 443. Obtain the system locale. 45 46 Call the **getSystemLocale** method to obtain the system locale. 47 48 ```js 49 var locale = i18n.getSystemLocale(); 50 ``` 51 524. Check whether the locale's language is RTL. 53 54 Call the **isRTL** method to check whether the locale's language is RTL. 55 56 ```js 57 var rtl = i18n.isRTL("zh-CN"); 58 ``` 59 605. Check whether the system uses a 24-hour clock. 61 62 Call the **is24HourClock** method to check whether the system uses a 24-hour clock. 63 64 ```js 65 var hourClock = i18n.is24HourClock(); 66 ``` 67 686. Obtain the localized display of a language. 69 70 Call the **getDisplayLanguage** method to obtain the localized display of a language. **language** indicates the language to be localized, **locale** indicates the locale, and **sentenceCase** indicates whether the first letter of the result must be capitalized. 71 72 ```js 73 var language = "en"; 74 var locale = "zh-CN"; 75 var sentenceCase = false; 76 var localizedLanguage = i18n.getDisplayLanguage(language, locale, sentenceCase); 77 ``` 78 797. Obtain the localized display of a country. 80 81 Call the **getDisplayCountry** method to obtain the localized display of a country name. **country** indicates the country code (a two-letter code in compliance with ISO-3166, for example, CN), **locale** indicates the locale, and **sentenceCase** indicates whether the first letter of the result must be capitalized. 82 83 ```js 84 var country = "US"; 85 var locale = "zh-CN"; 86 var sentenceCase = false; 87 var localizedCountry = i18n.getDisplayCountry(country, locale, sentenceCase); 88 ``` 89 90 91## Obtaining Calendar Information 92 93[Calendar](../reference/apis/js-apis-i18n.md#calendar8) APIs are used to obtain calendar information, for example, the localized display of the calendar, the first day of a week, and the minimum count of days in the first week of a year. 94 95 96### Available APIs 97 98| Module | API | Description | 99| -------- | -------- | -------- | 100| ohos.i18n | getCalendar(locale: string, type?: string): Calendar<sup>8+</sup> | Obtains the **Calendar** object for a specific locale and type. | 101| ohos.i18n | setTime(date: Date): void<sup>8+</sup> | Sets the date for the **Calendar** object. | 102| ohos.i18n | setTime(time: number): void<sup>8+</sup> | Sets the time for the **Calendar** object. | 103| ohos.i18n | set(year: number, month: number, date: number, hour?: number, minute?: number, second?: number): void<sup>8+</sup> | Sets the year, month, day, hour, minute, and second for the **Calendar** object. | 104| ohos.i18n | setTimeZone(timezone: string): void<sup>8+</sup> | Sets the time zone for the **Calendar** object. | 105| ohos.i18n | getTimeZone(): string<sup>8+</sup> | Obtains the time zone for the **Calendar** object. | 106| ohos.i18n | getFirstDayOfWeek(): number<sup>8+</sup> | Obtains the first day of a week for the **Calendar** object. | 107| ohos.i18n | setFirstDayOfWeek(value: number): void<sup>8+</sup> | Sets the first day of a week for the **Calendar** object. | 108| ohos.i18n | getMinimalDaysInFirstWeek(): number<sup>8+</sup> | Obtains the minimum count of days in the first week of a year. | 109| ohos.i18n | setMinimalDaysInFirstWeek(value: number): void<sup>8+</sup> | Sets the minimum count of days in the first week of a year. | 110| ohos.i18n | getDisplayName(locale: string): string<sup>8+</sup> | Obtains the localized display of the **Calendar** object. | 111| ohos.i18n | isWeekend(date?: Date): boolean<sup>8+</sup> | Checks whether a given date is a weekend. | 112 113 114### How to Develop 115 1161. Instantiate a **Calendar** object. 117 118 Call the **getCalendar** method to obtain the time zone object of a specific locale and type (**i18n** is the name of the imported module). **type** indicates the valid calendar type, for example, **buddhist**, **chinese**, **coptic**, **ethiopic**, **hebrew**, **gregory**, **indian**, **islamic_civil**, **islamic_tbla**, **islamic_umalqura**, **japanese**, and **persian**. If **type** is left unspecified, the default calendar type of the locale is used. 119 120 121 ```js 122 var calendar = i18n.getCalendar("zh-CN", "gregory"); 123 ``` 124 1252. Set the time for the **Calendar** object. 126 127 Call the **setTime** method to set the time of the **Calendar** object. This method receives two types of parameters. One is a **Date** object, and the other is a value indicating the number of milliseconds elapsed since January 1, 1970, 00:00:00 GMT. 128 129 ```js 130 var date1 = new Date(); 131 calendar.setTime(date1); 132 var date2 = 1000; 133 calendar.setTime(date2); 134 ``` 135 1363. Set the year, month, day, hour, minute, and second for the **Calendar** object. 137 138 Call the **set** method to set the year, month, day, hour, minute, and second for the **Calendar** object. 139 140 ```js 141 calendar.set(2021, 12, 21, 6, 0, 0) 142 ``` 143 1444. Set and obtain the time zone for the **Calendar** object. 145 146 Call the **setTimeZone** and **getTimeZone** methods to set and obtain the time zone for the **Calendar** object. The **setTimeZone** method requires an input string to indicate the time zone to be set. 147 148 149 ```js 150 calendar.setTimeZone("Asia/Shanghai"); 151 var timezone = calendar.getTimeZone(); 152 ``` 153 1545. Set and obtain the first day of a week for the **Calendar** object. 155 156 Call the **setFirstDayOfWeek** and **getFirstDayOfWeek** methods to set and obtain the first day of a week for the **Calendar** object. **setFirstDayOfWeek** must be set to a value indicating the first day of a week. The value **1** indicates Sunday, and the value **7** indicates Saturday. 157 158 159 ```js 160 calendar.setFirstDayOfWeek(1); 161 var firstDayOfWeek = calendar.getFirstDayOfWeek(); 162 ``` 163 1646. Set and obtain the minimum count of days in the first week for the **Calendar** object. 165 166 Call the **setMinimalDaysInFirstWeek** and **getMinimalDaysInFirstWeek** methods to set and obtain the minimum count of days in the first week for the **Calendar** object. 167 168 ```js 169 calendar.setMinimalDaysInFirstWeek(3); 170 var minimalDaysInFirstWeek = calendar.getMinimalDaysInFirstWeek(); 171 ``` 172 1737. Obtain the localized display of the **Calendar** object. 174 175 Call the **getDisplayName** method to obtain the localized display of the **Calendar** object. 176 177 178 ```js 179 var localizedName = calendar.getDisplayName("zh-CN"); 180 ``` 181 1828. Check whether a date is a weekend. 183 184 Call the **isWeekend** method to determine whether the input date is a weekend. 185 186 187 ```js 188 var date = new Date(); 189 var weekend = calendar.isWeekend(date); 190 ``` 191 192 193## Formatting a Phone Number 194 195[PhoneNumberFormat](../reference/apis/js-apis-i18n.md#phonenumberformat8) APIs are used to format phone numbers in different countries and check whether the phone number formats are correct. 196 197 198### Available APIs 199 200| Module | API | Description | 201| -------- | -------- | -------- | 202| ohos.i18n | constructor(country: string, options?: PhoneNumberFormatOptions)<sup>8+</sup> | Instantiates a **PhoneNumberFormat** object. | 203| ohos.i18n | isValidNumber(number: string): boolean<sup>8+</sup> | Checks whether the value of **number** is a phone number in the correct format. | 204| ohos.i18n | format(number: string): string<sup>8+</sup> | Formats the value of **number** based on the specified country and style. | 205 206 207### How to Develop 208 2091. Instantiate a **PhoneNumberFormat** object. 210 211 Call the **PhoneNumberFormat** constructor to instantiate a **PhoneNumberFormat** object. The country code and formatting options of the phone number need to be passed into this constructor. The formatting options are optional, including a style option. Values of this option include: **E164**, **INTERNATIONAL**, **NATIONAL**, and **RFC3966**. 212 213 214 ```js 215 var phoneNumberFormat = new i18n.PhoneNumberFormat("CN", {type: "E164"}); 216 ``` 217 2182. Check whether the phone number format is correct. 219 220 Call the **isValidNumber** method to check whether the format of the input phone number is correct. 221 222 ```js 223 var validNumber = phoneNumberFormat.isValidNumber("15812341234"); 224 ``` 225 2263. Format a phone number. 227 228 Call the **format** method of **PhoneNumberFormat** to format the input phone number. 229 230 ```js 231 var formattedNumber = phoneNumberFormat.format("15812341234"); 232 ``` 233 234 235## Measurement Conversion 236 237The **unitConvert** API is provided to help you implement measurement conversion. 238 239 240### Available APIs 241 242| Module | API | Description | 243| -------- | -------- | -------- | 244| ohos.i18n | unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale: string, style?: string): string<sup>8+</sup> | Converts one measurement unit (**fromUnit**) into another (**toUnit**) and formats the unit based on the specified locale and style. | 245 246 247### How to Develop 248 249Call the [unitConvert](../reference/apis/js-apis-i18n.md#unitconvert8) method to convert a measurement unit and format the display result. 250 251 252 ```js 253 var fromUnit = {unit: "cup", measureSystem: "US"}; 254 var toUnit = {unit: "liter", measureSystem: "SI"}; 255 var number = 1000; 256 var locale = "en-US"; 257 var style = "long"; 258 i18n.Util.unitConvert(fromUtil, toUtil, number, locale, style); 259 ``` 260 261 262## Alphabet Index 263 264[IndexUtil](../reference/apis/js-apis-i18n.md#indexutil8) APIs are used to obtain the alphabet indexes of different locales and calculate the index to which a string belongs. 265 266 267### Available APIs 268 269| Module | API | Description | 270| -------- | -------- | -------- | 271| ohos.i18n | getInstance(locale?: string): IndexUtil<sup>8+</sup> | Instantiates an **IndexUtil** object. | 272| ohos.i18n | getIndexList(): Array<string><sup>8+</sup> | Obtains the index list of the current locale. | 273| ohos.i18n | addLocale(locale: string): void<sup>8+</sup> | Adds the index of a new locale to the index list. | 274| ohos.i18n | getIndex(text: string): string<sup>8+</sup> | Obtains the index of **text**. | 275 276 277### How to Develop 278 2791. Instantiate an **IndexUtil** object. 280 281 Call the **getInstance** method to instantiate an **IndexUtil** object for a specific locale. When the **locale** parameter is empty, instantiate an **IndexUtil** object of the default locale. 282 283 284 ```js 285 var indexUtil = i18n.getInstance("zh-CN"); 286 ``` 287 2882. Obtain the index list. 289 290 Call the **getIndexList** method to obtain the alphabet index list of the current locale. 291 292 ```js 293 var indexList = indexUtil.getIndexList(); 294 ``` 295 2963. Add an index. 297 298 Call the **addLocale** method to add the alphabet index of a new locale to the current index list. 299 300 ```js 301 indexUtil.addLocale("ar") 302 ``` 303 3044. Obtain the index of a string. 305 306 Call the **getIndex** method to obtain the alphabet index of a string. 307 308 ```js 309 var text = "access index"; 310 indexUtil.getIndex(text); 311 ``` 312 313 314## Obtaining Line Breaks of Text 315 316When a text is displayed in more than one line, [BreakIterator8](../reference/apis/js-apis-i18n.md#breakiterator8) APIs are used to obtain the line break positions of the text. 317 318 319### Available APIs 320 321| Module | API | Description | 322| -------- | -------- | -------- | 323| ohos.i18n | getLineInstance(locale: string): BreakIterator<sup>8+</sup> | Instantiates a **BreakIterator** object. | 324| ohos.i18n | setLineBreakText(text: string): void<sup>8+</sup> | Sets the text to be processed. | 325| ohos.i18n | getLineBreakText(): string<sup>8+</sup> | Obtains the text to be processed. | 326| ohos.i18n | current(): number<sup>8+</sup> | Obtains the current position of a **BreakIterator** object in the text being processed. | 327| ohos.i18n | first(): number<sup>8+</sup> | Sets a **BreakIterator** object to the first breakable point. | 328| ohos.i18n | last(): number<sup>8+</sup> | Sets a **BreakIterator** object to the last breakable point. | 329| ohos.i18n | next(index?: number): number<sup>8+</sup> | Moves a **BreakIterator** object to the break point according to **index**. | 330| ohos.i18n | previous(): number<sup>8+</sup> | Moves a **BreakIterator** object to the previous break point. | 331| ohos.i18n | following(offset: number): number<sup>8+</sup> | Moves a **BreakIterator** object to the break point following the position specified by **offset**. | 332| ohos.i18n | isBoundary(offset: number): boolean<sup>8+</sup> | Determines whether a position is a break point. | 333 334 335### How to Develop 336 3371. Instantiate a **BreakIterator** object. 338 339 Call the **getLineInstance** method to instantiate a **BreakIterator** object. 340 341 342 ```js 343 var locale = "en-US" 344 var breakIterator = i18n.getLineInstance(locale); 345 ``` 346 3472. Set and access the text that requires line breaking. 348 349 Call the **setLineBreakText** and **getLineBreakText** methods to set and access the text that requires line breaking. 350 351 352 ```js 353 var text = "Apple is my favorite fruit"; 354 breakIterator.setLineBreakText(text); 355 var breakText = breakIterator.getLineBreakText(); 356 ``` 357 3583. Obtain the current position of the **BreakIterator** object. 359 360 Call the **current** method to obtain the current position of the **BreakIterator** object in the text being processed. 361 362 363 ```js 364 var pos = breakIterator.current(); 365 ``` 366 3674. Set the position of a **BreakIterator** object. 368 369 The following APIs are provided to adjust the **first**, **last**, **next**, **previous**, or **following** position of the **BreakIterator** object in the text to be processed. 370 371 372 ```js 373 var firstPos = breakIterator.first(); // Set a BreakIterator object to the first break point, that is, the start position of the text. 374 var lastPos = breakIterator.last(); // Set a BreakIterator object to the last break point, that is, the position after the text end. 375 // Move a BreakIterator object forward or backward by a certain number of break points. 376 // If a positive number is input, move backward. If a negative number is input, move forward. If no value is input, move one position backward. 377 // When the object is moved out of the text length range, -1 is returned. 378 var nextPos = breakIterator.next(-2); 379 var previousPos = breakIterator.previous(); // Move a BreakIterator object to the previous break point. When the text length is out of the range, -1 is returned. 380 // Move a BreakIterator object to the break point following the position specified by offset. If the object is moved out of the text length range, -1 is returned. 381 var followingPos = breakIterator.following(10); 382 ``` 383 3845. Determine whether a position is a break point. 385 386 Call the **isBoundary** method to determine whether a position is a break point. If yes, **true** is returned and the **BreakIterator** object is moved to this position. If no, **false** is returned and the **BreakIterator** object is moved to a break point after this position. 387 388 389 ```js 390 var isboundary = breakIterator.isBoundary(5); 391 ``` 392