@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 '@kit.LocalizationKit';

System⁹⁺

setSystemLanguage⁹⁺

static setSystemLanguage(language: string): void

Sets the system language.

To listen for system language changes, enable listening for COMMON_EVENT_LOCALE_CHANGED.

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 ohos.i18n Error Codes and Universal Error Codes.

Example

  import { BusinessError, commonEventManager } from '@kit.BasicServicesKit';

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

To listen for system region changes, enable listening for COMMON_EVENT_LOCALE_CHANGED.

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 ohos.i18n Error Codes and Universal Error Codes.

Example

  import { BusinessError } from '@kit.BasicServicesKit';

  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.

To listen for system locale changes, enable listening for COMMON_EVENT_LOCALE_CHANGED.

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 ohos.i18n Error Codes and Universal Error Codes.

Example

  import { BusinessError } from '@kit.BasicServicesKit';

  try {
    i18n.System.setSystemLocale('zh-CN'); // Set the 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 whether to use 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 ohos.i18n Error Codes and Universal Error Codes.

Example

  import { BusinessError } from '@kit.BasicServicesKit';

  // 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 ohos.i18n Error Codes and Universal Error Codes.

Example

  import { BusinessError } from '@kit.BasicServicesKit';

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

Removes 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 ohos.i18n Error Codes and Universal Error Codes.

Example

  import { BusinessError } from '@kit.BasicServicesKit';

  // 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 ohos.i18n Error Codes and Universal Error Codes.

Example

  import { BusinessError } from '@kit.BasicServicesKit';

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

setTemperatureType¹⁸⁺

static setTemperatureType(type: TemperatureType): void

Sets the temperature unit of the system.

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 ohos.i18n Error Codes and Universal Error Codes.

NOTE

The error message of 890001 is subject to the actual error.

Example

  import { BusinessError } from '@kit.BasicServicesKit';

  try {
    i18n.System.setTemperatureType(i18n.TemperatureType.CELSIUS); //: Set the temperature unit to °C.
  } catch(error) {
    let err: BusinessError = error as BusinessError;
    console.error(`call System.setTemperatureType failed, error code: ${err.code}, message: ${err.message}.`);
  }

setFirstDayOfWeek¹⁸⁺

static setFirstDayOfWeek(type: WeekDay): void

Sets the first day of a week.

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 ohos.i18n Error Codes and Universal Error Codes.

NOTE

The error message of 890001 is subject to the actual error.

Example

  import { BusinessError } from '@kit.BasicServicesKit';

  try {
    i18n.System.setFirstDayOfWeek (i18n.WeekDay.MON); // Set the preferred start day of a week to Monday.
  } catch(error) {
    let err: BusinessError = error as BusinessError;
    console.error(`call System.setFirstDayOfWeek 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 list of languages after sorting.

System API: This is a system API.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Error codes

For details about the error codes, see ohos.i18n Error Codes and Universal Error Codes.

Example

  import { BusinessError } from '@kit.BasicServicesKit';

  // 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 IDs of the countries or regions after sorting.

System API: This is a system API.

System capability: SystemCapability.Global.I18n

Parameters

Return value

Error codes

For details about the error codes, see ohos.i18n Error Codes and Universal Error Codes.

Example

  import { BusinessError } from '@kit.BasicServicesKit';

  // 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 list of time zone city items after sorting.

System API: This is a system API.

System capability: SystemCapability.Global.I18n

Return value

Error codes

For details about the error codes, see ohos.i18n Error Codes and Universal Error Codes.

Example

  import { BusinessError } from '@kit.BasicServicesKit';

  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 locale information, which consists of the language, script, and country/region.

System API: This is a system API.

System capability: SystemCapability.Global.I18n

TimeZoneCityItem¹⁰⁺

Represents a time zone and city combination item.

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

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Localization Kit

harmony 鸿蒙RawFileDescriptor

harmony 鸿蒙RawFileDescriptor64

harmony 鸿蒙ResourceManager_Configuration

harmony 鸿蒙Font Management Error Codes

harmony 鸿蒙I18N Error Codes

harmony 鸿蒙Resource Manager Error Codes

harmony 鸿蒙@ohos.fontManager (Font Management)

harmony 鸿蒙@ohos.i18n (Internationalization)

harmony 鸿蒙@ohos.intl (Internationalization)