import { convertDateFormatToIntlOptions, convertDateTimeFieldFormatToIntlOptions, convertNumberFieldFormatToIntlOptions, convertNumberFormatToIntlOptions, createJSONLoader } from "@arcgis/core/intl.js";const { convertDateFormatToIntlOptions, convertDateTimeFieldFormatToIntlOptions, convertNumberFieldFormatToIntlOptions, convertNumberFormatToIntlOptions, createJSONLoader } = await $arcgis.import("@arcgis/core/intl.js");- Since
- ArcGIS Maps SDK for JavaScript 4.12
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 components, 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);}Functions
| Name | Return Type | Object |
|---|---|---|
| | ||
| | ||
Intl.NumberFormatOptions | | |
Intl.NumberFormatOptions | | |
| | ||
| | ||
| | ||
| | ||
| | ||
| | ||
| | ||
| | ||
| | ||
| | ||
| | ||
| | ||
| | ||
| | ||
| |
convertDateFormatToIntlOptions
Converts a web map date format string to an Intl.DateTimeFormat options object.
- See also
- Signature
-
convertDateFormatToIntlOptions (format: DateFormat | TimeFormat): Intl.DateTimeFormatOptions
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| format | A web map date format string to convert. | |
- Returns
- Intl.DateTimeFormatOptions
The date format options derived from the format string as defined in the web map specification.
Example
const 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(); // 1560375191812const formattedDate = intl.formatDate(now, dateFormatIntlOptions);
console.log(formattedDate); // expected output for US English locale: "6/12/2019, 2:33 PM" convertDateTimeFieldFormatToIntlOptions
- Since
- ArcGIS Maps SDK for JavaScript 4.34
Converts a DateTimeFieldFormat to an Intl.DateTimeFormatOptions options object.
- See also
- Signature
-
convertDateTimeFieldFormatToIntlOptions (format: DateTimeFieldFormat): Intl.DateTimeFormatOptions
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| format | The DateTimeFieldFormat to convert. | |
- Returns
- Intl.DateTimeFormatOptions
The Intl date format options.
Example
const dateTimeFieldFormat = new DateTimeFieldFormat({ dateStyle: "short", timeStyle: "short", hour12: "always"});const dateTimeFieldFormatIntlOptions = intl.convertDateTimeFieldFormatToIntlOptions(dateTimeFieldFormat);const now = Date.now(); // 1759292167543const formattedDateTime = intl.formatDate(now, dateTimeFieldFormatIntlOptions);console.log(formattedDateTime); // expected output for US English locale: "9/30/25, 9:16 PM" convertNumberFieldFormatToIntlOptions
- Since
- ArcGIS Maps SDK for JavaScript 4.34
Converts a NumberFieldFormat to an Intl.NumberFormatOptions options object.
- See also
- Signature
-
convertNumberFieldFormatToIntlOptions (format: NumberFieldFormat): Intl.NumberFormatOptions
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| format | The NumberFieldFormat to convert. | |
- Returns
- Intl.NumberFormatOptions
The Intl number format options.
Example
const numberFieldFormat = new NumberFieldFormat({ useGrouping: "always", minimumFractionDigits: 2, maximumFractionDigits: 2});const numberFieldFormatIntlOptions = intl.convertNumberFieldFormatToIntlOptions(numberFieldFormat);const number = 123456.789;const formattedNumber = intl.formatNumber(number, numberFieldFormatIntlOptions);console.log(formattedNumber); // expected output for English locale: 123,456.79 convertNumberFormatToIntlOptions
Converts a NumberFormat to an Intl.NumberFormatOptions object.
- See also
- Signature
-
convertNumberFormatToIntlOptions (format?: NumberFormat): Intl.NumberFormatOptions
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| format | The NumberFormat to convert. | |
- Returns
- Intl.NumberFormatOptions
The Intl number format options.
Example
const 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
- Since
- ArcGIS Maps SDK for JavaScript 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.
- Signature
-
createJSONLoader (params: JSONLoaderOptions): MessageBundle
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| params | The configuration of the loader. | |
- Returns
- MessageBundle
loader - A message bundle loader.
Example
// Assume the following directory structuresrc/ 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 methodintl.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
- Since
- ArcGIS Maps SDK for JavaScript 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 a pattern 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.
- Signature
-
fetchMessageBundle (bundleId: string): Promise<MessageBundle>
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| bundleId | The identifier of the message bundle, passed to the loader registered with registerMessageBundleLoader(). | |
- Returns
- Promise<MessageBundle>
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 locationconst bundle = await intl.fetchMessageBundle("my-application/MyBundle");// English message bundle is loaded
// If needing to update or set locale, call setLocaleintl.setLocale("fr");
// Once locale is updated, fetch the new French message bundleconst bundle = await intl.fetchMessageBundle("my-application/MyBundle"); formatDate
Formats a Date or Number value to a string in the current locale.
Internally formatDate creates Intl formatter instances for the current locale.
The formatters are cached using their options as a cache key.
Reuse the same options objects for best performance.
- See also
- Signature
-
formatDate (value: number | Date | undefined, options?: DateTimeFormatOptions): string
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| value | The Date object, or the number of milliseconds elapsed since January 1, 1970 00:00 UTC, to be formatted. | | |
| options | Date format options. | |
- Returns
- string
Formatted string for the input Date value.
Example
const now = Date.now(); // 1560375191812const 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
- Since
- ArcGIS Maps SDK for JavaScript 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 their options as a cache key.
Reuse the same options objects for best performance.
- Signature
-
formatDateOnly (value: string, options?: Intl.DateTimeFormatOptions): string
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| value | The | | |
| options | Date format options. | |
- Returns
- string
Formatted string for the input
date-onlyvalue.
Example
// Examples of formatting "1959-10-13" on an device set to locale "en-us".console.log(intl.formatDateOnly("1959-10-13")); // 10/13/1959console.log(intl.formatDateOnly("1959-10-13", intl.convertDateFormatToIntlOptions("short-date"))); // 10/13/1959console.log(intl.formatDateOnly("1959-10-13", intl.convertDateFormatToIntlOptions("long-date")); // Tuesday, October 13, 1959 formatNumber
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 their options as a cache key.
Reuse the same options objects for best performance.
- Signature
-
formatNumber (value: number, options?: Intl.NumberFormatOptions): string
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| value | Number to be formatted. | | |
| options | Intl.NumberFormatOptions | Number format options. | |
- Returns
- string
Formatted string for the input Number.
Examples
// Formats a number with a fixed number of places using a digit separatorconst 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 Eurosconst 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 percentageconst growth = 0.5;const formattedNumber = intl.formatNumber(growth, { style: "percent"});console.log(formattedNumber); // In for US English locale: 50% formatTimeOnly
- Since
- ArcGIS Maps SDK for JavaScript 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 their options as a cache key.
Reuse the same options objects for best performance.
- Signature
-
formatTimeOnly (value: string, options?: Intl.DateTimeFormatOptions): string
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| value | The | | |
| options | Time format options. | |
- Returns
- string
Formatted string for the input
time-onlyvalue.
Example
// Examples of formatting "13:10:39" on an device set to locale "en-us".console.log(intl.formatTimeOnly("13:10:39")); // 1:10 PMconsole.log(intl.formatTimeOnly("13:10:39", intl.convertDateFormatToIntlOptions("short-time")); // 1:10 PMconsole.log(intl.formatTimeOnly("13:10:39", intl.convertDateFormatToIntlOptions("long-time")); // 1:10:39 PM formatTimestamp
- Since
- ArcGIS Maps SDK for JavaScript 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 their options as a cache key.
Reuse the same options objects for best performance.
- Signature
-
formatTimestamp (value: string, options?: DateTimeFormatOptions): string
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| value | The | | |
| options | Timestamp format options. | |
- Returns
- string
Formatted string for the input
timestamp-offsetvalue.
Example
console.log(intl.formatDateOnly("1959-10-13")); // output - 10/13/1959console.log(intl.formatDateOnly("1959-10-13", intl.convertDateFormatToIntlOptions("long-date")); getLocale
- Since
- ArcGIS Maps SDK for JavaScript 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
esriConfigvariable, which also initializes theesri/configmodule. - The
langattribute defined on the roothtmlelement. - 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 root html element.
A callback can be invoked to notify when the locale changes by using onLocaleChange().
- Signature
-
getLocale (): string
- Returns
- string
The current locale string.
getLocaleLanguage
- Since
- ArcGIS Maps SDK for JavaScript 4.34
This function returns the language code associated with the current locale.
- Signature
-
getLocaleLanguage (): string | null | undefined
Example
console.log(intl.getLocaleLanguage()); // "ar" normalizeMessageBundleLocale
- Since
- ArcGIS Maps SDK for JavaScript 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,
hr, hu, id, it, ja, ko, lt, lv, no, nl, pl, pt-BR,
pt-PT, ro, ru, sk, sl, sr, sv, th, tr, uk, vi, zh-CN, zh-HK, and
zh-TW.
- Signature
-
normalizeMessageBundleLocale (locale: string): null | undefined | MessageBundleLocale
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| locale | Any locale string. | |
- Returns
- null | undefined | MessageBundleLocale
The normalized locale, or null if no known locale was found.
Example
// For example: `en-US`let locale = intl.getLocale();// locale is now `en`locale = intl.normalizeMessageBundleLocale(locale); onLocaleChange
- Since
- ArcGIS Maps SDK for JavaScript 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.
- See also
- Signature
-
onLocaleChange (callback: LocaleChangeCallback): ResourceHandle
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| callback | A function that is fired when the locale changes. It is called with the newly-set locale after executing the setLocale() method. | |
- Returns
- ResourceHandle
Returns a handler with a
remove()method that can be called to remove the callback and stop listening for locale changes.
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 Frenchintl.setLocale("fr");
// Listen for when locale is changed and then fetch the updated French message bundleintl.onLocaleChange(function(locale) { console.log("locale changed to: ", locale); let bundle = await intl.fetchMessageBundle("my-application/MyBundle");}); prefersRTL
- Since
- ArcGIS Maps SDK for JavaScript 4.16
Provides right-to-left preference for input locale.
- Signature
-
prefersRTL (locale?: string): boolean
registerMessageBundleLoader
- Since
- ArcGIS Maps SDK for JavaScript 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.
- Signature
-
registerMessageBundleLoader (loader: MessageBundleLoader): ResourceHandle
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| loader | A message bundle loader. | |
- Returns
- ResourceHandle
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 localeintl.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 localeintl.setLocale("fr"); setLocale
- Since
- ArcGIS Maps SDK for JavaScript 4.16
Sets the locale used by the SDK.
Prefer setting the lang attribute on the root html element.
When the locale changes, the registered callback for onLocaleChange() is called.
The JavaScript SDK reacts when the locale changes at runtime. Please note that this is considered experimental.
The JavaScript SDK offers the same level of support for number, and date formatting
as web browsers' Intl APIs.
For string translations, 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, no, nl, pl, pt-BR,
pt-PT, ro, ru, sk, sl, sr, sv, th, tr, uk, vi, zh-CN, zh-HK, and
zh-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.
It is possible to set the locale to be more specific such as en-AU or fr-CA.
The strings will still be translated using en messages (which use American English),
while dates, times, and numbers use the more specific data and number formatting.
Read more in Locale fallback.
- Signature
-
setLocale (locale: string | null | undefined): void
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| locale | The new Unicode locale identifier string, similar to the Intl APIs.
If this is | |
- Returns
- void
Example
// Sets the locale to Frenchintl.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
Use this to substitute keys in a template string with values from the argument data.
null or undefined 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 the options as a cache key.
Reuse the same options objects for best performance.
- Signature
-
substitute (template: string, data: Record<string, any>, options?: SubstituteOptions): string
Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| template | Template string to use for substitution. | | |
| data | Data object to be substituted. | | |
| options | Options for determining how to substitute keys in the template string. | |
- Returns
- string
The formatted string.
Examples
// Format a dateconst 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 numberconst 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" } } }});