Internationalization – intl
NOTE
The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
This module contains standard i18n APIs, which are defined in ECMA 402.
Modules to Import
import Intl from '@ohos.intl';
Locale
Attributes
System capability: SystemCapability.Global.I18n
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
language | string | Yes | No | Language associated with the locale, for example, zh. |
script | string | Yes | No | Script type of the language, for example, Hans. |
region | string | Yes | No | Region associated with the locale, for example, CN. |
baseName | string | Yes | No | Basic key information about the locale, which consists of the language, script, and region, for example, zh-Hans-CN. |
caseFirst | string | Yes | No | Whether case is taken into account for the locale's collation rules. The value can be upper, lower, or false. |
calendar | string | Yes | No | Calendar for the locale. The value can be any of the following: buddhist, chinese, coptic, dangi, ethioaa, ethiopic, gregory, hebrew, indian, islamic, islamic-umalqura, islamic-tbla, islamic-civil, islamic-rgsa, iso8601, japanese, persian, roc, islamicc. |
collation | string | Yes | No | Rule for sorting regions. The value can be any of the following: big5han, compat, dict, direct, ducet, eor, gb2312, phonebk, phonetic, pinyin, reformed, searchjl, stroke, trad, unihan, zhuyin. |
hourCycle | string | Yes | No | Time system for the locale. The value can be any of the following: h12, h23, h11, h24. |
numberingSystem | string | Yes | No | Numbering system for the locale. The value can be any of the following: adlm, ahom, arab, arabext, bali, beng, bhks, brah, cakm, cham, deva, diak, fullwide, gong, gonm, gujr, guru, hanidec, hmng, hmnp, java, kali, khmr, knda, lana, lanatham, laoo, latn, lepc, limb, mathbold, mathdbl, mathmono, mathsanb, mathsans, mlym, modi, mong, mroo, mtei, mymr, mymrshan, mymrtlng, newa, nkoo, olck, orya, osma, rohg, saur, segment, shrd, sind, sinh, sora, sund, takr, talu, tamldec, telu, thai, tibt, tirh, vaii, wara, wcho. |
numeric | boolean | Yes | No | Whether to apply special collation rules for numeric characters. |
constructor8+
constructor()
Creates a Locale object.
System capability: SystemCapability.Global.I18n
Example
var locale = new Intl.Locale();
constructor
constructor(locale: string, options?: LocaleOptions)
Creates a Locale object.
System capability: SystemCapability.Global.I18n
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
locale | string | Yes | A string containing locale information, including the language, optional script, and region. |
options | LocaleOptions | No | Options for creating the Locale object. |
Example
var locale = new Intl.Locale("zh-CN");
toString
toString(): string
Converts locale information to a string.
System capability: SystemCapability.Global.I18n
Return Value
Type | Description |
---|---|
string | String containing locale information. |
Example
var locale = new Intl.Locale("zh-CN");
locale.toString();
maximize
maximize(): Locale
Maximizes information of the Locale object. If the script and locale information is missing, add the information.
System capability: SystemCapability.Global.I18n
Return Value
Type | Description |
---|---|
Locale | Locale object with the maximized information. |
Example
var locale = new Intl.Locale("zh-CN");
locale.maximize();
minimize
minimize(): Locale
Minimizes information of the Locale object. If the script and locale information is present, delete the information.
System capability: SystemCapability.Global.I18n
Return Value
Type | Description |
---|---|
Locale | Locale object with the minimized information. |
Example
var locale = new Intl.Locale("zh-CN");
locale.minimize();
LocaleOptions
Represents the locale options.
System capability: SystemCapability.Global.I18n
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
calendar | string | Yes | Yes | Calendar for the locale. The calue can be any of the following: buddhist, chinese, coptic, dangi, ethioaa, ethiopic, gregory, hebrew, indian, islamic, islamic-umalqura, islamic-tbla, islamic-civil, islamic-rgsa, iso8601, japanese, persian, roc, islamicc. |
collation | string | Yes | Yes | Collation rule. The value can be any of the following: big5han, compat, dict, direct, ducet, emoji, eor, gb2312, phonebk, phonetic, pinyin, reformed,search, searchjl, standard, stroke, trad, unihan, zhuyin. |
hourCycle | string | Yes | Yes | Time system for the locale. The value can be any of the following: h11, h12, h23, h24. |
numberingSystem | string | Yes | Yes | Numbering system for the locale. The value can be any of the following: adlm, ahom, arab, arabext, bali, beng, bhks, brah, cakm, cham, deva, diak, fullwide, gong, gonm, gujr, guru, hanidec, hmng, hmnp, java, kali, khmr, knda, lana, lanatham, laoo, latn, lepc, limb, mathbold, mathdbl, mathmono, mathsanb, mathsans, mlym, modi, mong, mroo, mtei, mymr, mymrshan, mymrtlng, newa, nkoo, olck, orya, osma, rohg, saur, segment, shrd, sind, sinh, sora, sund, takr, talu, tamldec, telu, thai, tibt, tirh, vaii, wara, wcho. |
numeric | boolean | Yes | Yes | Whether to use the 12-hour clock. |
caseFirst | string | Yes | Yes | Whether upper case or lower case is sorted first. The value can be upper, lower, or false. |
DateTimeFormat
constructor8+
constructor()
Creates a DateTimeOptions object for the specified locale.
System capability: SystemCapability.Global.I18n
Example
var datefmt= new Intl.DateTimeFormat();
constructor
constructor(locale: string | Array<string>, options?: DateTimeOptions)
Creates a DateTimeOptions object for the specified locale.
System capability: SystemCapability.Global.I18n
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
locale | string | Array<string> | Yes | A string containing locale information, including the language, optional script, and region. |
options | DateTimeOptions | No | Options for creating a DateTimeFormat object. |
Example
var datefmt= new Intl.DateTimeFormat("zh-CN", { dateStyle: 'full', timeStyle: 'medium' });
Example
var datefmt= new Intl.DateTimeFormat(["ban", "zh"], { dateStyle: 'full', timeStyle: 'medium' });
format
format(date: Date): string
Formats the specified date and time.
System capability: SystemCapability.Global.I18n
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
date | Date | Yes | Date and time to be formatted. |
Return Value
Type | Description |
---|---|
string | A string containing the formatted date and time. |
Example
var date = new Date(2021, 11, 17, 3, 24, 0);
var datefmt = new Intl.DateTimeFormat("en-GB");
datefmt.format(date);
formatRange
formatRange(startDate: Date, endDate: Date): string
Formats the specified date range.
System capability: SystemCapability.Global.I18n
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
startDate | Date | Yes | Start date and time to be formatted. |
endDate | Date | Yes | End date and time to be formatted. |
Return Value
Type | Description |
---|---|
string | A string containing the formatted date and time range. |
Example
var startDate = new Date(2021, 11, 17, 3, 24, 0);
var endDate = new Date(2021, 11, 18, 3, 24, 0);
var datefmt = new Intl.DateTimeFormat("en-GB");
datefmt.formatRange(startDate, endDate);
resolvedOptions
resolvedOptions(): DateTimeOptions
Obtains the formatting options for DateTimeFormat object.
System capability: SystemCapability.Global.I18n
Return Value
Type | Description |
---|---|
DateTimeOptions | Formatting options for DateTimeFormat objects. |
Example
var datefmt = new Intl.DateTimeFormat("en-GB");
datefmt.resolvedOptions();
DateTimeOptions
Provides the options for the DateTimeFormat object.
System capability: SystemCapability.Global.I18n
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
locale | string | Yes | No | Locale, for example, zh-Hans-CN. |
dateStyle | string | Yes | Yes | Date display format. The value can be long, short, medium, or full. |
timeStyle | string | Yes | Yes | Time display format. The value can be long, short, medium, or full. |
hourCycle | string | Yes | Yes | Time system for the locale. The value can be any of the following: h11, h12, h23, h24. |
timeZone | string | Yes | Yes | Time zone represented by a valid IANA time zone ID. |
numberingSystem | string | Yes | Yes | Numbering system for the locale. The value can be any of the following: adlm, ahom, arab, arabext, bali, beng, bhks, brah, cakm, cham, deva, diak, fullwide, gong, gonm, gujr, guru, hanidec, hmng, hmnp, java, kali, khmr, knda, lana, lanatham, laoo, latn, lepc, limb, mathbold, mathdbl, mathmono, mathsanb, mathsans, mlym, modi, mong, mroo, mtei, mymr, mymrshan, mymrtlng, newa, nkoo, olck, orya, osma, rohg, saur, segment, shrd, sind, sinh, sora, sund, takr, talu, tamldec, telu, thai, tibt, tirh, vaii, wara, wcho. |
hour12 | boolean | Yes | Yes | Whether to use the 12-hour clock. |
weekday | string | Yes | Yes | Workday display format. The value can be long, short, or narrow. |
era | string | Yes | Yes | Era display format. The value can be long, short, or narrow. |
year | string | Yes | Yes | Year display format. The value can be numeric or 2-digit. |
month | string | Yes | Yes | Month display format. The value can be any of the following: numeric, 2-digit, long, short, narrow. |
day | string | Yes | Yes | Day display format. The value can be numeric or 2-digit. |
hour | string | Yes | Yes | Hour display format. The value can be numeric or 2-digit. |
minute | string | Yes | Yes | Minute display format. The value can be numeric or 2-digit. |
second | string | Yes | Yes | Seconds display format. The value can be numeric or 2-digit. |
timeZoneName | string | Yes | Yes | Localized representation of a time zone name. |
dayPeriod | string | Yes | Yes | Time period display format. The value can be long, short, or narrow. |
localeMatcher | string | Yes | Yes | Locale matching algorithm. The value can be lookup or best fit. |
formatMatcher | string | Yes | Yes | Format matching algorithm. The value can be basic or best fit. |
NumberFormat
constructor8+
constructor()
Creates a NumberFormat object for the specified locale.
System capability: SystemCapability.Global.I18n
Example
var numfmt = new Intl.NumberFormat();
constructor
constructor(locale: string | Array<string>, options?: NumberOptions)
Creates a NumberFormat object for the specified locale.
System capability: SystemCapability.Global.I18n
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
locale | string | Array<string> | Yes | A string containing locale information, including the language, optional script, and region. |
options | NumberOptions | No | Options for creating a NumberFormat object. |
Example
var numfmt = new Intl.NumberFormat("en-GB", {style:'decimal', notation:"scientific"});
format
format(number: number): string;
Formats a number.
System capability: SystemCapability.Global.I18n
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
number | number | Yes | Number to be formatted. |
Return Value
Type | Description |
---|---|
string | Formatted number. |
Example
var numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"});
numfmt.format(1223);
resolvedOptions
resolvedOptions(): NumberOptions
Obtains the options of the NumberFormat object.
System capability: SystemCapability.Global.I18n
Return Value
Type | Description |
---|---|
NumberOptions | Formatting options for NumberFormat objects. |
Example
var numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"});
numfmt.resolvedOptions();
NumberOptions
Provides the device capability.
System capability: SystemCapability.Global.I18n
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
locale | string | Yes | No | Locale, for example, zh-Hans-CN. |
currency | string | Yes | Yes | Currency unit, for example, EUR, CNY, or USD. |
currencySign | string | Yes | Yes | Currency unit symbol. The value can be symbol, narrowSymbol, code, or name. |
currencyDisplay | string | Yes | Yes | Currency display mode. The value can be symbol, narrowSymbol, code, or name. |
unit | string | Yes | Yes | Unit name, for example, meter, inch, or hectare. |
unitDisplay | string | Yes | Yes | Unit display format. The value can be long, short, or medium. |
unitUsage8+ | string | Yes | Yes | Unit usage scenario. The value can be any of the following: default, area-land-agricult, area-land-commercl, area-land-residntl, length-person, length-person-small, length-rainfall, length-road, length-road-small, length-snowfall, length-vehicle, length-visiblty, length-visiblty-small, length-person-informal, length-person-small-informal, length-road-informal, speed-road-travel, speed-wind, temperature-person, temperature-weather, volume-vehicle-fuel. |
signDisplay | string | Yes | Yes | Number sign display format. The value can be auto, never, always, or expectZero. |
compactDisplay | string | Yes | Yes | Compact display format. The value can be long or short. |
notation | string | Yes | Yes | Number formatting specification. The value can be standard, scientific, engineering, or compact. |
localeMatcher | string | Yes | Yes | Locale matching algorithm. The value can be lookup or best fit. |
style | string | Yes | Yes | Number display format. The value can be decimal, currency, percent, or unit. |
numberingSystem | string | Yes | Yes | Numbering system for the locale. The value can be any of the following: adlm, ahom, arab, arabext, bali, beng, bhks, brah, cakm, cham, deva, diak, fullwide, gong, gonm, gujr, guru, hanidec, hmng, hmnp, java, kali, khmr, knda, lana, lanatham, laoo, latn, lepc, limb, mathbold, mathdbl, mathmono, mathsanb, mathsans, mlym, modi, mong, mroo, mtei, mymr, mymrshan, mymrtlng, newa, nkoo, olck, orya, osma, rohg, saur, segment, shrd, sind, sinh, sora, sund, takr, talu, tamldec, telu, thai, tibt, tirh, vaii, wara, wcho. |
useGrouping | boolean | Yes | Yes | Whether to use grouping for display. |
minimumIntegerDigits | number | Yes | Yes | Minimum number of digits allowed in the integer part of a number. The value ranges from 1 to 21. |
minimumFractionDigits | number | Yes | Yes | Minimum number of digits in the fraction part of a number. The value ranges from 0 to 20. |
maximumFractionDigits | number | Yes | Yes | Maximum number of digits in the fraction part of a number. The value ranges from 1 to 21. |
minimumSignificantDigits | number | Yes | Yes | Minimum number of the least significant digits. The value ranges from 1 to 21. |
maximumSignificantDigits | number | Yes | Yes | Maximum number of the least significant digits. The value ranges from 1 to 21. |
Collator8+
constructor8+
constructor()
Creates a Collator object.
System capability: SystemCapability.Global.I18n
Example
var collator = new Intl.Collator();
constructor8+
constructor(locale: string | Array<string>, options?: CollatorOptions)
Creates a Collator object.
System capability: SystemCapability.Global.I18n
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
locale | string | Array<string> | Yes | A string containing locale information, including the language, optional script, and region. |
options | CollatorOptions | No | Options for creating a Collator object. |
Example
var collator = new Intl.Collator("zh-CN", {localeMatcher: "lookup", usage: "sort"});
compare8+
compare(first: string, second: string): number
Compares two strings based on the sorting policy of the Collator object.
System capability: SystemCapability.Global.I18n
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
first | string | Yes | First string to compare. |
second | string | Yes | Second string to compare. |
Return Value
Type | Description |
---|---|
number | Comparison result. If the value is a negative number, the first string is before the second string. If the value of number is 0, the first string is equal to the second string. If the value of number is a positive number, the first string is after the second string. |
Example
var collator = new Intl.Collator("zh-Hans");
collator.compare("first", "second");
resolvedOptions8+
resolvedOptions(): CollatorOptions
Returns properties reflecting the locale and collation options of a Collator object.
System capability: SystemCapability.Global.I18n
Return Value
Type | Description |
---|---|
CollatorOptions | Properties of the Collator object. |
Example
var collator = new Intl.Collator("zh-Hans");
var options = collator.resolvedOptions();
CollatorOptions8+
Represents the properties of a Collator object.
System capability: SystemCapability.Global.I18n
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
localeMatcher | string | Yes | Yes | Locale matching algorithm. The value can be lookup or best fit. |
usage | string | Yes | Yes | Whether the comparison is for sorting or for searching. The value can be sort or search. |
sensitivity | string | Yes | Yes | Differences in the strings that lead to non-zero return values. The value can be base, accent, case, or variant. |
ignorePunctuation | boolean | Yes | Yes | Whether punctuation is ignored. The value can be true or false. |
collation | string | Yes | Yes | Rule for sorting regions. The value can be any of the following: big5han, compat, dict, direct, ducet, eor, gb2312, phonebk, phonetic, pinyin, reformed, searchjl, stroke, trad, unihan, zhuyin. |
numeric | boolean | Yes | Yes | Whether numeric collation is used. The value can be true or false. |
caseFirst | string | Yes | Yes | Whether upper case or lower case is sorted first. The value can be upper, lower, or false. |
PluralRules8+
constructor8+
constructor()
Create a PluralRules object.
System capability: SystemCapability.Global.I18n
Example
var pluralRules = new Intl.PluralRules();
constructor8+
constructor(locale: string | Array<string>, options?: PluralRulesOptions)
Create a PluralRules object.
System capability: SystemCapability.Global.I18n
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
locale | string | Array<string> | Yes | A string containing locale information, including the language, optional script, and region. |
options | PluralRulesOptions | No | Options for creating a PluralRules object. |
Example
var pluralRules= new Intl.PluraRules("zh-CN", {"localeMatcher": "lookup", "type": "cardinal"});
select8+
select(n: number): string
Obtains a string that represents the singular-plural type of the specified number.
System capability: SystemCapability.Global.I18n
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
n | number | Yes | Number for which the singular-plural type is to be obtained. |
Return Value
Type | Description |
---|---|
string | Singular-plural type. The value can be any of the following: one, two, few, many, others. |
Example
var pluralRules = new Intl.PluralRules("zh-Hans");
pluralRules.select(1);
PluralRulesOptions8+
Represents the properties of a PluralRules object.
System capability: SystemCapability.Global.I18n
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
localeMatcher | string | Yes | Yes | Locale matching algorithm. The value can be lookup or best fit. |
type | string | Yes | Yes | Sorting type. The value can be cardinal or ordinal. |
minimumIntegerDigits | number | Yes | Yes | Minimum number of digits allowed in the integer part of a number. The value ranges from 1 to 21. |
minimumFractionDigits | number | Yes | Yes | Minimum number of digits in the fraction part of a number. The value ranges from 0 to 20. |
maximumFractionDigits | number | Yes | Yes | Maximum number of digits in the fraction part of a number. The value ranges from 1 to 21. |
minimumSignificantDigits | number | Yes | Yes | Minimum number of the least significant digits. The value ranges from 1 to 21. |
maximumSignificantDigits | number | Yes | Yes | Maximum number of the least significant digits. The value ranges from 1 to 21. |
RelativeTimeFormat8+
constructor8+
constructor()
Creates a RelativeTimeFormat object.
System capability: SystemCapability.Global.I18n
Example
var relativetimefmt = new Intl.RelativeTimeFormat();
constructor8+
constructor(locale: string | Array<string>, options?: RelativeTimeFormatInputOptions)
Creates a RelativeTimeFormat object.
System capability: SystemCapability.Global.I18n
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
locale | string | Array<string> | Yes | A string containing locale information, including the language, optional script, and region. |
options | RelativeTimeFormatInputOptions | No | Options for creating a RelativeTimeFormat object. |
Example
var relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {"localeMatcher": "lookup", "numeric": "always", "style": "long"});
format8+
format(value: number, unit: string): string
Formats the value and unit based on the specified locale and formatting options.
System capability: SystemCapability.Global.I18n
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
value | number | Yes | Value to format. |
unit | string | Yes | Unit to format. The value can be any of the following: year, quarter, month, week, day, hour, minute, second. |
Return Value
Type | Description |
---|---|
string | Relative time after formatting. |
Example
var relativetimefmt = new Intl.RelativeTimeFormat("zh-CN");
relativetimefmt.format(3, "quarter")
formatToParts8+
formatToParts(value: number, unit: string): Array<object>
Returns an array of RelativeTimeFormat objects in parts for locale-aware formatting.
System capability: SystemCapability.Global.I18n
Parameters
Name | Type | Mandatory | Description |
---|---|---|---|
value | number | Yes | Value to format. |
unit | string | Yes | Unit to format. The value can be any of the following: year, quarter, month, week, day, hour, minute, second. |
Return Value
Type | Description |
---|---|
Array<object> | An array of RelativeTimeFormat objects in parts. |
Example
var relativetimefmt = new Intl.RelativeTimeFormat("en", {"numeric": "auto"});
var parts = relativetimefmt.format(10, "seconds");
resolvedOptions8+
resolvedOptions(): RelativeTimeFormatResolvedOptions
Obtains the formatting options for RelativeTimeFormat objects.
System capability: SystemCapability.Global.I18n
Return Value
Type | Description |
---|---|
RelativeTimeFormatResolvedOptions | Formatting options for RelativeTimeFormat objects. |
Example
var relativetimefmt= new Intl.RelativeTimeFormat("en-GB");
relativetimefmt.resolvedOptions();
RelativeTimeFormatInputOptions8+
Represents the properties of a RelativeTimeFormat object.
System capability: SystemCapability.Global.I18n
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
localeMatcher | string | Yes | Yes | Locale matching algorithm. The value can be lookup or best fit. |
numeric | string | Yes | Yes | Format of the output message. The value can be always or auto. |
style | string | Yes | Yes | Length of an internationalized message. The value can be long, short, or narrow. |
RelativeTimeFormatResolvedOptions8+
Represents the properties of a RelativeTimeFormat object.
System capability: SystemCapability.Global.I18n
Name | Type | Readable | Writable | Description |
---|---|---|---|---|
locale | string | Yes | Yes | A string containing locale information, including the language, optional script, and region. |
numeric | string | Yes | Yes | Format of the output message. The value can be always or auto. |
style | string | Yes | Yes | Length of an internationalized message. The value can be long, short, or narrow. |
numberingSystem | string | Yes | Yes | Numbering system. |