@ohos.i18n (Internationalization)

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

NOTE

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

• 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 details about the basic I18N capabilities, see intl.

Modules to Import

import I18n from '@ohos.i18n';

System⁹⁺

getDisplayCountry⁹⁺

static getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): string

Obtains the localized script for the specified country.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Error codes

For details about the error codes, see I18N Error Codes.

Example

import { BusinessError } from '@ohos.base';

try {
    let displayCountry: string = I18n.System.getDisplayCountry("zh-CN", "en-GB"); // displayCountry = "China"
} catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error(`call System.getDisplayCountry failed, error code: ${err.code}, message: ${err.message}.`);
}

getDisplayLanguage⁹⁺

static getDisplayLanguage(language: string, locale: string, sentenceCase?: boolean): string

Obtains the localized script for the specified language.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Error codes

For details about the error codes, see I18N Error Codes.

Example

import { BusinessError } from '@ohos.base';

try {
  let displayLanguage: string = I18n.System.getDisplayLanguage("zh", "en-GB"); // displayLanguage = Chinese
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.getDisplayLanguage failed, error code: ${err.code}, message: ${err.message}.`);
}

getSystemLanguages⁹⁺

static getSystemLanguages(): Array<string>

Obtains the list of system languages.

System capability: SystemCapability.Global.I18n

Return value

Example

import { BusinessError } from '@ohos.base';

try {
  let systemLanguages: Array<string> = I18n.System.getSystemLanguages(); // [ "en-Latn-US", "zh-Hans" ]
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.getSystemLanguages failed, error code: ${err.code}, message: ${err.message}.`);
}

getSystemCountries⁹⁺

static getSystemCountries(language: string): Array<string>

Obtains the list of countries and regions supported for the specified language.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Error codes

For details about the error codes, see I18N Error Codes.

Example

import { BusinessError } from '@ohos.base';

try {
  let systemCountries: Array<string> = I18n.System.getSystemCountries('zh'); // systemCountries = [ "ZW", "YT", "YE", ..., "ER", "CN", "DE" ], 240 countries or regions in total
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.getSystemCountries failed, error code: ${err.code}, message: ${err.message}.`);
}

isSuggested⁹⁺

static isSuggested(language: string, region?: string): boolean

Checks whether the system language matches the specified region.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Error codes

For details about the error codes, see I18N Error Codes.

Example

import { BusinessError } from '@ohos.base';

try {
  let res: boolean = I18n.System.isSuggested('zh', 'CN');  // res = true
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.isSuggested failed, error code: ${err.code}, message: ${err.message}.`);
}

getSystemLanguage⁹⁺

static getSystemLanguage(): string

Obtains the system language.

System capability: SystemCapability.Global.I18n

Return value

Example

import { BusinessError } from '@ohos.base';

try {
  let systemLanguage: string = I18n.System.getSystemLanguage();  // systemLanguage indicates the current system language.
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.getSystemLanguage failed, error code: ${err.code}, message: ${err.message}.`);
}

setSystemLanguage⁹⁺

static setSystemLanguage(language: string): void

Sets the system language. Currently, this API does not support real-time updating of the system language.

System API: This is a system API.

Permission required: ohos.permission.UPDATE_CONFIGURATION

System capability: SystemCapability.Global.I18n

Parameters

Error codes

For details about the error codes, see I18N Error Codes.

Example

import { BusinessError } from '@ohos.base';

try {
  I18n.System.setSystemLanguage('zh'); // Set the current system language to zh.
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.setSystemLanguage failed, error code: ${err.code}, message: ${err.message}.`);
}

getSystemRegion⁹⁺

static getSystemRegion(): string

Obtains the system region.

System capability: SystemCapability.Global.I18n

Return value

Example

import { BusinessError } from '@ohos.base';

try {
  let systemRegion: string = I18n.System.getSystemRegion(); // Obtain the current system region.
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.getSystemRegion failed, error code: ${err.code}, message: ${err.message}.`);
}

setSystemRegion⁹⁺

static setSystemRegion(region: string): void

Sets the system region.

System API: This is a system API.

Permission required: ohos.permission.UPDATE_CONFIGURATION

System capability: SystemCapability.Global.I18n

Parameters

Error codes

For details about the error codes, see I18N Error Codes.

Example

import { BusinessError } from '@ohos.base';

try {
  I18n.System.setSystemRegion('CN'); // Set the current system region to CN.
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.setSystemRegion failed, error code: ${err.code}, message: ${err.message}.`);
}

getSystemLocale⁹⁺

static getSystemLocale(): string

Obtains the system locale.

System capability: SystemCapability.Global.I18n

Return value

Example

import { BusinessError } from '@ohos.base';

