@ohos.i18n (Internationalization) (System API)

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.

• Since API version 11, some APIs of this module are supported in ArkTS widgets.

• This topic describes only system APIs provided by the module. For details about its public APIs, see @ohos.i18n (Internationalization).

Modules to Import

import I18n from '@ohos.i18n';

System⁹⁺

setSystemLanguage⁹⁺

static setSystemLanguage(language: string): void

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

To listen for COMMON_EVENT_LOCALE_CHANGED events after the system language is set, you need to add an event subscriber.

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';
import CommonEventManager from '@ohos.commonEventManager';

// Set the system language
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}.`);
}

// Subscribe to a common event.
let subscriber: CommonEventManager.CommonEventSubscriber; // Used to save the created subscriber object for subsequent subscription and unsubscription.
let subscribeInfo: CommonEventManager.CommonEventSubscribeInfo = { // Define the subscriber information.
  events: [CommonEventManager.Support.COMMON_EVENT_LOCALE_CHANGED]
};
CommonEventManager.createSubscriber(subscribeInfo).then((commonEventSubscriber:CommonEventManager.CommonEventSubscriber) => { // Create a subscriber.
    console.info("createSubscriber");
    subscriber = commonEventSubscriber;
    CommonEventManager.subscribe(subscriber, (err, data) => {
      if (err) {
        console.error(`Failed to subscribe common event. error code: ${err.code}, message: ${err.message}.`);
        return;
      }
      console.info("the subscribed event has occurred."); // Triggered when the subscribed event occurs.
    })
}).catch((err: BusinessError) => {
    console.error(`createSubscriber failed, code is ${err.code}, message is ${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}.`);
}

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}.`);
}

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}.`);
}

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}.`);
}

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 time zone and city combination information.

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