# Internationalization (intl) >![](../../public_sys-resources/icon-note.gif) **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 contains standard i18n APIs, which are defined in ECMA 402. ## Modules to Import ``` import Intl from '@ohos.intl'; ``` ## Required Permissions None ## Locale ### Attributes

Name	Parameter 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 buddhist, chinese, coptic, dangi, ethioaa, ethiopic, gregory, hebrew, indian, islamic, islamic-umalqura, islamic-tbla, islamic-civil, islamic-rgsa, iso8601, japanese, persian, roc, or islamicc.
collation	string	Yes	No	Collation rules for the locale. The value can be any of the following: big5han, compat, dict, direct, ducet, eor, gb2312, phonebk, phonetic, pinyin, reformed, searchjl, stroke, trad, unihan, and zhuyin.
hourCycle	string	Yes	No	Time system for the locale. The value can be h11, h12, h23, or 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, and wcho.
numeric	boolean	Yes	No	Whether to apply special collation rules for numeric characters.

### constructor constructor\(locale: string, options?: options\) Creates a **Locale** object. - Parameters

Name	Type	Mandatory	Description
locale	string	Yes	A string containing locale information, including the language, optional script, and locale.

- Example ``` var locale = new Intl.Locale("zh-CN"); ``` ### toString toString\(\): string Converts locale information to a string. - Return values

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

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

Type	Description
Locale	Locale object with the minimized information.

- Example ``` var locale = new Intl.Locale("zh-CN"); locale.minimize(); ``` ## DateTimeFormat ### constructor constructor\(locale: string, options?: DateTimeOptions\) Creates a **DateTimeOptions** object for the specified locale. - Parameters

Name	Type	Mandatory	Description
locale	string	Yes	A string containing locale information, including the language, optional script, and locale.
options	DateTimeOptions	No	Options for creating a DateTimeFormat object.

- Example ``` var datefmt= new Intl.DateTimeFormat("zh-CN", { dateStyle: 'full', timeStyle: 'medium' }); ``` ### constructor constructor\(locales: Array, options?: DateTimeOptions\) Creates a **DateTimeOptions** object for the specified array of locales. - Parameters

Name	Type	Mandatory	Description
locales	Array<string>	Yes	An array of strings containing locale information.
options	DateTimeOptions	No	Options for creating a DateTimeFormat object.

- Example ``` var datefmt= new Intl.DateTimeFormat(["ban", "zh"], { dateStyle: 'full', timeStyle: 'medium' }); ``` ### format format\(date: Date\): string Formats the specified date and time. - Parameters

Name	Type	Mandatory	Description
date	Date	Yes	Date and time to be formatted.

- Return values

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\(fromDate: Date, toDate: Date\): string Formats the specified date range. - 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 values

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

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.

Name	Parameter 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 h11, h12, h23, or 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, and 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 numeric, 2-digit, long, short, or 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	Second 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 ### constructor constructor\(locale: string, options?: NumberOptions\) Creates a **NumberFormat** object for the specified locale. - Parameters

Name	Type	Mandatory	Description
locale	string	Yes	A string containing locale information, including the language, optional script, and locale.
options	NumberOptions	No	Options for creating a NumberFormat object.

- Example ``` var numfmt = new Intl.NumberFormat("en-GB", {style:'decimal', notation:"scientific"}); ``` ### constructor constructor\(locales: Array, options?: NumberOptions\) Creates a **NumberFormat** object for the specified array of locales. - Parameters

Name	Type	Mandatory	Description
locales	Array<string>	Yes	An array of strings containing locale information.
options	NumberOptions	No	Options for creating a NumberFormat object.

- Example ``` var numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"}); ``` ### format format\(number: number\): string; Formats a number. - Parameters

Name	Type	Mandatory	Description
number	number	Yes	Number to be formatted.

- Return values

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

Type	Description
NumberOptions	Options of the NumberFormat object.

- Example ``` var numfmt = new Intl.NumberFormat(["en-GB", "zh"], {style:'decimal', notation:"scientific"}); numfmt.resolvedOptions(); ``` ## NumberOptions Provides the device capability.

Name	Parameter 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.
unitUsage	string	Yes	Yes	Unit use case. 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, and 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 notation. 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, and wcho.
useGrouping	boolean	Yes	Yes	Whether to use grouping for display.
miniumumIntegerDigits	number	Yes	Yes	Minimum number of digits allowed in the integer part of a number. The value ranges from 1 to 21.
miniumumFractionDigits	number	Yes	Yes	Minimum number of digits in the fraction part of a number. The value ranges from 0 to 20.
maxiumumFractionDigits	number	Yes	Yes	Maximum number of digits in the fraction part of a number. The value ranges from 1 to 21.
miniumumSignificantDigits	number	Yes	Yes	Minimum number of the least significant digits. The value ranges from 1 to 21.
maxiumumSignificantDigits	number	Yes	Yes	Maximum number of the least significant digits. The value ranges from 1 to 21.

## Collator⁸⁺ ### constructor⁸⁺ constructor\(\) Creates a **Collator** object. - Example ``` var collator = new Intl.Collator(); ``` ### constructor⁸⁺ constructor\(locale: string | Array, options?: CollatorOptions\) Creates a **Collator** object based on the specified locale and options. Parameters