try {
  let systemLocale: string = I18n.System.getSystemLocale();  // Obtain the current system locale.
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.getSystemLocale failed, error code: ${err.code}, message: ${err.message}.`);
}

setSystemLocale⁹⁺

static setSystemLocale(locale: string): void

Sets the system locale.

System API: This is a system API.

Permission required: ohos.permission.UPDATE_CONFIGURATION

System capability: SystemCapability.Global.I18n

Parameters

Error codes

For details about the error codes, see I18N Error Codes.

Example

import { BusinessError } from '@ohos.base';

try {
  I18n.System.setSystemLocale('zh-CN'); // Set the current system locale to zh-CN.
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.setSystemLocale failed, error code: ${err.code}, message: ${err.message}.`);
}

is24HourClock⁹⁺

static is24HourClock(): boolean

Checks whether the 24-hour clock is used.

System capability: SystemCapability.Global.I18n

Return value

Example

import { BusinessError } from '@ohos.base';

try {
  let is24HourClock: boolean = I18n.System.is24HourClock();  // Check whether the 24-hour clock is enabled.
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.is24HourClock failed, error code: ${err.code}, message: ${err.message}.`);
}

set24HourClock⁹⁺

static set24HourClock(option: boolean): void

Sets the system time to the 24-hour clock.

System API: This is a system API.

Permission required: ohos.permission.UPDATE_CONFIGURATION

System capability: SystemCapability.Global.I18n

Parameters

Error codes

For details about the error codes, see I18N Error Codes.

Example

import { BusinessError } from '@ohos.base';

// Set the system time to the 24-hour clock.
try {
  I18n.System.set24HourClock(true);
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.set24HourClock failed, error code: ${err.code}, message: ${err.message}.`);
}

addPreferredLanguage⁹⁺

static addPreferredLanguage(language: string, index?: number): void

Adds a preferred language to the specified position on the preferred language list.

System API: This is a system API.

Permission required: ohos.permission.UPDATE_CONFIGURATION

System capability: SystemCapability.Global.I18n

Parameters

Error codes

For details about the error codes, see I18N Error Codes.

Example

import { BusinessError } from '@ohos.base';

// Add zh-CN to the preferred language list.
let language = 'zh-CN';
let index = 0;
try {
  I18n.System.addPreferredLanguage(language, index); // Add zh-CN to the first place in the preferred language list.
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.addPreferredLanguage failed, error code: ${err.code}, message: ${err.message}.`);
}

removePreferredLanguage⁹⁺

static removePreferredLanguage(index: number): void

Deletes a preferred language from the specified position on the preferred language list.

System API: This is a system API.

Permission required: ohos.permission.UPDATE_CONFIGURATION

System capability: SystemCapability.Global.I18n

Parameters

Error codes

For details about the error codes, see I18N Error Codes.

Example

import { BusinessError } from '@ohos.base';

// Delete the first preferred language from the preferred language list.
let index: number = 0;
try {
  I18n.System.removePreferredLanguage(index);
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.removePreferredLanguage failed, error code: ${err.code}, message: ${err.message}.`);
}

getPreferredLanguageList⁹⁺

static getPreferredLanguageList(): Array<string>

Obtains the list of preferred languages.

System capability: SystemCapability.Global.I18n

Return value

Example

import { BusinessError } from '@ohos.base';

try {
  let preferredLanguageList: Array<string> = I18n.System.getPreferredLanguageList(); // Obtain the current preferred language list.
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.getPreferredLanguageList failed, error code: ${err.code}, message: ${err.message}.`);
}

getFirstPreferredLanguage⁹⁺

static getFirstPreferredLanguage(): string

Obtains the first language in the preferred language list.

System capability: SystemCapability.Global.I18n

Return value

Example

import { BusinessError } from '@ohos.base';

try {
  let firstPreferredLanguage: string = I18n.System.getFirstPreferredLanguage();  // Obtain the first language in the preferred language list.
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.getFirstPreferredLanguage failed, error code: ${err.code}, message: ${err.message}.`);
}

getAppPreferredLanguage⁹⁺

static getAppPreferredLanguage(): string

Obtains the preferred language of an application.

System capability: SystemCapability.Global.I18n

Return value

Example

import { BusinessError } from '@ohos.base';

try {
  let appPreferredLanguage: string = I18n.System.getAppPreferredLanguage(); // Obtain the preferred language of an application.
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.getAppPreferredLanguage failed, error code: ${err.code}, message: ${err.message}.`);
}

setUsingLocalDigit⁹⁺

static setUsingLocalDigit(flag: boolean): void

Specifies whether to enable use of local digits.

System API: This is a system API.

Permission required: ohos.permission.UPDATE_CONFIGURATION

System capability: SystemCapability.Global.I18n

Parameters

Error codes

For details about the error codes, see I18N Error Codes.

Example

import { BusinessError } from '@ohos.base';

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

getUsingLocalDigit⁹⁺

static getUsingLocalDigit(): boolean

Checks whether use of local digits is enabled.

System capability: SystemCapability.Global.I18n

Return value

Example

import { BusinessError } from '@ohos.base';

try {
  let status: boolean = I18n.System.getUsingLocalDigit();  // Check whether the local digit switch is enabled.
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call System.getUsingLocalDigit failed, error code: ${err.code}, message: ${err.message}.`);
}

