require(["esri/intl"], (intl) => { /* code goes here */ });
import * as intl from "@arcgis/core/intl.js";
esri/intl
Overview
This module provides the ability to set the app locale along with date and number formatting methods and supporting utilities.
The formatting functions formatDate()
, formatNumber()
, and substitute()
rely on the Internationalization APIs available in all web browsers to enable locale-sensitive date, time, and number formatting.
Setting the locale
The SDK will automatically use locale defined via lang
attribute on the root html
element, or the locale of the browser.
To override this behavior, you can set the locale used by the SDK with the setLocale
method.
This locale will determine:
- the number and date formatting used throughout the API,
- the translation of widgets, and
- the place label language of basemaps (if using the basemap styles service).
See the localization guide page for more information.
Number formatting
You can format numbers with formatNumber()
in three different styles: decimal
, percent
, or currency
.
const decimalFormatted = intl.formatNumber(12.5, {
style: "decimal"
});
const percentFormatted = intl.formatNumber(12.5, {
style: "percent"
});
const currencyFormatted = intl.formatNumber(12.5, {
style: "currency",
currency: "EUR",
currencyDisplay: "symbol"
});
console.log(decimalFormatted); // In French locale: 12,5
console.log(percentFormatted); // In French locale: 1 250 %
console.log(currencyFormatted); // In French locale: 12,50 €
By default, numbers are formatted using the appropriate set of options
for a specified style. It is also
possible to control whether to use a grouping separator with a number of integer, fractional, or significant digits.
Date and time formatting
You can format dates with formatDate()
. Each date-time component of the formatted date
can be controlled: weekday
, era
, year
, month
, day
, hour
, minute
, second
, and timeZoneName
.
The locale and region are taken into account to determine the most appropriate order of each component,
or whether to use 24-hour or 12-hour time formats. For example, formatting a date in en-US
and in en-GB
gives
different results.
const now = Date.now();
const dateTimeFormatOptions = {
weekday: "long",
day: "2-digit",
month: "long",
year: "numeric",
hour: "numeric",
minute: "numeric"
};
const formatted = intl.formatDate(now, dateTimeFormatOptions);
console.log(formatted);
// In English en-US: Monday, June 24, 2019, 2:28 PM
// In English en-GB: Monday, 24 June 2019, 14:28
// In French fr-FR: lundi 24 juin 2019 à 14:28
Tips and tricks
The formatDate()
, formatNumber()
, and substitute()
functions are light wrappers
around the Intl APIs that cache the created Intl.DateTimeFormat
and Intl.NumberFormat formatter objects for a set of options
.
Consider reusing the same options
objects to avoid having to recreate these objects.
const currencyFormatter = {
style: "currency",
currency: "EUR",
currencyDisplay: "symbol"
};
function formatCurrency(amount) {
return formatNumber(amount, currencyFormatter);
}
Method Overview
Name | Return Type | Summary | Object |
---|---|---|---|
Converts a web map date format string to an Intl.DateTimeFormat options object. | intl | ||
Converts a NumberFormat to an Intl.NumberFormatOptions object. | intl | ||
Creates a message bundle loader specialized in loading translation files as JSON files. | intl | ||
Promise<Object> | Loads a localized message bundle used with the current API locale. | intl | |
Formats a | intl | ||
Formats a | intl | ||
Formats a | intl | ||
Formats a | intl | ||
Formats a | intl | ||
Returns the current locale used by the API. | intl | ||
Returns one of the known message bundle locale for an input locale. | intl | ||
Registers a callback that gets notified when the locale changes. | intl | ||
Provides right-to-left preference for input locale. | intl | ||
Registers a message loader to load specified message bundles needed for translating strings. | intl | ||
Sets the locale used by the API. | intl | ||
Use this to substitute keys in a | intl |
Method Details
-
convertDateFormatToIntlOptions
convertDateFormatToIntlOptions(format){Intl.DateTimeFormatOptions}
-
Converts a web map date format string to an Intl.DateTimeFormat options object.
Parameterformat StringoptionalA web map date format string to convert.
Possible Values:"short-date"|"short-date-short-time"|"short-date-short-time-24"|"short-date-long-time"|"short-date-long-time-24"|"long-month-day-year"|"long-month-day-year-short-time"|"long-month-day-year-short-time-24"|"long-month-day-year-long-time"|"long-month-day-year-long-time-24"|"day-short-month-year"|"day-short-month-year-short-time"|"day-short-month-year-short-time-24"|"day-short-month-year-long-time"|"day-short-month-year-long-time-24"|"long-date"|"long-date-short-time"|"long-date-short-time-24"|"long-date-long-time"|"long-date-long-time-24"|"long-month-year"|"short-month-year"|"year"|"short-time"|"long-time"
ReturnsType Description Intl.DateTimeFormatOptions The date format options derived from the format string as defined in the web map specification. - See also
Exampleconst dateFormatIntlOptions = intl.convertDateFormatToIntlOptions("short-date-short-time"); // See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat#Parameters // Setting the string value 'short-date-short-time' is similar to what is set in the object below // dateFormatIntlOptions = { // day: "numeric", // month: "numeric", // year: "numeric", // hour: "numeric", // minute: "numeric" // } const now = Date.now(); // 1560375191812 const formattedDate = intl.formatDate(now, dateFormatIntlOptions); console.log(formattedDate); // expected output for US English locale: "6/12/2019, 2:33 PM"
-
convertNumberFormatToIntlOptions
convertNumberFormatToIntlOptions(format){Intl.NumberFormatOptions}
-
Converts a NumberFormat to an Intl.NumberFormatOptions object.
Parameterformat NumberFormatoptionalThe NumberFormat to convert.
ReturnsType Description Intl.NumberFormatOptions The Intl number format options. - See also
Exampleconst numberFormatIntlOptions = intl.convertNumberFormatToIntlOptions({ places: 2, digitSeparator: true }); // See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat#Parameters // Setting the places and digitSeparator above is similar to what is set below // numberFormatIntlOptions = { // useGrouping: true, // minimumFractionDigits: 2, // maximumFractionDigits: 2 // } const number = 123456.789; const formattedNumber = intl.formatNumber(number, numberFormatIntlOptions); console.log(formattedNumber); // expected output for English locale: 123,456.79
-
createJSONLoader
createJSONLoader(params){MessageBundleLoader}
Since: ArcGIS Maps SDK for JavaScript 4.18intl since 4.16, createJSONLoader added at 4.18. -
Creates a message bundle loader specialized in loading translation files as JSON files. Internally, this is the loader used to load locales by the ArcGIS Maps SDK for JavaScript.
ParametersSpecificationparams ObjectThe configuration of the loader.
SpecificationUsed to check if the loader should be used to load a candidate's message bundle.
base StringUsed to calculate the relative path of the file to load.
The location of the translation files. It can be either a
string
orURL
pointing to the folder where the files are located, or a function called with a specified path. The function should return the final path.ReturnsType Description MessageBundleLoader loader - A message bundle loader. Example// Assume the following directory structure src/ assets/ translations/ MyBundle.json MyBundle_fr.json widgets/ MyWidget.ts // Configure the message bundle loader given the directory structure noted above const loader = intl.createJSONLoader({ pattern: "my-application/", // The pattern is used to match the string in `intl.fetchMessageBundle("my-application/translations/MyBundle")` base: "my-application", // This removes the base, ie. "translations/MyBundle" location: new Url("./assets/", window.location.href) // Add the location, ie. "assets/translations/MyBundle" }); // This loads file, "./assets/translations/MyBundle.json" or // "./assets/translations/MyBundle_en.json" (unless locale is updated to something, e.g. like `fr`). // Register the message bundle created from the createJSONLoader method intl.registerMessageBundleLoader(loader); // Fetches the message bundle, "./assets/translations/MyBundle.json" const bundle = await intl.fetchMessageBundle("my-application/MyBundle"); // If no `base` property is specified for the loader method, the assets would read as, src/ assets/ my-application/ translations/ MyBundle.json MyBundle_en.json MyBundle_fr.json // The method would load file, "./assets/my-application/translations/MyBundle.json" or // "./assets/my-application/translations/MyBundle_en.json" (unless locale is updated to something, e.g. like `fr`).
-
fetchMessageBundle
fetchMessageBundle(bundleId){Promise<Object>}
Since: ArcGIS Maps SDK for JavaScript 4.18intl since 4.16, fetchMessageBundle added at 4.18. -
Loads a localized message bundle used with the current API locale. A message bundle is an object containing translations and can be stored as a file on disk, or as an object within code. Internally, the ArcGIS Maps SDK for JavaScript uses JSON files containing localized translations. These bundles are identified by a unique string, ie.
bundleId
.The
fetchMessageBundle
method should be used if functions are working with translated strings outside of a widget. Whereas, if a widget needs to utilize a message bundle, it should do so via the @messageBundle decorator.The
fetchMessageBundle
method words by finding the first loader with apattern
that matches the message identifier. It then calls the loader's own fetchMessageBundle function. If the returned Promise rejects,fetchMessageBundle
finds another loader and repeats the operation until a loader successfully fetches a bundle, or no more loaders are available.Below is an example of the JSON message bundle used for the Home widget localized for US English locale. Below that is a bundle translated for France's French locale for the same widget's strings.
ParameterbundleId StringThe identifier of the message bundle, passed to the loader registered with registerMessageBundleLoader.
ReturnsType Description Promise<Object> When resolved, an object containing the localized message strings. Examples// This snippet shows the JSON message bundle used for the Home widget in English { "widgetLabel": "Home", "button": "Home", "title": "Default map view" }
// This snippet shows the same translation strings in the French locale { "widgetLabel": "Accueil", "button": "Accueil", "title": "Vue cartographique par défaut" }
// Fetches the message bundle from the specified location const bundle = await intl.fetchMessageBundle("my-application/MyBundle"); // English message bundle is loaded // If needing to update or set locale, call setLocale intl.setLocale("fr"); // Once locale is updated, fetch the new French message bundle const bundle = await intl.fetchMessageBundle("my-application/MyBundle");
-
formatDate
formatDate(value, formatOptions){String}
-
Formats a
Date
orNumber
value to a string in the current locale.Internally
formatDate
creates Intl formatter instances for the current locale. The formatters are cached using theiroptions
as a cache key. Reuse the sameoptions
objects for best performance.ParametersThe Date object, or the number of milliseconds elapsed since January 1, 1970 00:00:00 UTC, to be formatted.
formatOptions Intl.DateTimeFormatOptionsoptionalDate format options.
ReturnsType Description String Formatted string for the input Date value. - See also
Exampleconst now = Date.now(); // 1560375191812 const dateFormatIntlOptions = intl.convertDateFormatToIntlOptions("short-date-short-time"); const formattedDate = intl.formatDate(now, dateFormatIntlOptions); console.log(formattedDate); // expected output for English locale: "6/12/2019, 2:33 PM"
-
formatDateOnly
formatDateOnly(value, options){String}
Since: ArcGIS Maps SDK for JavaScript 4.28intl since 4.16, formatDateOnly added at 4.28. -
Formats a
date-only
field value to a string in the current locale.Internally
formatDateOnly
creates Intl formatter instances for the current locale. The formatters are cached using theiroptions
as a cache key. Reuse the sameoptions
objects for best performance.Parametersvalue StringThe
date-only
field value.options Intl.DateTimeFormatOptionsoptionalDate format options.
ReturnsType Description String Formatted string for the input date-only
value.Example// Examples of formatting "1959-10-13" on an device set to locale "en-us". console.log(intl.formatDateOnly("1959-10-13")); // 10/13/1959 console.log(intl.formatDateOnly("1959-10-13", intl.convertDateFormatToIntlOptions("short-date"))); // 10/13/1959 console.log(intl.formatDateOnly("1959-10-13", intl.convertDateFormatToIntlOptions("long-date")); // Tuesday, October 13, 1959
-
formatNumber
formatNumber(value, formatOptions){String}
-
Formats a
Number
value to a string in the current locale.Internally
formatNumber
creates Intl formatter instances for the current locale. The formatters are cached using theiroptions
as a cache key. Reuse the sameoptions
objects for best performance.Parametersvalue NumberNumber to be formatted.
formatOptions Intl.NumberFormatOptionsoptionalNumber format options.
ReturnsType Description String Formatted string for the input Number. Examples// Formats a number with a fixed number of places using a digit separator const numberFormatIntlOptions = intl.convertNumberFormatToIntlOptions({ places: 2, digitSeparator: true }); const number = 123456.789; const formattedNumber = intl.formatNumber(123456.789, numberFormatIntlOptions); console.log(formattedNumber); // In US English locale: 123,456.79
// Formats a number as currency, in Euros const amount = 14; const formattedNumber = intl.formatNumber(amount, { style: "currency", currency: "EUR", currencyDisplay: "symbol" }); console.log(formattedNumber); // In for US English locale: €14.00
// Formats a number as percentage const growth = 0.5; const formattedNumber = intl.formatNumber(growth, { style: "percent" }); console.log(formattedNumber); // In for US English locale: 50%
-
formatTimeOnly
formatTimeOnly(value, options){String}
Since: ArcGIS Maps SDK for JavaScript 4.28intl since 4.16, formatTimeOnly added at 4.28. -
Formats a
time-only
field value to a string in the current locale.Internally
formatTimeOnly
creates Intl formatter instances for the current locale. The formatters are cached using theiroptions
as a cache key. Reuse the sameoptions
objects for best performance.Parametersvalue StringThe
time-only
field value.options Intl.DateTimeFormatOptionsoptionalTime format options.
ReturnsType Description String Formatted string for the input time-only
value.Example// Examples of formatting "13:10:39" on an device set to locale "en-us". console.log(intl.formatTimeOnly("13:10:39")); // 1:10 PM console.log(intl.formatTimeOnly("13:10:39", intl.convertDateFormatToIntlOptions("short-time")); // 1:10 PM console.log(intl.formatTimeOnly("13:10:39", intl.convertDateFormatToIntlOptions("long-time")); // 1:10:39 PM
-
formatTimestamp
formatTimestamp(value, options){String}
Since: ArcGIS Maps SDK for JavaScript 4.28intl since 4.16, formatTimestamp added at 4.28. -
Formats a
timestamp-offset
field value to a string in the current locale.Internally
formatTimestamp
creates Intl formatter instances for the current locale. The formatters are cached using theiroptions
as a cache key. Reuse the sameoptions
objects for best performance.Parametersvalue StringThe
timestamp-offset
field value.options Intl.DateTimeFormatOptionsoptionalTimestamp format options.
ReturnsType Description String Formatted string for the input timestamp-offset
value.Exampleconsole.log(intl.formatDateOnly("1959-10-13")); // output - 10/13/1959 console.log(intl.formatDateOnly("1959-10-13", intl.convertDateFormatToIntlOptions("long-date"));
-
getLocale
getLocale(){String}
Since: ArcGIS Maps SDK for JavaScript 4.16intl since 4.16, getLocale added at 4.16. -
Returns the current locale used by the API. The API reads this information in a specified order. This order is described as follows:
- What is initialized using the global
esriConfig
variable, which also initializes theesri/config
module. - What is set in
dojoConfig.locale
for backward compatibility - The
lang
attribute defined on the roothtml
element. - What is set
navigator.language
, the locale defined by the web browser's user's preferences.
The preferred way of setting a locale is via the
lang
attribute on the roothtml
element. A callback can be invoked to notify when the locale changes by usingonLocaleChange()
.ReturnsType Description String The current locale string. - What is initialized using the global
-
Since: ArcGIS Maps SDK for JavaScript 4.18intl since 4.16, normalizeMessageBundleLocale added at 4.18. -
Returns one of the known message bundle locale for an input locale. For example, the known message bundle locale for
"fr-FR"
is"fr"
.The following set of locales are available:
ar
,bs
,ca
,cs
,da
,de
,el
,en
,es
,et
,fi
,fr
,he
,hi
,hr
,hu
,id
,it
,ja
,ko
,lt
,lv
,nb
,nl
,pl
,pt-BR
,pt-PT
,ro
,ru
,sk
,sl
,sr
,sv
,th
,tr
,uk
,vi
,zh-CN
,zh-HK
, andzh-TW
.Parameterlocale StringAny locale string.
ReturnsExample// For example: `en-US` let locale = intl.getLocale(); // locale is now `en` locale = intl.normalizeMessageBundleLocale(locale);
-
onLocaleChange
onLocaleChange(callback){Handle}
Since: ArcGIS Maps SDK for JavaScript 4.16intl since 4.16, onLocaleChange added at 4.16. -
Registers a callback that gets notified when the locale changes. This happens when setLocale() is called, or when the web browser locale changes by the user and the current locale is equal to that of the web browser.
Parametercallback LocaleChangeCallbackA function that is fired when the locale changes. It is called with the newly-set locale after executing the setLocale() method.
ReturnsType Description Handle Returns a handler with a remove()
method that can be called to remove the callback and stop listening for locale changes.- See also
Example// Initially fetches the message bundle in the current language. let bundle = await intl.fetchMessageBundle("my-application/MyBundle"); // Do something with the bundle // Set the locale to French intl.setLocale("fr"); // Listen for when locale is changed and then fetch the updated French message bundle intl.onLocaleChange(function(locale) { console.log("locale changed to: ", locale); let bundle = await intl.fetchMessageBundle("my-application/MyBundle"); });
-
prefersRTL
prefersRTL(locale){Boolean}
Since: ArcGIS Maps SDK for JavaScript 4.16intl since 4.16, prefersRTL added at 4.16. -
Provides right-to-left preference for input locale.
Parameterlocale StringoptionalThe locale string to obtain the right-to-left information. The current locale is used by default.
ReturnsType Description Boolean Returns true
if right-to-left is preferred for the inputlocale
. For example, this returnstrue
if the locale isar
orhe
.
-
registerMessageBundleLoader
registerMessageBundleLoader(loader){Object}
Since: ArcGIS Maps SDK for JavaScript 4.18intl since 4.16, registerMessageBundleLoader added at 4.18. -
Registers a message loader to load specified message bundles needed for translating strings. This method needs to be called prior to fetching the application's message bundle(s).
There are two options for creating the required MessageBundleLoader param.
- Define your own loader by implementing a MessageBundleLoader, or
- Use the loader the API implements via the convenience method, createJSONLoader.
Examples for both are provided below.
Parameterloader MessageBundleLoaderA message bundle loader.
ReturnsType Description Object Returns a handler with a remove()
method that should be called to unregister the message loader.Property Type Description remove Function When called, unregisters the message loader. Examples// This example defines a loader by implementing a MessageBundleLoader. // Register a loader that loads bundles with the specified bundle identifier // starting with "my-application\/" const patternBundle = /^my-application\/(.+)/g; intl.registerMessageBundleLoader({ pattern: patternBundle, // Calls the FetchMessageBundle function of the loader, passing in the bundle identifier and locale async fetchMessageBundle(bundleId, locale) { // extract the filename from the bundle id. const filename = pattern.exec(bundleId)[1]; // normalize the locale, e.g. 'fr-FR' > 'fr' const knownLocale = intl.normalizeMessageBundleLocale(locale); // Fetch the corresponding JSON file given the specified url path const response = await fetch(new Url(`./assets/translations/${filename}_${knownLocale}.json`, window.location.href)); return response.json(); } }); // If the locale changes, calling fetchMessageBundle resolves to the new localized message bundle. intl.onLocaleChange((newLocale) => { const bundle = await intl.fetchMessageBundle("my-application/translations/MyBundle"); // loads file: "https://myserver/my-application/translations/MyBundle_fr.json" }); // Updates the locale intl.setLocale("fr");
// This example defines the loader via the createJSONLoader method. // Register a loader that loads bundles with the specified bundle identifier // starting with "my-application\/" const patternBundle = /^my-application\/(.+)/g; intl.registerMessageBundleLoader( intl.createJSONLoader({ pattern: patternBundle, base: "my-application/", location: new URL("./assets/", window.location.href) }) ); // If the locale changes, calling fetchMessageBundle resolves to the new localized message bundle. intl.onLocaleChange((newLocale) => { const bundle = await intl.fetchMessageBundle("my-application/MyBundle"); // loads file: "https://myserver/my-application/MyBundle_fr.json" }); // Updates the locale intl.setLocale("fr");
-
Since: ArcGIS Maps SDK for JavaScript 4.16intl since 4.16, setLocale added at 4.16. -
Sets the locale used by the API. Prefer setting the
lang
attribute on the roothtml
element.When the locale changes, the registered callback for
onLocaleChange()
is called.The JavaScript API widgets react when the locale changes at runtime. Please note that this is considered experimental.
The JavaScript API offers the same level of support for number, and date formatting as web browsers' Intl APIs. For translations of widgets, the following set of locales are available:
ar
,bg
,bs
,ca
,cs
,da
,de
,el
,en
,es
,et
,fi
,fr
,he
,hr
,hu
,id
,it
,ja
,ko
,lt
,lv
,nb
,nl
,pl
,pt-BR
,pt-PT
,ro
,ru
,sk
,sl
,sr
,sv
,th
,tr
,uk
,vi
,zh-CN
,zh-HK
, andzh-TW
.If translation messages are not available for the current locale, the language is determined based on the order as described in getLocale(); or else it defaults to English messages.
Then it is possible to set the locale to
en-US
oren-GB
. The widgets are translated usingen
messages, while dates and numbers use their corresponding formatting.Parameterlocale StringThe new Unicode locale identifier string, similar to the Intl APIs. If this is
undefined
, the locale is reset to its default value described ingetLocale()
.Example// Sets the locale to French intl.setLocale("fr"); // Sets the locale to UK English. // Dates are formatted in day/month/year order. intl.setLocale("en-GB"); // Sets the locale to US English. // Dates are formatted in month/day/year order. intl.setLocale("en-US");
-
substitute
substitute(template, data, options){String}
-
Use this to substitute keys in a
template
string with values from the argumentdata
.null
orundefined
values aren't printed in the output result.The formatting of the values from
data
can be specified. By default the values will be formatted based on their native JavaScript type.Internally
substitute
creates Intl formatter instances for the current locale. The formatters are cached using theoptions
as a cache key. Reuse the sameoptions
objects for best performance.Parameterstemplate StringTemplate string to use for substitution.
data ObjectData object to be substituted.
options SubstituteOptionsoptionalOptions for determining how to substitute keys in the template string.
ReturnsType Description String The formatted string. Examples// Format a date const data = { increasedValue: 500, time: Date.UTC(2019), } const dateFormatOptions = intl.convertDateFormatToIntlOptions("short-date-short-time-24"); intl.substitute("Date: {time}", data, { format: { time: { type: "date", intlOptions: dateFormatOptions } } });
// Format a number const data = { increasedValue: 500, time: Date.UTC(2019), } intl.substitute("Number: {value}", data, { format: { value: { type: "number", intlOptions: { maximumFractionDigits: 21 } } } });
const data = { increasedValue: 500, time: Date.UTC(2019), } intl.substitute("Median income increased by {increasedValue} in {time:yearFormat}", data, { format: { increasedValue: { type: "number", intlOptions: { useGrouping: true, currency: "EUR", currencyDisplay: "symbol", maximumFractionDigits: 2 } }, yearFormat: { type: "date", intlOptions: { year: "numeric" } } } });
Type Definitions
-
FetchMessageBundle
FetchMessageBundle(bundleId, locale){Promise<Object>}
Since: ArcGIS Maps SDK for JavaScript 4.18intl since 4.16, FetchMessageBundle added at 4.18. -
The function responsible for fetching a message bundle resource for a particular locale.
ParametersReturnsType Description Promise<Object> Resolves to an object containing the localized message strings. - See also
-
The onLocaleChange() method registers this callback when the locale changes.
ParameternewLocale StringA string containing a reference to the changed locale.
-
Since: ArcGIS Maps SDK for JavaScript 4.18intl since 4.16, MessageBundleLoader added at 4.18. -
A message bundle loader is an object used to load translation strings in the user's locale. It must be registered in
intl
using registerMessageBundleLoader. When loading message bundles in the API, the last registered loader is evaluated first.- Properties
-
Used to check if the loader should be used to load a candidate message bundle.
fetchMessageBundle FetchMessageBundleCalled to load the message bundle if the
pattern
matches the bundle identifier. - See also
Exampleconst loader = { // The loader matches all the bundle identifiers starting with "my-application/" pattern: "my-application/", // fetch the JSON file from a `translations` folder async fetchMessageBundle(bundleId, locale) { const url = new URL(`/assets/translations/${bundleId}_${locale}.json`, window.location.href); const response = await fetch(url); return response.json(); } }; registerMessageBundleLoader(loader); // Fetch file `./translations/my-application/MyBundle_en-US.json` const bundle = await fetchMessageBundle("my-application/translations/MyBundle");
-
The Web map definition for formatting numbers. This provides more detail about how a number value should be displayed.
- Properties
-
digitSeparator Boolean
Indicates if the number should be formatted with a thousands separator. This is equivalent to
useGrouping
.places NumberSpecifies the number of decimal places that should appear in the formatted number. Any places beyond this value are rounded. This is equivalent to defining
minimumFractionDigits
andmaximumFractionDigits
. - See also
-
The formatting options for date values.
- Properties
-
type String
The type of this format. The value is always
"date"
.The value is always "date".
intlOptions Intl.DateTimeFormatOptionsThe date format options for the Intl.DateTimeFormat object.
- See also
Exampleconst dateFormat = { type: "date", intlOptions: { year: "numeric", month: "numeric", day: "numeric", hour: "numeric", minute: "numeric" } }; let data = { time: Date.now() }; intl.substitute("Date: {time}", data, { format: { time: dateFormat } });
-
The formatting options for numeric values.
- Properties
-
type String
The type of this format. The value is always
"number"
.The value is always "number".
intlOptions Intl.NumberFormatOptionsThe Intl number format options for the Intl.NumberFormat object.
- See also
Examples// Formats a number with a fixed number of fraction digits const numberFormat = { type: "number", intlOptions: { style: "decimal", useGrouping: true, minimumFractionDigits: 2, maximumFractionDigits: 2 } }); let data = { value: 10 }; intl.substitute("A number: {value}", data, { value: numberFormat });
// Formats a number as currency, in Euros. const currencyFormat = { type: "number", intlOptions: { style: "currency", currency: "EUR", currencyDisplay: "symbol" } }; let data = { amount: 14 }; intl.substitute("Amount: {amount}", data, { amount: currencyFormat });
// Formats a number as a percentage. const percentFormat = { type: "number", intlOptions: { style: "percent" } }; let data = { growth: 0.5 }; intl.substitute("Growth: {growth}", data, { growth: percentFormat });
-
An object to specify substitution options.
Use the format property to define the formatting for each value referenced in the string template.
format
is a key-value pair object. Each key can either be:- a property of the
data
parameter orsubstitute()
- a named formatter than can be referenced in the template string.
In the following example, the
time
property fromdata
will be formatted as a date with each component in numeric format.const data = { time: Date.now() }; intl.substitute("Date: {time}", data, { format: { time: { type: "date", intlOptions: { year: "numeric", month: "numeric", day: "numeric", hour: "numeric", minute: "numeric" } } } });
The following example uses a named formatter to format the
time
property twice with different formatting options.const data = { time: Date.now() }; intl.substitute("In {time:monthFormat} of {time:yearFormat}", data, { format: { monthFormat: { type: "date", intlOptions: { month: "long" } }, yearFormat: { type: "date", intlOptions: { year: "numeric" } } } });
- Property
-
A hashmap of string keys to formatting options.
- See also
- a property of the