@arcgis/core

/** * * [Overview](https://developers.arcgis.com/javascript/latest/references/core/intl/#overview) * * [Setting the locale](https://developers.arcgis.com/javascript/latest/references/core/intl/#locale) * * [Number formatting](https://developers.arcgis.com/javascript/latest/references/core/intl/#number) * * [Date and time formatting](https://developers.arcgis.com/javascript/latest/references/core/intl/#datetime) * * [Tips and tricks](https://developers.arcgis.com/javascript/latest/references/core/intl/#tips) * * * ## 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()](https://developers.arcgis.com/javascript/latest/references/core/intl/#formatDate), [formatNumber()](https://developers.arcgis.com/javascript/latest/references/core/intl/#formatNumber), and [substitute()](https://developers.arcgis.com/javascript/latest/references/core/intl/#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](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) 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()](https://developers.arcgis.com/javascript/latest/references/core/intl/#setLocale) method. * This locale will determine: * 1. the number and date formatting used throughout the API, * 2. the translation of components, and * 3. the place label language of basemaps (if using the [basemap styles service](https://developers.arcgis.com/javascript/latest/references/core/support/BasemapStyle/)). * * See the [localization](https://developers.arcgis.com/javascript/latest/localization/) guide page for more information. * * * ## Number formatting * * You can format numbers with [formatNumber()](https://developers.arcgis.com/javascript/latest/references/core/intl/#formatNumber) in three different styles: `decimal`, `percent`, or `currency`. * * ```js * 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()](https://developers.arcgis.com/javascript/latest/references/core/intl/#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. * * ```js * 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()](https://developers.arcgis.com/javascript/latest/references/core/intl/#formatDate), [formatNumber()](https://developers.arcgis.com/javascript/latest/references/core/intl/#formatNumber), and [substitute()](https://developers.arcgis.com/javascript/latest/references/core/intl/#substitute) functions are light wrappers * around the Intl APIs that cache the created [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) * and [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat) formatter objects for a set of `options`. * Consider reusing the same `options` objects to avoid having to recreate these objects. * * ```js * const currencyFormatter = { * style: "currency", * currency: "EUR", * currencyDisplay: "symbol" * }; * * function formatCurrency(amount) { * return formatNumber(amount, currencyFormatter); * } * ``` * * @since 4.12 * @see [Intl on MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) * @see [Intl.DateTimeFormat on MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat) * @see [Intl.NumberFormat on MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat) * @see [FieldInfoFormat](https://developers.arcgis.com/javascript/latest/references/core/popup/support/FieldInfoFormat/) * @see [Sample - Load portal items via drag and drop](https://developers.arcgis.com/javascript/latest/sample-code/portalitem-dragndrop/) */ import type DateTimeFieldFormat from "./layers/support/DateTimeFieldFormat.js"; import type NumberFieldFormat from "./layers/support/NumberFieldFormat.js"; import type { ResourceHandle } from "./core/Handles.js"; import type { DateFormat, DateTimeFormatOptions, TimeFormat } from "./intl/date.js"; import type { LocaleChangeCallback } from "./intl/locale.js"; import type { MessageBundle, MessageBundleLoader, MessageBundleLocale } from "./intl/messages.js"; import type { NumberFormat } from "./intl/number.js"; import type { SubstituteOptions } from "./intl/substitute.js"; import type { JSONLoaderOptions } from "./intl/t9n.js"; /** * Converts a [web map date format string](https://developers.arcgis.com/web-map-specification/objects/format/) to an [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat#Parameters) options object. * * @param format - A web map date format string to convert. * @returns The date format options derived from the format string as defined in the web map specification. * @see [FieldInfoFormat.dateFormat](https://developers.arcgis.com/javascript/latest/references/core/popup/support/FieldInfoFormat/#dateFormat) * @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" */ export function convertDateFormatToIntlOptions(format: DateFormat | TimeFormat): Intl.DateTimeFormatOptions; /** * Converts a [DateTimeFieldFormat](https://developers.arcgis.com/javascript/latest/references/core/layers/support/DateTimeFieldFormat/) to an [Intl.DateTimeFormatOptions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat#Parameters) options object. * * @param format - The [DateTimeFieldFormat](https://developers.arcgis.com/javascript/latest/references/core/layers/support/DateTimeFieldFormat/) to convert. * @returns The [Intl date format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat#Parameters) options. * @since 4.34 * @see [FieldInfo.fieldFormat](https://developers.arcgis.com/javascript/latest/references/core/popup/FieldInfo/#fieldFormat) * @example * const dateTimeFieldFormat = new DateTimeFieldFormat({ * dateStyle: "short", * timeStyle: "short", * hour12: "always" * }); * const dateTimeFieldFormatIntlOptions = intl.convertDateTimeFieldFormatToIntlOptions(dateTimeFieldFormat); * const now = Date.now(); // 1759292167543 * const formattedDateTime = intl.formatDate(now, dateTimeFieldFormatIntlOptions); * console.log(formattedDateTime); // expected output for US English locale: "9/30/25, 9:16 PM" */ export function convertDateTimeFieldFormatToIntlOptions(format: DateTimeFieldFormat): Intl.DateTimeFormatOptions; /** * Converts a [NumberFieldFormat](https://developers.arcgis.com/javascript/latest/references/core/layers/support/NumberFieldFormat/) to an [Intl.NumberFormatOptions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat#Parameters) options object. * * @param format - The [NumberFieldFormat](https://developers.arcgis.com/javascript/latest/references/core/layers/support/NumberFieldFormat/) to convert. * @returns The [Intl number format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat#Parameters) options. * @since 4.34 * @see [FieldInfo.fieldFormat](https://developers.arcgis.com/javascript/latest/references/core/popup/FieldInfo/#fieldFormat) * @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 */ export function convertNumberFieldFormatToIntlOptions(format: NumberFieldFormat): Intl.NumberFormatOptions; /** * Converts a [NumberFormat](https://developers.arcgis.com/javascript/latest/references/core/intl/number/#NumberFormat) to an [Intl.NumberFormatOptions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat#Parameters) object. * * @param format - The [NumberFormat](https://developers.arcgis.com/javascript/latest/references/core/intl/number/#NumberFormat) to convert. * @returns The [Intl number format](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/NumberFormat#Parameters) options. * @see [FieldInfoFormat](https://developers.arcgis.com/javascript/latest/references/core/popup/support/FieldInfoFormat/) * @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 */ export function convertNumberFormatToIntlOptions(format?: NumberFormat): Intl.NumberFormatOptions; /** * 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. * * @param params - The configuration of the loader. * @returns loader - A message bundle loader. * @since 4.18 * @see [fetchMessageBundle()](https://developers.arcgis.com/javascript/latest/references/core/intl/#fetchMessageBundle) * @see [registerMessageBundleLoader()](https://developers.arcgis.com/javascript/latest/references/core/intl/#registerMessageBundleLoader) * @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`). */ export function createJSONLoader(params: JSONLoaderOptions): MessageBundle; /** * 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](https://developers.arcgis.com/javascript/latest/references/core/widgets/Widget/) needs to utilize a message bundle, it should do so via the * [@messageBundle](https://developers.arcgis.com/javascript/latest/references/core/widgets/support/widget/#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](https://developers.arcgis.com/javascript/latest/references/core/intl/messages/#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](https://developers.arcgis.com/javascript/latest/references/core/widgets/Home/) * widget localized for US English locale. * Below that is a bundle translated for France's French locale for the same widget's strings. * * @param bundleId - The identifier of the message bundle, passed to the loader registered with [registerMessageBundleLoader()](https://developers.arcgis.com/javascript/latest/references/core/intl/#registerMessageBundleLoader). * @returns When resolved, an object containing the localized message strings. * @since 4.18 * @see [registerMessageBundleLoader()](https://developers.arcgis.com/javascript/latest/references/core/intl/#registerMessageBundleLoader) * @see [@messageBundle](https://developers.arcgis.com/javascript/latest/references/core/widgets/support/widget/#messageBundle) * @example * // This snippet shows the JSON message bundle used for the Home widget in English * { * "widgetLabel": "Home", * "button": "Home", * "title": "Default map view" * } * @example * // This snippet shows the same translation strings in the French locale * { * "widgetLabel": "Accueil", * "button": "Accueil", * "title": "Vue cartographique par défaut" * } * @example * // 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"); */ export function fetchMessageBundle(bundleId: string): Promise<MessageBundle>; /** * Formats a `Date` or `Number` value to a string in the current locale. * * > [!WARNING] * > * > Internally `formatDate` creates [Intl formatter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) instances for the current locale. * > The formatters are cached using their `options` as a cache key. * > Reuse the same `options` objects for best performance. * * @param value - The [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object, or the number of milliseconds elapsed since January 1, 1970 00:00:00 UTC, to be formatted. * @param options - Date format options. * @returns Formatted string for the input Date value. * @see [FieldInfoFormat.dateFormat](https://developers.arcgis.com/javascript/latest/references/core/popup/support/FieldInfoFormat/#dateFormat) * @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" */ export function formatDate(value: number | Date | undefined, options?: DateTimeFormatOptions): string; /** * Formats a `date-only` field value to a string in the current locale. * * > [!WARNING] * > * > Internally `formatDateOnly` creates [Intl formatter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) instances for the current locale. * > The formatters are cached using their `options` as a cache key. * > Reuse the same `options` objects for best performance. * * @param value - The `date-only` field value. * @param options - Date format options. * @returns Formatted string for the input `date-only` value. * @since 4.28 * @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 */ export function formatDateOnly(value: string, options?: Intl.DateTimeFormatOptions): string; /** * Formats a `Number` value to a string in the current locale. * * > [!WARNING] * > * > Internally `formatNumber` creates [Intl formatter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) instances for the current locale. * > The formatters are cached using their `options` as a cache key. * > Reuse the same `options` objects for best performance. * * @param value - Number to be formatted. * @param options - Number format options. * @returns Formatted string for the input Number. * @example * // 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 * @example * // 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 * @example * // 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% */ export function formatNumber(value: number, options?: Intl.NumberFormatOptions): string; /** * Formats a `time-only` field value to a string in the current locale. * * > [!WARNING] * > * > Internally `formatTimeOnly` creates [Intl formatter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) instances for the current locale. * > The formatters are cached using their `options` as a cache key. * > Reuse the same `options` objects for best performance. * * @param value - The `time-only` field value. * @param options - Time format options. * @returns Formatted string for the input `time-only` value. * @since 4.28 * @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 */ export function formatTimeOnly(value: string, options?: Intl.DateTimeFormatOptions): string; /** * Formats a `timestamp-offset` field value to a string in the current locale. * * > [!WARNING] * > * > Internally `formatTimestamp` creates [Intl formatter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) instances for the current locale. * > The formatters are cached using their `options` as a cache key. * > Reuse the same `options` objects for best performance. * * @param value - The `timestamp-offset` field value. * @param options - Timestamp format options. * @returns Formatted string for the input `timestamp-offset` value. * @since 4.28 * @example * console.log(intl.formatDateOnly("1959-10-13")); // output - 10/13/1959 * console.log(intl.formatDateOnly("1959-10-13", intl.convertDateFormatToIntlOptions("long-date")); */ export function formatTimestamp(value: string, options?: DateTimeFormatOptions): string; /** * 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. * 1. The [`lang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) defined on the root `html` element. * 1. What is set [`navigator.language`](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorLanguage/language), the locale defined by the web browser's user's preferences. * * The preferred way of setting a locale is via the [`lang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) on the root `html` element. * A callback can be invoked to notify when the locale changes by using [onLocaleChange()](https://developers.arcgis.com/javascript/latest/references/core/intl/#onLocaleChange). * * @returns The current locale string. * @since 4.16 * @see [NavigatorLanguage on MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorLanguage) * @see [setLocale()](https://developers.arcgis.com/javascript/latest/references/core/intl/#setLocale) * @see [onLocaleChange()](https://developers.arcgis.com/javascript/latest/references/core/intl/#onLocaleChange) */ export function getLocale(): string; /** * This function returns the language code associated with the current locale. * * @returns The language code of the locale (if defined). * @since 4.34 * @see [W3C | Language tags in HTML and XML](https://www.w3.org/International/articles/language-tags/) * @see [Wikipedia | IETF language tag](https://en.wikipedia.org/wiki/IETF_language_tag) * @example console.log(intl.getLocaleLanguage()); // "ar" */ export function getLocaleLanguage(): string | null | undefined; /** * 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`. * * @param locale - Any locale string. * @returns The normalized locale, or null if no known locale was found. * @since 4.18 * @example * // For example: `en-US` * let locale = intl.getLocale(); * // locale is now `en` * locale = intl.normalizeMessageBundleLocale(locale); */ export function normalizeMessageBundleLocale(locale: string): null | undefined | MessageBundleLocale; /** * Registers a [callback](https://developers.arcgis.com/javascript/latest/references/core/intl/locale/#LocaleChangeCallback) that gets notified when * the locale changes. This happens when [setLocale()](https://developers.arcgis.com/javascript/latest/references/core/intl/#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. * * @param callback - A function that is fired when the locale changes. * It is called with the newly-set locale after executing the [setLocale()](https://developers.arcgis.com/javascript/latest/references/core/intl/#setLocale) method. * @returns Returns a handler with a `remove()` method * that can be called to remove the callback and stop listening for locale changes. * @since 4.16 * @see [getLocale()](https://developers.arcgis.com/javascript/latest/references/core/intl/#getLocale) * @see [setLocale()](https://developers.arcgis.com/javascript/latest/references/core/intl/#setLocale) * @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"); * }); */ export function onLocaleChange(callback: LocaleChangeCallback): ResourceHandle; /** * Provides right-to-left preference for input locale. * * @param locale - The locale string to obtain the right-to-left information. * The current locale is used by default. * @returns Returns `true` if right-to-left is preferred for the input `locale`. * For example, this returns `true` if the locale is `ar` or `he`. * @since 4.16 */ export function prefersRTL(locale?: string): boolean; /** * 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](https://developers.arcgis.com/javascript/latest/references/core/intl/messages/#MessageBundleLoader) param. * 1. Define your own loader by implementing a [MessageBundleLoader](https://developers.arcgis.com/javascript/latest/references/core/intl/messages/#MessageBundleLoader), or * 2. Use the loader the API implements via the convenience method, [createJSONLoader()](https://developers.arcgis.com/javascript/latest/references/core/intl/#createJSONLoader). * * Examples for both are provided below. * * @param loader - A message bundle loader. * @returns 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. * @since 4.18 * @see [fetchMessageBundle()](https://developers.arcgis.com/javascript/latest/references/core/intl/#fetchMessageBundle) * @see [registerMessageBundleLoader()](https://developers.arcgis.com/javascript/latest/references/core/intl/#registerMessageBundleLoader) * @see [normalizeMessageBundleLocale()](https://developers.arcgis.com/javascript/latest/references/core/intl/#normalizeMessageBundleLocale) * @see [@messageBundle](https://developers.arcgis.com/javascript/latest/references/core/widgets/support/widget/#messageBundle) * @see [MessageBundleLoader](https://developers.arcgis.com/javascript/latest/references/core/intl/messages/#MessageBundleLoader) * @see [createJSONLoader()](https://developers.arcgis.com/javascript/latest/references/core/intl/#createJSONLoader) * @example * // 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"); * @example * // 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"); */ export function registerMessageBundleLoader(loader: MessageBundleLoader): ResourceHandle; /** * Sets the locale used by the SDK. * Prefer setting the [`lang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) on the root `html` element. * * When the locale changes, the registered callback for [onLocaleChange()](https://developers.arcgis.com/javascript/latest/references/core/intl/#onLocaleChange) is called. * * > [!WARNING] * > * > 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](https://developers.arcgis.com/javascript/latest/references/core/intl/#formatNumber), and [date](https://developers.arcgis.com/javascript/latest/references/core/intl/#formatDate) 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()](https://developers.arcgis.com/javascript/latest/references/core/intl/#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](https://developers.arcgis.com/javascript/latest/localization/#locale-fallback). * * @param locale - 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()](https://developers.arcgis.com/javascript/latest/references/core/intl/#getLocale). * @since 4.16 * @see [More info on locale on MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation) * @see [getLocale()](https://developers.arcgis.com/javascript/latest/references/core/intl/#getLocale) * @see [onLocaleChange()](https://developers.arcgis.com/javascript/latest/references/core/intl/#onLocaleChange) * @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"); */ export function setLocale(locale: string | null | undefined): void; /** * 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. * * > [!WARNING] * > * > Internally `substitute` creates [Intl formatter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) instances for the current locale. * > The formatters are cached using the `options` as a cache key. * > Reuse the same `options` objects for best performance. * * @param template - Template string to use for substitution. * @param data - Data object to be substituted. * @param options - Options for determining how to substitute keys in the template string. * @returns The formatted string. * @see [Sample - Load portal items via drag and drop](https://developers.arcgis.com/javascript/latest/sample-code/portalitem-dragndrop/) * @example * // 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 * } * } * }); * @example * // Format a number * const data = { * increasedValue: 500, * time: Date.UTC(2019), * } * * intl.substitute("Number: {value}", data, { * format: { * value: { * type: "number", * intlOptions: { * maximumFractionDigits: 21 * } * } * } * }); * @example * 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" * } * } * } * }); */ export function substitute(template: string, data: Record<string, any>, options?: SubstituteOptions): string;