I18n.isRTL

isRTL(locale: string): boolean

Checks whether a locale uses an RTL language.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

i18n.isRTL("zh-CN");// Since Chinese is not written from right to left, false is returned.
i18n.isRTL("ar-EG");// Since Arabic is written from right to left, true is returned.

I18n.getCalendar⁸⁺

getCalendar(locale: string, type? : string): Calendar

Obtains a Calendar object.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

I18n.getCalendar("zh-Hans", "chinese"); // Obtain the Calendar object for the Chinese lunar calendar.

Calendar⁸⁺

setTime⁸⁺

setTime(date: Date): void

Sets the date for this Calendar object.

System capability: SystemCapability.Global.I18n

Parameters

Example

let calendar: I18n.Calendar = I18n.getCalendar("en-US", "gregory");
let date: Date = new Date(2021, 10, 7, 8, 0, 0, 0);
calendar.setTime(date);

setTime⁸⁺

setTime(time: number): void

Sets the date and time for this Calendar object. The value is represented by the number of milliseconds that have elapsed since the Unix epoch (00:00:00 UTC on January 1, 1970).

System capability: SystemCapability.Global.I18n

Parameters

Example

let calendar: I18n.Calendar = I18n.getCalendar("en-US", "gregory");
calendar.setTime(10540800000);

set⁸⁺

set(year: number, month: number, date:number, hour?: number, minute?: number, second?: number): void

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

System capability: SystemCapability.Global.I18n

Parameters

Example

let calendar: I18n.Calendar = I18n.getCalendar("zh-Hans");
calendar.set(2021, 10, 1, 8, 0, 0); // set time to 2021.10.1 08:00:00

setTimeZone⁸⁺

setTimeZone(timezone: string): void

Sets the time zone of this Calendar object.

System capability: SystemCapability.Global.I18n

Parameters

Example

let calendar: I18n.Calendar = I18n.getCalendar("zh-Hans");
calendar.setTimeZone("Asia/Shanghai");

getTimeZone⁸⁺

getTimeZone(): string

Obtains the time zone of this Calendar object.

System capability: SystemCapability.Global.I18n

Return value

Example

let calendar: I18n.Calendar = I18n.getCalendar("zh-Hans");
calendar.setTimeZone("Asia/Shanghai");
let timezone: string = calendar.getTimeZone(); // timezone = "Asia/Shanghai"

getFirstDayOfWeek⁸⁺

getFirstDayOfWeek(): number

Obtains the start day of a week for this Calendar object.

System capability: SystemCapability.Global.I18n

Return value

Example

let calendar: I18n.Calendar = I18n.getCalendar("en-US", "gregory");
let firstDayOfWeek: number = calendar.getFirstDayOfWeek(); // firstDayOfWeek = 1

setFirstDayOfWeek⁸⁺

setFirstDayOfWeek(value: number): void

Sets the start day of a week for this Calendar object.

System capability: SystemCapability.Global.I18n

Parameters

Example

let calendar: I18n.Calendar = I18n.getCalendar("zh-Hans");
calendar.setFirstDayOfWeek(3);
let firstDayOfWeek: number = calendar.getFirstDayOfWeek(); // firstDayOfWeek = 3

getMinimalDaysInFirstWeek⁸⁺

getMinimalDaysInFirstWeek(): number

Obtains the minimum number of days in the first week of a year.

System capability: SystemCapability.Global.I18n

Return value

Example

let calendar: I18n.Calendar = I18n.getCalendar("zh-Hans");
let minimalDaysInFirstWeek: number = calendar.getMinimalDaysInFirstWeek(); // minimalDaysInFirstWeek = 1

setMinimalDaysInFirstWeek⁸⁺

setMinimalDaysInFirstWeek(value: number): void

Sets the minimum number of days in the first week of a year.

System capability: SystemCapability.Global.I18n

Parameters

Example

let calendar: I18n.Calendar = I18n.getCalendar("zh-Hans");
calendar.setMinimalDaysInFirstWeek(3);
let minimalDaysInFirstWeek: number = calendar.getMinimalDaysInFirstWeek(); // minimalDaysInFirstWeek = 3

get⁸⁺

get(field: string): number

Obtains the value of the specified field in the Calendar object.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let calendar: I18n.Calendar = I18n.getCalendar("zh-Hans");
calendar.set(2021, 10, 1, 8, 0, 0); // set time to 2021.10.1 08:00:00
let hourOfDay: number = calendar.get("hour_of_day"); // hourOfDay = 8

getDisplayName⁸⁺

getDisplayName(locale: string): string

Obtains the displayed name of the Calendar object for the specified locale.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let calendar: I18n.Calendar = I18n.getCalendar("en-US", "buddhist");
let calendarName: string = calendar.getDisplayName("zh"); // calendarName = "Buddhist Calendar"

