Skip To ContentArcGIS for DevelopersSign In Dashboard
require(["esri/intl"], function(intl) { /* code goes here */ });
Object: esri/intl
Since: ArcGIS API for JavaScript 4.12

Overview

This module provides 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.

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

NameReturn TypeSummaryObject
Intl.DateTimeFormatOptions

Converts a web map date format string to an Intl.DateTimeFormat options object.

more details
more detailsintl
Intl.NumberFormatOptions

Converts a NumberFormat to an Intl.NumberFormatOptions object.

more details
more detailsintl
MessageBundleLoader

Creates a message bundle loader specialized in loading translation files as JSON files.

more details
more detailsintl
Promise<Object>

Loads a localized message bundle used with the current API locale.

more details
more detailsintl
String

Formats a Date or Number value to a string in the current locale.

more details
more detailsintl
String

Formats a Number value to a string in the current locale.

more details
more detailsintl
String

Returns the current locale used by the API.

more details
more detailsintl
String|null

Returns one of the known message bundle locale for an input locale.

more details
more detailsintl
Handle

Registers a callback that gets notified when the locale changes.

more details
more detailsintl
Boolean

Provides right-to-left preference for input locale.

more details
more detailsintl

Registers a message loader to load specified message bundles needed for translating strings.

more details
more detailsintl

Sets the locale used by the API.

more details
more detailsintl
String

Use this to substitute keys in a template string with values from the argument data.

more details
more detailsintl

Method Details

convertDateFormatToIntlOptions(format){Intl.DateTimeFormatOptions}

Converts a web map date format string to an Intl.DateTimeFormat options object.

Parameter:
format String
optional

A 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"

Returns:
TypeDescription
Intl.DateTimeFormatOptionsThe date format options derived from the format string as defined in the web map specification.
See also:
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(); // 1560375191812
const formattedDate = intl.formatDate(now, dateFormatIntlOptions);

console.log(formattedDate); // expected output for US English locale: "6/12/2019, 2:33 PM"
convertNumberFormatToIntlOptions(format){Intl.NumberFormatOptions}

Converts a NumberFormat to an Intl.NumberFormatOptions object.

Parameter:
optional

The NumberFormat to convert.

Returns:
TypeDescription
Intl.NumberFormatOptionsThe Intl number format options.
See also:
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(params){MessageBundleLoader}
Since: ArcGIS API 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 API for JavaScript.

Parameters:
Specification:
params Object

The configuration of the loader.

Specification:
pattern String|RegExp

Used to check if the loader should be used to load a candidate's message bundle.

base String

Used to calculate the relative path of the file to load.

location String|URL|Function

The location of the translation files. It can be either a string or URL pointing to the folder where the files are located, or a function called with a specified path. The function should return the final path.

Returns:
TypeDescription
MessageBundleLoaderloader - A message bundle loader.
See also:
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(bundleId){Promise<Object>}
Since: ArcGIS API 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 API 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.

Parameter:
bundleId String

The identifier of the message bundle, passed to the loader registered with registerMessageBundleLoader.

Returns:
TypeDescription
Promise<Object>When resolved, an object containing the localized message strings.
See also:
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(value, formatOptions){String}

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.

Parameters:
value Date|Number

The Date object, or the number of milliseconds elapsed since January 1, 1970 00:00:00 UTC, to be formatted.

optional

Date format options.

Returns:
TypeDescription
StringFormatted string for the input Date value.
See also:
Example:
const 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"
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 their options as a cache key. Reuse the same options objects for best performance.

Parameters:
value Number

Number to be formatted.

optional

Number format options.

Returns:
TypeDescription
StringFormatted 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%
getLocale(){String}
Since: ArcGIS API 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:

  1. What is initialized using the global esriConfig variable, which also initializes the esri/config module.
  2. What is set in dojoConfig.locale for backward compatibility
  3. 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 setLocale() method. A callback can be invoked to notify when the locale changes by using onLocaleChange().

The locale defaults to en (English).

Returns:
TypeDescription
StringThe current locale string.
See also:
normalizeMessageBundleLocale(locale){String|null}
Since: ArcGIS API 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, 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, and zh-TW.

