i18n Development

The i18n 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.

The intl module provides basic i18n capabilities through the standard i18n interfaces defined in ECMA 402. It works with the i18n module to provide a complete suite of i18n capabilities.

Obtaining and Setting i18n Information

The following table lists the APIs used to configure information such as the system language, preferred language, country or region, 24-hour clock, and use of local digits.

Available APIs

How to Develop

1. Import the i18n module.

   import I18n from '@ohos.i18n';
   

2. Obtain and set the system language.

   Call setSystemLanguage to set the system language. (This is a system API and can be called only by system applications with the UPDATE_CONFIGURATION permission.) Call the getSystemLanguage API to obtain the system language.

   try {
      I18n.System.setSystemLanguage("en"); // Set the system language to en.
      let language = I18n.System.getSystemLanguage(); // language = "en"
   } catch(error) {
      console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`);
   }
   

3. Obtain and set the system locale.

   Call setSystemRegion to set the system country or region. (This is a system API and can be called only by system applications with the UPDATE_CONFIGURATION permission.) Call getSystemRegion to obtain the system country or region.

   try {
      I18n.System.setSystemRegion("CN"); // Set the system country to CN.
      let region = I18n.System.getSystemRegion(); // region = "CN"
   } catch(error) {
      console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`);
   }
   

4. Obtain and set the system locale.

   Call setSystemLocale to set the system locale. (This is a system API and can be called only by system applications with the UPDATE_CONFIGURATION permission.) For details about how to set a locale, see Setting Locale Information. Call getSystemLocale to obtain the system locale.

   try {
      I18n.System.setSystemLocale("zh-Hans-CN"); // Set the system locale to zh-Hans-CN.
      let locale = I18n.System.getSystemLocale(); // locale = "zh-Hans-CN"
   } catch(error) {
      console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`);
   }
   

5. Check whether the locale uses a right-to-left (RTL) language.

   Call isRTL to check whether the locale uses an RTL language.

   try {
      let rtl = I18n.isRTL("zh-CN"); // rtl = false
      rtl = I18n.isRTL("ar"); // rtl = true
   } catch(error) {
      console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`);
   }
   

6. Obtain and set the 24-hour clock.

   Call set24HourClock to enable the 24-hour clock. Call is24HourClock to check whether the 24-hour clock is enabled.

   try {
      I18n.System.set24HourClock(true);
      let hourClock = I18n.System.is24HourClock(); // hourClock = true
   } catch(error) {
      console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`);
   }
   

7. Obtain the localized representation of a language.

   Call getDisplayLanguage to obtain the localized representation 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.

   try {
      let language = "en";
      let locale = "zh-CN";
      let sentenceCase = false;
      let localizedLanguage = I18n.System.getDisplayLanguage(language, locale, sentenceCase); // localizedLanguage = "English"
   } catch(error) {
      console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`);
   }
   

8. Obtain the localized representation of a country.

   Call getDisplayCountry to obtain the localized representation of a country. country indicates the country to be localized, locale indicates the locale, and sentenceCase indicates whether the first letter of the result must be capitalized.

   try {
      let country = "US";
      let locale = "zh-CN";
      let sentenceCase = false;
      let localizedCountry = I18n.System.getDisplayCountry(country, locale, sentenceCase); // localizedCountry = "U.S."
   } catch(error) {
      console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`);
   }
   

9. Obtain the list of system languages and the list of countries supported by a system language.

   Call getSystemLanguages to obtain the list of system languages. Call getSystemCountries to obtain the list of countries and regions supported by a system language.

   
   try {
      let languageList = I18n.System.getSystemLanguages();  // languageList = ["en-Latn-US", "zh-Hans"]
      let countryList = I18n.System.getSystemCountries("zh"); // countryList = ["ZW", "YT", ..., "CN", "DE"], 240 countries and regions in total
   } catch(error) {
      console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`);
   }
   

10. Check whether the language matches a country or region.

Call isSuggested to check whether the language matches a country or region.

try {
   let isSuggest = I18n.System.isSuggested("zh", "CN"); // isSuggest = true
} catch(error) {
   console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`);
}

11. Obtain and set the preferred language.

Call addPreferredLanguage to add a preferred language to the preferred language list. Call removePreferredLanguage to remove a preferred language from the preferred language list. (addPreferredLanguage and removePreferredLanguage are system APIs and can be called only by system applications with the UPDATE_CONFIGURATION permission.) Call getPreferredLanguageList to obtain the preferred language list. Call getFirstPreferredLanguage to obtain the first preferred language in the preferred language list. Call getAppPreferredLanguageList to obtain the preferred language of the application. It is the first language that matches the application resource in the preferred language list.

try {
   I18n.System.addPreferredLanguage("en-GB", 0); // Set the first language in the preferred language list to en-GB.
   let list = I18n.System.getPreferredLanguageList(); // Obtain the preferred language list. Example: list = ["en-GB", ...]
   I18n.System.removePreferredLanguage(list.length - 1); // Remove the last preferred language from the preferred language list.
   let firstPreferredLanguage = I18n.System.getFirstPreferredLanguage(); // firstPreferredLanguage = "en-GB"
   let appPreferredLanguage = I18n.System.getAppPreferredLanguage(); // Set the preferred language of the application to en-GB if the application contains en-GB resources.
} catch(error) {
   console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`);
}