isWeekend⁸⁺

isWeekend(date?: Date): boolean

Checks whether a given date is a weekend in the calendar.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let calendar: I18n.Calendar = I18n.getCalendar("zh-Hans");
calendar.set(2021, 11, 11, 8, 0, 0); // set time to 2021.11.11 08:00:00
calendar.isWeekend(); // false
let date: Date = new Date(2011, 11, 6, 9, 0, 0);
calendar.isWeekend(date); // true

PhoneNumberFormat⁸⁺

constructor⁸⁺

constructor(country: string, options?: PhoneNumberFormatOptions)

Creates a PhoneNumberFormat object.

System capability: SystemCapability.Global.I18n

Parameters

Example

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

isValidNumber⁸⁺

isValidNumber(number: string): boolean

Checks whether the format of the specified phone number is valid.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let phonenumberfmt: I18n.PhoneNumberFormat = new I18n.PhoneNumberFormat("CN");
let isValidNumber: boolean = phonenumberfmt.isValidNumber("158****2312"); // isValidNumber = true

format⁸⁺

format(number: string): string

Formats a phone number.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let phonenumberfmt: I18n.PhoneNumberFormat = new I18n.PhoneNumberFormat("CN");
let formattedPhoneNumber: string = phonenumberfmt.format("158****2312"); // formattedPhoneNumber = "158 **** 2312"

getLocationName⁹⁺

getLocationName(number: string, locale: string): string

Obtains the home location of a phone number.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let phonenumberfmt: I18n.PhoneNumberFormat = new I18n.PhoneNumberFormat("CN");
let locationName: string = phonenumberfmt.getLocationName("158****2345", "zh-CN"); // locationName = "Zhanjiang, Guangdong Province"

PhoneNumberFormatOptions⁸⁺

Defines the options for this PhoneNumberFormat object.

System capability: SystemCapability.Global.I18n

UnitInfo⁸⁺

Defines the measurement unit information.

System capability: SystemCapability.Global.I18n

getInstance⁸⁺

getInstance(locale?:string): IndexUtil

Creates an IndexUtil object.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

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

IndexUtil⁸⁺

getIndexList⁸⁺

getIndexList(): Array<string>

Obtains the index list for this locale object.

System capability: SystemCapability.Global.I18n

Return value

Example

let indexUtil: I18n.IndexUtil = I18n.getInstance("zh-CN");
// indexList = [ "...", "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N",
//              "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z", "..." ]
let indexList: Array<string> = indexUtil.getIndexList();

addLocale⁸⁺

addLocale(locale: string): void

Adds a locale object to the current index list.

System capability: SystemCapability.Global.I18n

Parameters

Example

let indexUtil: I18n.IndexUtil = I18n.getInstance("zh-CN");
indexUtil.addLocale("en-US");

getIndex⁸⁺

getIndex(text: string): string

Obtains the index of a text object.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let indexUtil: I18n.IndexUtil = I18n.getInstance("zh-CN");
let index: string = indexUtil.getIndex("hi");  // index = "H"

I18n.getLineInstance⁸⁺

getLineInstance(locale: string): BreakIterator

Obtains a BreakIterator object for text segmentation.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let iterator: I18n.BreakIterator = I18n.getLineInstance("en");

BreakIterator⁸⁺

setLineBreakText⁸⁺

setLineBreakText(text: string): void

Sets the text to be processed by the BreakIterator object.

System capability: SystemCapability.Global.I18n

Parameters

Example

let iterator: I18n.BreakIterator = I18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit ."); // Set a short sentence as the text to be processed by the BreakIterator object.

getLineBreakText⁸⁺

getLineBreakText(): string

Obtains the text being processed by the BreakIterator object.

System capability: SystemCapability.Global.I18n

Return value

Example

let iterator: I18n.BreakIterator = I18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
let breakText: string = iterator.getLineBreakText(); // breakText = "Apple is my favorite fruit."

current⁸⁺

current(): number

Obtains the position of the BreakIterator object in the text being processed.

System capability: SystemCapability.Global.I18n

Return value

Example

let iterator: I18n.BreakIterator = I18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
let currentPos: number = iterator.current(); // currentPos = 0

first⁸⁺

first(): number

Puts the BreakIterator object to the first break point, which is always at the beginning of the processed text.

System capability: SystemCapability.Global.I18n

Return value

Example

let iterator: I18n.BreakIterator = I18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
let firstPos: number = iterator.first(); // firstPos = 0

last⁸⁺

last(): number

Puts the BreakIterator object to the last break point, which is always the next position after the end of the processed text.

System capability: SystemCapability.Global.I18n

Return value

Example

let iterator: I18n.BreakIterator = I18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
let lastPos: number = iterator.last(); // lastPos = 27

next⁸⁺

next(index?: number): number