Name	Type	Mandatory	Description
locale	string\|Array<string>	Yes	A string containing locale information, including the language, optional script, and locale.
options	CollatorOptions	No	Options for creating a Collator object.

- Example ``` var collator = new Intl.Collator("zh-CN", {"localeMatcher": "lookup", "usage": "sort"}); ``` ### compare⁸⁺ compare\(first: string, second: string\): number Compares two strings based on the sorting policy of the **Collator**. - Parameters

Name	Type	Mandatory	Description
first	string	Yes	First string to compare.
second	string	Yes	Second string to compare.

- Return values

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"); ``` ### resolvedOptions⁸⁺ resolvedOptions\(\): CollatorOptions Returns properties reflecting the locale and collation options of a **Collator** object. - Return values

Type	Description
CollatorOptions	Properties of the Collator object.

- Example ``` var collator = new intl.Collator("zh-Hans"); var options = collator.resolvedOptions(); ``` ## CollatorOptions⁸⁺ Represents the properties of a **Collator** object.

Name	Parameter 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	Sorting policy. The value can be any of the following: big5han, compat, dict, direct, ducet, eor, gb2312, phonebk, phonetic, pinyin, reformed, searchjl, stroke, trad, unihan, and 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.

## PluralRules⁸⁺ ### constructor⁸⁺ constructor\(\) Create a **PluralRules** object. - Example ``` var pluralRules = new Intl.PluralRules(); ``` ### constructor⁸⁺ constructor\(locale: string | Array, options?: PluralRulesOptions\) Creates a **PluralRules** object based on the specified locale and options. Parameters

Name	Type	Mandatory	Description
locale	string\|Array<string>	Yes	A string containing locale information, including the language, optional script, and locale.
options	PluralRulesOptions	No	Options for creating a PluralRules object.

- Example ``` var pluralRules= new Intl.PluraRules("zh-CN", {"localeMatcher": "lookup", "type": "cardinal"}); ``` ### select⁸⁺ select\(n: number\): string Obtains a string that represents the singular-plural type of the specified number. - Parameters

Name	Type	Mandatory	Description
n	number	Yes	Number for which the singular-plural type is to be obtained.

- Return values

Type	Description
string	Singular-plural type. The options are as follows: zero, one, two, few, many, and others.

- Example ``` var pluralRules = new intl.PluralRules("zh-Hans"); pluralRules.select(1); ``` ## PluralRulesOptions⁸⁺ Represents the properties of a **PluralRules** object.

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

## RelativeTimeFormat⁸⁺ ### constructor⁸⁺ constructor\(\) Creates a **RelativeTimeFormat** object. - Example ``` var relativetimefmt = new Intl.RelativeTimeFormat(); ``` ### constructor⁸⁺ constructor\(locale: string | Array, options?: RelativeTimeFormatInputOptions\) Creates a **RelativeTimeFormat** object based on the specified locale and options. Parameters

Name	Type	Mandatory	Description
locale	string\|Array<string>	Yes	A string containing locale information, including the language, optional script, and locale.
options	RelativeTimeFormatInputOptions	No	Options for creating a RelativeTimeFormat object.

- Example ``` var relativeTimeFormat = new Intl.RelativeTimeFormat("zh-CN", {"localeMatcher": "lookup", "numeric": "always", "style": "long"}); ``` ### format⁸⁺ format\(value: numeric, unit: string\): string Formats the value and unit based on the specified locale and formatting options. - Parameters

Name	Type	Mandatory	Description
value	numeric	Yes	Value to format.
unit	string	Yes	Unit to format. The value can be year, quarter, month, week, day, hour, minute, or second.

- Return values

Type	Description
string	Relative time after formatting.

- Example ``` var relativetimefmt = new Intl.RelativeTimeFormat("zh-CN"); relativetimefmt.format(3, "quarter") ``` ### formatToParts⁸⁺ formatToParts\(value: numeric, unit: string\): Array Returns an array of **RelativeTimeFormat** objects in parts for locale-aware formatting. - Parameters

Name	Type	Mandatory	Description
value	numeric	Yes	Value to format.
unit	string	Yes	Unit to format. The value can be year, quarter, month, week, day, hour, minute, or second.

- Return values

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"); ``` ### resolvedOptions⁸⁺ resolvedOptions\(\): RelativeTimeFormatResolvedOptions Obtains the formatting options for **RelativeTimeFormat** objects. - Return values

Type	Description
RelativeTimeFormatResolvedOptions	Formatting options for RelativeTimeFormat objects.

- Example ``` var relativetimefmt= new Intl.RelativeTimeFormat("en-GB"); relativetimefmt.resolvedOptions(); ``` ## RelativeTimeFormatInputOptions⁸⁺ Represents the properties of a **RelativeTimeFormat** object.

Name	Parameter 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 the internationalized message. The value can be long, short, or narrow.

## RelativeTimeFormatResolvedOptions⁸⁺ Represents the properties of a **RelativeTimeFormat** object.

Name	Parameter Type	Readable	Writable	Description
locale	string	Yes	Yes	A string containing locale information, including the language, optional script, and locale.
numeric	string	Yes	Yes	Format of the output message. The value can be always or auto.
style	string	Yes	Yes	Length of the internationalized message. The value can be long, short, or narrow.
numberingSystem	string	Yes	Yes	Numbering system.