Localization

Support for localization in the ArcGIS Maps SDK for JavaScript includes translated UI strings, date and number formatting, right-to-left (RTL) bidirectional content, different sets of basemaps, localized directions, and the label language of basemaps from the basemap styles service.

How does localization work with the ArcGIS Maps SDK for JavaScript?

If you don't specify the locale, the browser's default locale will be used.

To specify the locale, set the locale with the lang attribute on the root html element.

Use dark colors for code blocksCopy
<html lang="sv"></html>

You can specify your application's locale at runtime using the intl.setLocale() method. This can be useful if you want to use the preferred language of an ArcGIS Online organization, logged in user, or have an application where users can switch languages.

Use dark colors for code blocksCopy
// Sets the locale to French
intl.setLocale("fr");

// Sets the locale to UK English.
// Dates are formatted in day/month/year order.
// Strings are in default "en", which is American English.
intl.setLocale("en-GB");

Note that setLocale() can be called at anytime by an application. It is recommended to call setLocale as soon as possible within the application. Widgets and components will change to the new locale automatically. This behavior is considered experimental since the SDK is not designed around switching locales at runtime. For example, labels on feature layers, or numbers and dates formatted by Arcade expressions, will not update.

For backward compatibility, the locale can still be initialized using a global object similar to how it was handled prior to version 4.16.

Use dark colors for code blocksCopy
<script>
  // Set the locale before the SDK loads
  esriConfig = {
    locale: "fr-FR",
  };
</script>

Prior to version 4.16, setting the locale in a Dojo config object was the preferred way. This still works for backwards compatibility but is not recommended going forward.

Please refer to the Intl module - API reference documentation for additional information on SDK localization utilities.

Support for right-to-left (RTL)

The ArcGIS Maps SDK for JavaScript provides bidirectional support. To enable right-to-left (RTL), set the dir attribute in the <html> or <body> tag to rtl.

Use dark colors for code blocksCopy
<html dir="rtl"></html>

This will impact many aspects of the SDK, for example:

Content in widgets and components.
Themes.
Positions specified with leading/trailing options of the UI add/empty/move methods. For left-to-right (LTR), "leading" is left and "trailing" is right. For right-to-left (RTL), "leading" is right and "trailing" is left.

Alternatively, the right-to-left dir attribute may be applied individually on a container. Then, only the widget's content is affected:

Use dark colors for code blocksCopy
<body>
  <div id="viewDiv">
    <div id="elevationWidgetDiv" dir="rtl"></div>
  </div>
</body>

Locale support

The ArcGIS Maps SDK for JavaScript has translation support for the locales listed below. In addition to these languages, date and number formatting is supported for any sub-locales.

Arabic (ar)
Bosnian (bs) - Added in version 4.2
Bulgarian (bg) - Added in version 4.22
Catalan (ca) - Added in version 4.8
Chinese (zh), same as Simplified Chinese - Added in version 4.32
Simplified Chinese (zh-cn)
Traditional Chinese (Hong Kong) (zh-hk)
Traditional Chinese (Taiwan) (zh-tw)
Croatian (hr) - Added in version 4.1
Czech (cs)
Danish (da)
Dutch (nl)
English (en)
Estonian (et)
Finnish (fi)
French (fr)
German (de)
Greek (el)
Hebrew (he)
Hungarian (hu) - Added in version 4.8
Indonesian (id) - Added in version 4.2
Italian (it)
Japanese (ja)
Korean (ko)
Latvian (lv)
Lithuanian (lt)
Norwegian (no) ¹
Polish (pl)
Portuguese (pt), same as Portuguese (Brazil) - Added in version 4.32
Portuguese (Brazil) (pt-br)
Portuguese (Portugal) (pt-pt)
Romanian (ro)
Russian (ru)
Serbian (sr) - Added in version 4.1
Slovak (sk) - Added in version 4.18
Slovenian (sl) - Added in version 4.6
Spanish (es)
Swedish (sv)
Thai (th)
Turkish (tr)
Ukrainian (uk) - Added in version 4.11
Vietnamese (vi)

¹ The locale string for Norwegian was changed at 4.32 from nb to no. The old nb code is being aliased so will still work for now, but is deprecated.

Locale fallback

Sub-locales not listed above will get translation strings from their macrolanguages. For example, French Canadian ("fr-CA") will use French ("fr") translation strings, and Mexican Spanish ("es-MX") uses Spanish ("es") translation strings. If there is no supported macrolanguage, the translation strings will fall back to English. Date and number formatting will still use the more specific sub-locale.

Note that the macrolanguage for Nynorsk ("nn") is a special case in CLDR and browsers. Nynorsk is treated like "no-nn", and its macrolanguage is Norwegian ("no").

Change specific strings

Note that you can use messageOverrides on most components to change specific translated strings. This will override any localization. To find out which message strings can be overwritten for a specific component, look at the documentation e.g., arcgis-home.messageOverrides or arcgis-print.messageOverrides.

Use dark colors for code blocksCopy
// change the Home button tooltip ("Default map view" for English)
document.querySelector("arcgis-home").messageOverrides = { title: "my area of interest" };

The messageOverrides in Calcite Components work the same way.