Moves the BreakIterator object backward by the corresponding number of break points.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let iterator: I18n.BreakIterator = I18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
let pos: number = iterator.first(); // pos = 0
pos = iterator.next(); // pos = 6
pos = iterator.next(10); // pos = -1

previous⁸⁺

previous(): number

Moves the BreakIterator object forward by one break point.

System capability: SystemCapability.Global.I18n

Return value

Example

let iterator: I18n.BreakIterator = I18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
let pos: number = iterator.first(); // pos = 0
pos = iterator.next(3); // pos = 12
pos = iterator.previous(); // pos = 9

following⁸⁺

following(offset: number): number

Moves the BreakIterator to the break point following the specified position.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let iterator: I18n.BreakIterator = I18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
let pos: number = iterator.following(0); // pos = 6
pos = iterator.following(100); // pos = -1
pos = iterator.current(); // pos = 27

isBoundary⁸⁺

isBoundary(offset: number): boolean

Checks whether the specified position of the text is a break point.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let iterator: I18n.BreakIterator = I18n.getLineInstance("en");
iterator.setLineBreakText("Apple is my favorite fruit.");
let isBoundary: boolean = iterator.isBoundary(0); // isBoundary = true;
isBoundary = iterator.isBoundary(5); // isBoundary = false;

I18n.getTimeZone

getTimeZone(zoneID?: string): TimeZone

Obtains the TimeZone object corresponding to the specified time zone ID.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let timezone: I18n.TimeZone = I18n.getTimeZone();

TimeZone

getID

getID(): string

Obtains the ID of the specified TimeZone object.

System capability: SystemCapability.Global.I18n

Return value

Example

let timezone: I18n.TimeZone = I18n.getTimeZone();
let timezoneID: string = timezone.getID(); // timezoneID = "Asia/Shanghai"

getDisplayName

getDisplayName(locale?: string, isDST?: boolean): string

Obtains the localized representation of a TimeZone object.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let timezone: I18n.TimeZone = I18n.getTimeZone();
let timezoneName: string = timezone.getDisplayName("zh-CN", false); // timezoneName = "China Standard Time"

getRawOffset

getRawOffset(): number

Obtains the offset between the time zone represented by a TimeZone object and the UTC time zone.

System capability: SystemCapability.Global.I18n

Return value

Example

let timezone: I18n.TimeZone = I18n.getTimeZone();
let offset: number = timezone.getRawOffset(); // offset = 28800000

getOffset

getOffset(date?: number): number

Obtains the offset between the time zone represented by a TimeZone object and the UTC time zone at a certain time.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let timezone: I18n.TimeZone = I18n.getTimeZone();
let offset: number = timezone.getOffset(1234567890); // offset = 28800000

getAvailableIDs⁹⁺

static getAvailableIDs(): Array<string>

Obtains the list of time zone IDs supported by the system.

System capability: SystemCapability.Global.I18n

Return value

Example

// 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"], 24 time zones supported in total
let ids: Array<string> = I18n.TimeZone.getAvailableIDs();

getAvailableZoneCityIDs⁹⁺

static getAvailableZoneCityIDs(): Array<string>

Obtains the list of time zone city IDs supported by the system.

System capability: SystemCapability.Global.I18n

Return value

Example

// 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"], 24 time zone cities supported in total
let cityIDs: Array<string> = I18n.TimeZone.getAvailableZoneCityIDs();

getCityDisplayName⁹⁺

static getCityDisplayName(cityID: string, locale: string): string

Obtains the localized representation of a time zone city in the specified locale.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let displayName: string = I18n.TimeZone.getCityDisplayName("Shanghai", "zh-CN"); // displayName = "Shanghai (China)"

getTimezoneFromCity⁹⁺

static getTimezoneFromCity(cityID: string): TimeZone

Obtains the TimeZone object corresponding to the specified time zone city ID.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let timezone: I18n.TimeZone = I18n.TimeZone.getTimezoneFromCity("Shanghai");

getTimezonesByLocation¹⁰⁺

static getTimezonesByLocation(longitude: number, latitude: number): Array<TimeZone>

Creates an array of TimeZone objects corresponding to the specified longitude and latitude.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Error codes

For details about the error codes, see I18N Error Codes.

Example

let timezoneArray: Array<I18n.TimeZone> = I18n.TimeZone.getTimezonesByLocation(-118.1, 34.0);
for (let i = 0; i < timezoneArray.length; i++) {
    let tzId: string = timezoneArray[i].getID();
}

Transliterator⁹⁺

getAvailableIDs⁹⁺

static getAvailableIDs(): string[]

Obtains a list of IDs supported by the Transliterator object.

System capability: SystemCapability.Global.I18n

Return value

Example

// A total of 671 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.
// For more information, see ISO-15924.
let ids: string[] = I18n.Transliterator.getAvailableIDs();

getInstance⁹⁺

static getInstance(id: string): Transliterator

Creates a Transliterator object.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let transliterator: I18n.Transliterator = I18n.Transliterator.getInstance("Any-Latn");