12. Obtain and set the local digit switch.

Call setUsingLocalDigit to enable the local digit switch. (This is a system API and can be called only by system applications with the UPDATE_CONFIGURATION permission.) Call getUsingLocalDigit to check whether the local digit switch is enabled. Currently, use of local digits is supported only for the following languages: ar, as, bn, fa, mr, my, ne, ur.

try {
   I18n.System.setUsingLocalDigit(true); // Enable the local digit switch.
   let status = I18n.System.getUsingLocalDigit(); // status = true
} catch(error) {
   console.error(`call i18n.System interface failed, error code: ${error.code}, message: ${error.message}`);
}

Obtain the calendar information.

Calendar provides APIs to obtain calendar information, for example, localized representation of the calendar, the start day of a week, and the minimum number of days in the first week of a year.

Available APIs

How to Develop

1. Import the i18n module.

   import I18n from '@ohos.i18n';
   

2. Instantiate a Calendar object.

   Call getCalendar 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.

   let calendar = I18n.getCalendar("zh-CN", "chinese"); // Create the Calendar object for the Chinese lunar calendar.
   

3. Set the time for the Calendar object.

   Call setTime to set the time of the Calendar object. Two types of parameters are supported. 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.

   let date1 = new Date();
   calendar.setTime(date1);
   let date2 = 1000;
   calendar.setTime(date2);
   

4. Set the year, month, day, hour, minute, and second for this Calendar object.

   Call set to set the year, month, day, hour, minute, and second for the Calendar object.

   calendar.set(2021, 12, 21, 6, 0, 0);
   

5. Set and obtain the time zone for the Calendar object.

   Call setTimeZone and getTimeZone to set and obtain the time zone of the Calendar object. Note that setTimeZone requires an input string to indicate the time zone to be set.

   calendar.setTimeZone("Asia/Shanghai");
   let timezone = calendar.getTimeZone();  // timezone = "China Standard Time"
   

6. Set and obtain the first day of a week for the Calendar object.

   Call setFirstDayOfWeek and getFirstDayOfWeek to set and obtain the start 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.

   calendar.setFirstDayOfWeek(1);
   let firstDayOfWeek = calendar.getFirstDayOfWeek(); // firstDayOfWeek = 1
   

7. Set and obtain the minimum count of days in the first week for the Calendar object. Call setMinimalDaysInFirstWeek and getMinimalDaysInFirstWeek to set and obtain the minimum number of days in the first week for the Calendar object.

   calendar.setMinimalDaysInFirstWeek(3);
   let minimalDaysInFirstWeek = calendar.getMinimalDaysInFirstWeek(); // minimalDaysInFirstWeek = 3
   

8. Obtain the localized representation of the Calendar object. Call getDisplayName to obtain the localized representation of the Calendar object.

   let localizedName = calendar.getDisplayName("zh-CN"); // localizedName = " Lunar Calendar"
   

9. Check whether a date is a weekend.

   Call isWeekend to determine whether the input date is a weekend.

   let date = new Date(2022, 12, 12, 12, 12, 12);
   let weekend = calendar.isWeekend(date); // weekend = false
   

Formatting a Phone Number

PhoneNumberFormat provides APIs to format phone numbers of different countries or regions and check whether the phone number format is correct.

Available APIs

How to Develop

1. Import the i18n module.

   import I18n from '@ohos.i18n';
   

2. Instantiate a PhoneNumberFormat object.

   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.

   let phoneNumberFormat = new I18n.PhoneNumberFormat("CN", {type: "E164"});
   

3. Check whether the phone number format is correct.

   Call isValidNumber to check whether the format of the input phone number is correct.

   let validNumber = phoneNumberFormat.isValidNumber("15812341234"); // validNumber = true
   

4. Format a phone number.

   Call format to format the input phone number.

   let formattedNumber = phoneNumberFormat.format("15812341234"); // formattedNumber = "+8615812341234"
   

Measurement Conversion

The I18NUtil class provides an API to implement measurement conversion.

Available APIs

How to Develop

1. Import the i18n module.

   import I18n from '@ohos.i18n';
   