Parameter:
locale

Any locale string.

Returns:
TypeDescription
String | nullThe 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(callback){Handle}
Since: ArcGIS API 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.

Parameter:

A function that is fired when the locale changes. It is called with the newly-set locale after executing the setLocale() method.

Returns:
TypeDescription
HandleReturns 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(locale){Boolean}
Since: ArcGIS API for JavaScript 4.16

Provides right-to-left preference for input locale.

Parameter:
locale String
optional

The locale string to obtain the right-to-left information. The current locale is used by default.

Returns:
TypeDescription
BooleanReturns true if right-to-left is preferred for the input locale. For example, this returns true if the locale is ar or he.
registerMessageBundleLoader(loader)
Since: ArcGIS API 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.

  1. Define your own loader by implementing a MessageBundleLoader, or
  2. Use the loader the API implements via the convenience method, createJSONLoader.

Examples for both are provided below.

Parameter:

A message bundle loader.

See also:
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 fetchBundle(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");
setLocale(locale)
Since: ArcGIS API for JavaScript 4.16

Sets the locale used by the API. This is the preferred method for setting the API locale.

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

Then it is possible to set the locale to en-US or en-GB. The widgets are translated using en messages, while dates and numbers use their corresponding formatting.

Parameter:
locale String

The new Unicode locale identifier string, similar to the Intl APIs. If this is undefined, the locale is reset to its default value described in getLocale().

See also:
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(template, data, options){String}

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.

Parameters:
template String

Template string to use for substitution.

data Object

Data object to be substituted.

optional

Options for determining how to substitute keys in the template string.

Returns:
TypeDescription
StringThe formatted string.
See also:
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(bundleId, locale){Promise<Object>}
Since: ArcGIS API for JavaScript 4.18

The function responsible of fetching a message bundle resource for a particular locale.

Parameters:
bundleId String

The identifier of the bundle to localize.

locale String

The locale in which to load the bundle.

Returns:
TypeDescription
Promise<Object>Resolves to an object containing the localized message strings.
See also:
LocaleChangeCallback(newLocale)

The onLocaleChange() method registers this callback when the locale changes.

Parameter:
newLocale String

A string containing a reference to the changed locale.

MessageBundleLoader
Since: ArcGIS API for JavaScript 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:
pattern String|RegExp

Used to check if the loader should be used to load a candidate message bundle.

fetchMessageBundle FetchMessageBundle

Called to load the message bundle if the pattern matches the bundle identifier.

See also:
Example:
const 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");
NumberFormat

The Web map definition for formatting numbers. This provides more detail about how a number value should be displayed.

Properties:
digitSeparator Boolean
optional

Indicates if the number should be formatted with a thousands separator. This is equivalent to useGrouping.

places Number
optional

Specifies 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 and maximumFractionDigits.

See also:
SubstituteDateTimeFormatOptions

The formatting options for date values.

Properties:
type String

The type of this format. The value is always "date".

The value is always "date".

The date format options for the Intl.DateTimeFormat object.

See also:
Example:
const dateFormat = {
  type: "date",
  intlOptions: {
    year: "numeric",
    month: "numeric",
    day: "numeric",
    hour: "numeric",
    minute: "numeric"
  }
};

var data = {
  time: Date.now()
};

intl.substitute("Date: {time}", data, {
  format: {
    time: dateFormat
  }
});
SubstituteNumberFormatOptions

The formatting options for numeric values.

Properties:
type String

The type of this format. The value is always "number".

The value is always "number".

The 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
  }
});

var 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"
  }
};

var data = {
  amount: 14
};

intl.substitute("Amount: {amount}", data, {
  amount: currencyFormat
});
// Formats a number as a percentage.
const percentFormat = {
  type: "number",
  intlOptions: {
    style: "percent"
  }
};

var data = {
  growth: 0.5
};

intl.substitute("Growth: {growth}", data, {
  growth: percentFormat
});
SubstituteOptions

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 or substitute()
  • a named formatter than can be referenced in the template string.

In the following example, the time property from data 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:

API Reference search results

NameTypeModule
Loading...