transform⁹⁺

transform(text: string): string

Converts the input string from the source format to the target format.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let transliterator: I18n.Transliterator = I18n.Transliterator.getInstance("Any-Latn");
let res: string = transliterator.transform("China"); // res = "zhōng guó"

Unicode⁹⁺

isDigit⁹⁺

static isDigit(char: string): boolean

Checks whether the input string is composed of digits.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let isdigit: boolean = I18n.Unicode.isDigit("1");  // isdigit = true

isSpaceChar⁹⁺

static isSpaceChar(char: string): boolean

Checks whether the input character is a space.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let isspacechar: boolean = I18n.Unicode.isSpaceChar("a");  // isspacechar = false

isWhitespace⁹⁺

static isWhitespace(char: string): boolean

Checks whether the input character is a white space.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let iswhitespace: boolean = I18n.Unicode.isWhitespace("a");  // iswhitespace = false

isRTL⁹⁺

static isRTL(char: string): boolean

Checks whether the input character is of the right to left (RTL) language.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let isrtl: boolean = I18n.Unicode.isRTL("a");  // isrtl = false

isIdeograph⁹⁺

static isIdeograph(char: string): boolean

Checks whether the input character is an ideographic character.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let isideograph: boolean = I18n.Unicode.isIdeograph("a");  // isideograph = false

isLetter⁹⁺

static isLetter(char: string): boolean

Checks whether the input character is a letter.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let isletter: boolean = I18n.Unicode.isLetter("a");  // isletter = true

isLowerCase⁹⁺

static isLowerCase(char: string): boolean

Checks whether the input character is a lowercase letter.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let islowercase: boolean = I18n.Unicode.isLowerCase("a");  // islowercase = true

isUpperCase⁹⁺

static isUpperCase(char: string): boolean

Checks whether the input character is an uppercase letter.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let isuppercase: boolean = I18n.Unicode.isUpperCase("a");  // isuppercase = false

getType⁹⁺

static getType(char: string): string

Obtains the type of the input string.

System capability: SystemCapability.Global.I18n

Parameters

Return value

The following table lists only the common types. For more details, see the Unicode Standard.

Example

let type: string = I18n.Unicode.getType("a"); // type = "U_LOWERCASE_LETTER"

I18NUtil⁹⁺

unitConvert⁹⁺

static unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale: string, style?: string): string

Converts one measurement unit into another and formats the unit based on the specified locale and style.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

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

getDateOrder⁹⁺

static getDateOrder(locale: string): string

Obtains the sequence of the year, month, and day in the specified locale.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let order: string = I18n.I18NUtil.getDateOrder("zh-CN");  // order = "y-L-d"

Normalizer¹⁰⁺

getInstance¹⁰⁺

static getInstance(mode: NormalizerMode): Normalizer

Obtains a Normalizer object for text normalization.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let normalizer: I18n.Normalizer = I18n.Normalizer.getInstance(I18n.NormalizerMode.NFC);

normalize¹⁰⁺

normalize(text: string): string

Normalizes text strings.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let normalizer: I18n.Normalizer = I18n.Normalizer.getInstance(I18n.NormalizerMode.NFC);
let normalizedText: string = normalizer.normalize('\u1E9B\u0323'); // normalizedText = \u1E9B\u0323

NormalizerMode¹⁰⁺

Enumerates text normalization modes.

System capability: SystemCapability.Global.I18n

SystemLocaleManager¹⁰⁺

constructor¹⁰⁺

constructor()

Creates a SystemLocaleManager object.

System API: This is a system API.

System capability: SystemCapability.Global.I18n

Example

let systemLocaleManager: I18n.SystemLocaleManager = new I18n.SystemLocaleManager();

getLanguageInfoArray¹⁰⁺

getLanguageInfoArray(languages: Array<string>, options?: SortOptions): Array<LocaleItem>

Obtains the language sorting array.

System API: This is a system API.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Error codes

For details about the error codes, see I18N Error Codes.

Example

import { BusinessError } from '@ohos.base';

// Assume that the system language is zh-Hans, the system region is CN, and the system locale is zh-Hans-CN.
let systemLocaleManager: I18n.SystemLocaleManager = new I18n.SystemLocaleManager();
let languages: string[] = ["zh-Hans", "en-US", "pt", "ar"];
let sortOptions: I18n.SortOptions = {locale: "zh-Hans-CN", isUseLocalName: true, isSuggestedFirst: true};
try {
    // The language list after sorting is [zh-Hans, en-US, pt, ar].
    let sortedLanguages: Array<I18n.LocaleItem> = systemLocaleManager.getLanguageInfoArray(languages, sortOptions);
} catch(error) {
    let err: BusinessError = error as BusinessError;
    console.error(`call systemLocaleManager.getLanguageInfoArray failed, error code: ${err.code}, message: ${err.message}.`);
}

getRegionInfoArray¹⁰⁺

