Internationalization Development (I18N)

This 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 APIs defined in ECMA 402. It works with the I18N module to provide a complete suite of I18N capabilities.

Obtaining System Language and Region Information

You can use APIs provided in the following table to obtain the system language and region information.

Available APIs

How to Develop

1. Obtain the system language.

   Call the getSystemLanguage method to obtain the system language (i18n is the name of the imported module).

   var language = i18n.getSystemLanguage();
   

2. Obtain the system region.

   Call the getSystemRegion method to obtain the system region.

   var region = i18n.getSystemRegion();
   

3. Obtain the system locale.

   Call the getSystemLocale method to obtain the system locale.

   var locale = i18n.getSystemLocale();
   

4. Check whether the locale's language is RTL.

   Call the isRTL method to check whether the locale's language is RTL.

   var rtl = i18n.isRTL("zh-CN");
   

5. Check whether the system uses a 24-hour clock.

   Call the is24HourClock method to check whether the system uses a 24-hour clock.

   var hourClock = i18n.is24HourClock();
   

6. Obtain the localized display of a language.

   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.

   var language = "en";
   var locale = "zh-CN";
   var sentenceCase = false;
   var localizedLanguage = i18n.getDisplayLanguage(language, locale, sentenceCase);
   

7. Obtain the localized display of a country.

   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.

   var country = "US";
   var locale = "zh-CN";
   var sentenceCase = false;
   var localizedCountry = i18n.getDisplayCountry(country, locale, sentenceCase);
   

Obtaining Calendar Information

Calendar 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.

Available APIs

How to Develop

1. Instantiate a Calendar object.

   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.

   var calendar = i18n.getCalendar("zh-CN", "gregory");
   

2. Set the time for the Calendar object.

   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.

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

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

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

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

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

   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.

   calendar.setTimeZone("Asia/Shanghai");
   var timezone = calendar.getTimeZone();
   

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

   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.

   calendar.setFirstDayOfWeek(1);
   var firstDayOfWeek = calendar.getFirstDayOfWeek();
   

6. Set and obtain the minimum count of days in the first week for the Calendar object.

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

   calendar.setMinimalDaysInFirstWeek(3);
   var minimalDaysInFirstWeek = calendar.getMinimalDaysInFirstWeek();
   

7. Obtain the localized display of the Calendar object.

   Call the getDisplayName method to obtain the localized display of the Calendar object.

   var localizedName = calendar.getDisplayName("zh-CN");
   

8. Check whether a date is a weekend.

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

   var date = new Date();
   var weekend = calendar.isWeekend(date);
   

Formatting a Phone Number

PhoneNumberFormat APIs are used to format phone numbers in different countries and check whether the phone number formats are correct.

Available APIs

How to Develop

1. 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.

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

2. Check whether the phone number format is correct.

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

   var validNumber = phoneNumberFormat.isValidNumber("15812341234");
   

3. Format a phone number.

   Call the format method of PhoneNumberFormat to format the input phone number.

   var formattedNumber = phoneNumberFormat.format("15812341234");
   

Measurement Conversion

The unitConvert API is provided to help you implement measurement conversion.

Available APIs

How to Develop

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

var fromUnit = {unit: "cup", measureSystem: "US"};
var toUnit = {unit: "liter", measureSystem: "SI"};
var number = 1000;
var locale = "en-US";
var style = "long";
i18n.Util.unitConvert(fromUtil, toUtil, number, locale, style);

Alphabet Index

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

Available APIs

How to Develop

1. Instantiate an IndexUtil object.

   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.

   var indexUtil = i18n.getInstance("zh-CN");
   

2. Obtain the index list.

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

   var indexList = indexUtil.getIndexList();
   

3. Add an index.

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

   indexUtil.addLocale("ar")
   

4. Obtain the index of a string.

   Call the getIndex method to obtain the alphabet index of a string.

   var text = "access index";
   indexUtil.getIndex(text);
   

Obtaining Line Breaks of Text

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

Available APIs

How to Develop

1. Instantiate a BreakIterator object.

   Call the getLineInstance method to instantiate a BreakIterator object.

   var locale = "en-US"
   var breakIterator = i18n.getLineInstance(locale);
   

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

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

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

3. Obtain the current position of the BreakIterator object.

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

   var pos = breakIterator.current();
   

4. 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.

   var firstPos = breakIterator.first(); // Set a BreakIterator object to the first break point, that is, the start position of the text.
   var lastPos = breakIterator.last(); // Set a BreakIterator object to the last break point, that is, the position after the text end.
   // 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.
   // When the object is moved out of the text length range, -1 is returned.
   var nextPos = breakIterator.next(-2);
   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.
   // 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.
   var followingPos = breakIterator.following(10); 
   

5. Determine whether a position is a break point.

   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.

   var isboundary = breakIterator.isBoundary(5);