2. Convert a measurement unit.

   Call unitConvert to convert a measurement unit and format the display result.

   let fromUnit = {unit: "cup", measureSystem: "US"};
   let toUnit = {unit: "liter", measureSystem: "SI"};
   let number = 1000;
   let locale = "en-US";
   let style = "long";
   let converttedUnit = I18n.I18NUtil.unitConvert(fromUnit, toUnit, number, locale, style); // converttedUnit = "236.588 liters"
   

Alphabet Indexing

IndexUtil provides APIs to obtain the alphabet indexes of different locales and calculate the index to which a string belongs.

Available APIs

How to Develop

1. Import the i18n module.

   import I18n from '@ohos.i18n';
   

2. Instantiates an IndexUtil object.

   Call getInstance to instantiate an IndexUtil object for a specific locale. When the locale parameter is empty, instantiate an IndexUtil object of the default locale.

   let indexUtil = I18n.getInstance("zh-CN");
   

3. Obtain the index list.

   Call getIndexList to obtain the alphabet index list of the current locale.

   let indexList = indexUtil.getIndexList(); // indexList = ["...", "A", "B", "C", ..., "X", "Y", "Z", "..."]
   

4. Add an index.

   Call addLocale to add the alphabet index of a new locale to the current index list.

   indexUtil.addLocale("ar");
   

5. Obtain the index of a string.

   Call getIndex to obtain the alphabet index of a string.

   let text = "access index";
   let index = indexUtil.getIndex(text); // index = "A"
   

Obtaining Line Breaks of Text

When a text is displayed in more than one line, use BreakIterator8 APIs to obtain the line break positions of the text.

Available APIs

How to Develop

1. Import the i18n module.

   import I18n from '@ohos.i18n';
   

2. Instantiate a BreakIterator object.

   Call getLineInstance to instantiate a BreakIterator object.

   let locale = "en-US";
   let breakIterator = I18n.getLineInstance(locale);
   

3. Set and access the text that requires line breaking.

   Call setLineBreakText and getLineBreakText to set and access the text that requires line breaking.

   let text = "Apple is my favorite fruit";
   breakIterator.setLineBreakText(text);
   let breakText = breakIterator.getLineBreakText();  // breakText = "Apple is my favorite fruit"
   

4. Obtain the current position of the BreakIterator object.

   Call current to obtain the current position of the BreakIterator object in the text being processed.

   let pos = breakIterator.current(); // pos = 0
   

5. Set the position of a BreakIterator object.

   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.

   let firstPos = breakIterator.first(); // Set a BreakIterator object to the first break point, that is, the start position of the text (firstPos = 0).
   let lastPos = breakIterator.last(); // Sets a BreakIterator object to the last break point, that is, the position after the text end (lastPos = 26).
   // Move a BreakIterator object forward or backward by a certain number of break points.
   // 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.
   // If the object is moved out of the text length range, **-1** is returned.
   let nextPos = breakIterator.next(-2); // nextPos = 12
   let previousPos = breakIterator.previous(); // Move a BreakIterator object to the previous break point. When the text length is out of the range, **-1** is returned. Example: previousPos = 9
   // 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.
   let followingPos = breakIterator.following(10); // Example: followingPos = 12
   

6. Determine whether a position is a break point.

   Call isBoundary 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.

   let isboundary = breakIterator.isBoundary(5); // isboundary = false
   

Obtaining the Time Zone

TimeZone provides APIs to obtain time zone information, such as the time zone ID, localized representation, and time zone offset.

Available APIs

How to Develop

1. Import the i18n module.

   import I18n from '@ohos.i18n';
   

2. Instantiate the TimeZone object, and obtain the time zone information.

   Call getTimeZone to obtain the TimeZone object.

   let timezone = I18n.getTimeZone(); // If you use the default settings, you'll obtain the TimeZone object corresponding to the system time zone.
   

   Obtain the time zone ID, localized representation, time zone offset, and time zone offset at a certain time point.

   let timezoneID = timezone.getID(); // timezoneID = "Asia/Shanghai"
   let timezoneDisplayName = timezone.getDisplayName(); // timezoneDisplayName = "China Standard Time"
   let rawOffset = timezone.getRawOffset(); // rawOffset = 28800000
   let offset = timezone.getOffset(new Date().getTime()); // offset = 28800000
   

3. Obtain the list of time zone IDs supported by the system.

   Call getAvailableIDs to obtain the list of time zone IDs supported by the system. You can use the time zone ID in the time zone ID list as an input parameter of the getTimeZone API to create a TimeZone object.

   let timezoneIDs = I18n.TimeZone.getAvailableIDs(); // timezoneIDs = ["America/Adak", ...], which contains 24 time zone IDs in total
   let timezone = I18n.getTimeZone(timezoneIDs[0]);
   let timezoneDisplayName = timezone.getDisplayName(); // timezoneDisplayName = "Hawaii-Aleutian Standard Time"
   