getRegionInfoArray(regions: Array<string>, options?: SortOptions): Array<LocaleItem>

Obtains the country/region sorting array.

System API: This is a system API.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Error codes

For details about the error codes, see I18N Error Codes.

Example

import { BusinessError } from '@ohos.base';

// Assume that the system language is zh-Hans, the system region is CN, and the system locale is zh-Hans-CN.
let systemLocaleManager: I18n.SystemLocaleManager = new I18n.SystemLocaleManager();
let regions: string[] = ["CN", "US", "PT", "EG"];
let sortOptions: I18n.SortOptions = {locale: "zh-Hans-CN", isUseLocalName: false, isSuggestedFirst: true};
try {
    // The country/region list after sorting is [CN, EG, US, PT].
    let sortedRegions: Array<I18n.LocaleItem> = systemLocaleManager.getRegionInfoArray(regions, sortOptions);
} catch(error) {
    let err: BusinessError = error as BusinessError;
    console.error(`call systemLocaleManager.getRegionInfoArray failed, error code: ${err.code}, message: ${err.message}.`);
}

getTimeZoneCityItemArray¹⁰⁺

static getTimeZoneCityItemArray(): Array<TimeZoneCityItem>

Obtains the array of time zone city items after sorting.

System API: This is a system API.

System capability: SystemCapability.Global.I18n

Return value

Example

import { BusinessError } from '@ohos.base';

try {
  let timeZoneCityItemArray: Array<I18n.TimeZoneCityItem> = I18n.SystemLocaleManager.getTimeZoneCityItemArray();
  for (let i = 0; i < timeZoneCityItemArray.length; i++) {
      console.log(timeZoneCityItemArray[i].zoneId + ", " + timeZoneCityItemArray[i].cityId + ", " + timeZoneCityItemArray[i].cityDisplayName +
          ", " + timeZoneCityItemArray[i].offset + "\r\n");
  }
} catch(error) {
  let err: BusinessError = error as BusinessError;
  console.error(`call SystemLocaleManager.getTimeZoneCityItemArray failed, error code: ${err.code}, message: ${err.message}.`);
}

LocaleItem¹⁰⁺

Represents the list of languages or countries/regions sorted by SystemLocaleManager.

System API: This is a system API.

System capability: SystemCapability.Global.I18n

TimeZoneCityItem¹⁰⁺

Represents the type of time zone city items.

System API: This is a system API.

System capability: SystemCapability.Global.I18n

SuggestionType¹⁰⁺

Represents the language or country/region suggestion type.

System API: This is a system API.

System capability: SystemCapability.Global.I18n

SortOptions¹⁰⁺

Represents the language or country/region sorting option.

System API: This is a system API.

System capability: SystemCapability.Global.I18n

I18n.getDisplayCountry^(deprecated)

getDisplayCountry(country: string, locale: string, sentenceCase?: boolean): string

Obtains the localized script for the specified country.

This API is deprecated since API version 9. You are advised to use System.getDisplayCountry.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let countryName: string = I18n.getDisplayCountry("zh-CN", "en-GB", true); // countryName = true
countryName = I18n.getDisplayCountry("zh-CN", "en-GB"); // countryName = true

I18n.getDisplayLanguage^(deprecated)

getDisplayLanguage(language: string, locale: string, sentenceCase?: boolean): string

Obtains the localized script for the specified language.

This API is deprecated since API version 9. You are advised to use System.getDisplayLanguage.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

let languageName: string = I18n.getDisplayLanguage("zh", "en-GB", true); // languageName = "Chinese"
languageName = I18n.getDisplayLanguage("zh", "en-GB"); // languageName = "Chinese"

I18n.getSystemLanguage^(deprecated)

getSystemLanguage(): string

Obtains the system language.

This API is deprecated since API version 9. You are advised to use System.getSystemLanguage.

System capability: SystemCapability.Global.I18n

Return value

Example

let systemLanguage: string = I18n.getSystemLanguage(); // Obtain the current system language.

I18n.getSystemRegion^(deprecated)

getSystemRegion(): string

Obtains the system region.

This API is deprecated since API version 9. You are advised to use System.getSystemRegion.

System capability: SystemCapability.Global.I18n

Return value

Example

let region: string = I18n.getSystemRegion(); // Obtain the current system region.

I18n.getSystemLocale^(deprecated)

getSystemLocale(): string

Obtains the system locale.

This API is deprecated since API version 9. You are advised to use System.getSystemLocale.

System capability: SystemCapability.Global.I18n

Return value

Example

let locale: string = I18n.getSystemLocale (); // Obtain the system locale.

I18n.is24HourClock^(deprecated)

is24HourClock(): boolean

Checks whether the 24-hour clock is used.

This API is deprecated since API version 9. You are advised to use System.is24HourClock.

System capability: SystemCapability.Global.I18n

Return value

Example

let is24HourClock: boolean = I18n.is24HourClock();

I18n.set24HourClock^(deprecated)