4. Obtain the list of time zone city IDs supported by the system.

   Call getAvailableZoneCityIDs to obtain the list of time zone city IDs supported by the system. Call getCityDisplayName to obtain the localized representation of the time zone city ID. Call getTimezoneFromCity to create a TimeZone object based on the time zone city ID.

   let zoneCityIDs = I18n.TimeZone.getAvailableZoneCityIDs(); // ["Auckland", "Magadan", ...]
   let cityDisplayName = I18n.TimeZone.getCityDisplayName(zoneCityIDs[0], "zh-Hans"); // cityDisplayName = "Auckland (New Zealand)"
   let timezone = I18n.TimeZone.getTimezoneFromCity(zoneCityIDs[0]);
   let timezoneDisplayName = timezone.getDisplayName(); // timezoneDisplayName = "New Zealand Standard Time"
   

Obtain the Transliterator object.

Call Transliterator APIs to create a Transliterator object and obtain the transliterated string.

Available APIs

How to Develop

1. Import the i18n module.

   import I18n from '@ohos.i18n';
   

2. Obtains the transliterator ID list.

   Call getAvailableIDs to obtain the transliterator ID list. An ID is in the source-destination format. For example, ASCII-Latin means to convert the transliterator ID from ASCII to Latin.

   let ids = I18n.Transliterator.getAvailableIDs(); // ids = ["ASCII-Latin", "Accents-Any", ... ], 671 languages in total
   

3. Create a Transliterator object, and obtain the transliterated string.

   You can use the ID in the transliterator ID list as an input parameter of the getInstance API to create a Transliterator object. Call transform to obtain the transliterated string.

   let transliterator = I18n.Transliterator.getInstance("Any-Latn"); // Any-Latn means to convert any text to Latn text.
   let transformText = transliterator.transform ("Hello"); // transformText = "nǐ hǎo"
   

Obtaining the Character Type

Unicode provides APIs to obtain character information, for example, whether a character is a digit or a space.

Available APIs

How to Develop

1. Import the i18n module.

   import I18n from '@ohos.i18n';
   

2. Check the input character has a certain attribute.

   Check whether the input character is a digit.

   let isDigit = I18n.Unicode.isDigit("1"); // isDigit = true
   isDigit = I18n.Unicode.isDigit("a"); // isDigit = false
   

   Check whether the input character is a space.

   let isSpaceChar = I18n.Unicode.isSpaceChar(" "); // isSpaceChar = true
   isSpaceChar = I18n.Unicode.isSpaceChar("\n"); // isSpaceChar = false
   

   Check whether the input character is a white space.

   let isWhitespace = I18n.Unicode.isWhitespace(" "); // isWhitespace = true
   isWhitespace = I18n.Unicode.isWhitespace("\n"); // isWhitespace = true
   

   Check whether the input character is of the RTL language.

   let isRTL = I18n.Unicode.isRTL(""); // isRTL = true (Arabic characters are written from left to right.)
   isRTL = I18n.Unicode.isRTL("a"); // isRTL = false
   

   Check whether the input character is an ideographic character.

   let isIdeograph = I18n.Unicode.isIdeograph("Hello"); // isIdeograph = true
   isIdeograph = I18n.Unicode.isIdeograph("a"); // isIdeograph = false
   

   Check whether the input character is a letter.

   let isLetter = I18n.Unicode.isLetter("a"); // isLetter = true
   isLetter = I18n.Unicode.isLetter("."); // isLetter = false
   

   Check whether the input character is a lowercase letter.

   let isLowerCase = I18n.Unicode.isLowerCase("a"); // isLetter = true
   isLowerCase = I18n.Unicode.isLowerCase("A"); // isLetter = false
   

   Check whether the input character is an uppercase letter.

   let isUpperCase = I18n.Unicode.isUpperCase("a"); // isUpperCase = false
   isUpperCase = I18n.Unicode.isUpperCase("A"); // isUpperCase = true
   

3. Obtain the character type.

   Call getType to obtain the character type.

   let type = I18n.Unicode.getType("a"); // type = U_LOWER_CASE_LETTER
   

Obtaining the Sequence of Year, Month, and Day in a Date

Available APIs

How to Develop

1. Import the i18n module.

   import I18n from '@ohos.i18n';
   

2. Check the sequence of year, month, and day in a date.

   Call getDateOrder to obtain the sequence of year, month, and day in the date of the specified locale. The API returns a string consisting of three parts, y, L, and d, which indicate the year, month, and day, respectively. The three parts are separated by using a hyphen (-), for example, y-L-d.

   let order = I18n.I18NUtil.getDateOrder("zh-CN"); // order = "y-L-d" indicates that the sequence of year, month, and day in Chinese is year-month-day.