set24HourClock(option: boolean): boolean

Sets the 24-hour clock.

This API is deprecated since API version 9. You are advised to use System.set24HourClock.

Permission required: ohos.permission.UPDATE_CONFIGURATION

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

// Set the system time to the 24-hour clock.
let success: boolean = I18n.set24HourClock(true);

I18n.addPreferredLanguage^(deprecated)

addPreferredLanguage(language: string, index?: number): boolean

Adds a preferred language to the specified position on the preferred language list.

This API is supported since API version 8 and is deprecated since API version 9. You are advised to use System.addPreferredLanguage.

Permission required: ohos.permission.UPDATE_CONFIGURATION

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

// Add zh-CN to the preferred language list.
let language: string = 'zh-CN';
let index: number = 0;
let success: boolean = I18n.addPreferredLanguage(language, index);

I18n.removePreferredLanguage^(deprecated)

removePreferredLanguage(index: number): boolean

Deletes a preferred language from the specified position on the preferred language list.

This API is supported since API version 8 and is deprecated since API version 9. You are advised to use System.removePreferredLanguage.

Permission required: ohos.permission.UPDATE_CONFIGURATION

System capability: SystemCapability.Global.I18n

Parameters

Return value

Example

// Delete the first preferred language from the preferred language list.
let index: number = 0;
let success: boolean = I18n.removePreferredLanguage(index);

I18n.getPreferredLanguageList^(deprecated)

getPreferredLanguageList(): Array<string>

Obtains the list of preferred languages.

This API is supported since API version 8 and is deprecated since API version 9. You are advised to use System.getPreferredLanguageList.

System capability: SystemCapability.Global.I18n

Return value

Example

let preferredLanguageList: Array<string> = I18n.getPreferredLanguageList(); // Obtain the preferred language list.

I18n.getFirstPreferredLanguage^(deprecated)

getFirstPreferredLanguage(): string

Obtains the first language in the preferred language list.

This API is supported since API version 8 and is deprecated since API version 9. You are advised to use System.getFirstPreferredLanguage.

System capability: SystemCapability.Global.I18n

Return value

Example

let firstPreferredLanguage: string = I18n.getFirstPreferredLanguage();

Util^(deprecated)

unitConvert^(deprecated)

unitConvert(fromUnit: UnitInfo, toUnit: UnitInfo, value: number, locale: string, style?: string): string

Converts one measurement unit into another and formats the unit based on the specified locale and style.

This API is supported since API version 8 and is deprecated since API version 9. You are advised to use unitConvert.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Character^(deprecated)

isDigit^(deprecated)

isDigit(char: string): boolean

Checks whether the input string is composed of digits.

This API is supported since API version 8 and is deprecated since API version 9. You are advised to use isDigit.

System capability: SystemCapability.Global.I18n

Parameters

Return value

isSpaceChar^(deprecated)

isSpaceChar(char: string): boolean

Checks whether the input character is a space.

This API is supported since API version 8 and is deprecated since API version 9. You are advised to use isSpaceChar.

System capability: SystemCapability.Global.I18n

Parameters

Return value

isWhitespace^(deprecated)

isWhitespace(char: string): boolean

Checks whether the input character is a white space.

This API is supported since API version 8 and is deprecated since API version 9. You are advised to use isWhitespace.

System capability: SystemCapability.Global.I18n

Parameters

Return value

isRTL^(deprecated)

isRTL(char: string): boolean

Checks whether the input character is of the right to left (RTL) language.

This API is supported since API version 8 and is deprecated since API version 9. You are advised to use isRTL.

System capability: SystemCapability.Global.I18n

Parameters

Return value

isIdeograph^(deprecated)

isIdeograph(char: string): boolean

Checks whether the input character is an ideographic character.

This API is supported since API version 8 and is deprecated since API version 9. You are advised to use isIdeograph.

System capability: SystemCapability.Global.I18n

Parameters

Return value

isLetter^(deprecated)

isLetter(char: string): boolean

Checks whether the input character is a letter.

This API is supported since API version 8 and is deprecated since API version 9. You are advised to use isLetter.

System capability: SystemCapability.Global.I18n

Parameters

Return value

isLowerCase^(deprecated)

isLowerCase(char: string): boolean

Checks whether the input character is a lowercase letter.

This API is supported since API version 8 and is deprecated since API version 9. You are advised to use isLowerCase.

System capability: SystemCapability.Global.I18n

Parameters

Return value

isUpperCase^(deprecated)

isUpperCase(char: string): boolean

Checks whether the input character is an uppercase letter.

This API is supported since API version 8 and is deprecated since API version 9. You are advised to use isUpperCase.

System capability: SystemCapability.Global.I18n

Parameters

Return value

getType^(deprecated)

getType(char: string): string

Obtains the type of the input string.

This API is supported since API version 8 and is deprecated since API version 9. You are advised to use getType.

System capability: SystemCapability.Global.I18n

Parameters

Return value