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?

To set the locale in an app built with the JavaScript Maps SDK, use the lang attribute on the root html element. This is the recommended approach and also identifies the page language for assistive technologies.

<html lang="sv"></html>

If you don’t specify the locale, the browser’s default locale is used.

To change the locale at runtime, update the lang attribute. For example, this can be useful when using the preferred language of an ArcGIS Online organization or logged in user, or when an application lets users switch languages.

// Sets the locale for both @arcgis/core and components
document.documentElement.lang = "fr";

To localize only part of a page, set lang on a containing element. Components in that container use its locale, while the rest of the page keeps its existing locale.

<div lang="fr">
  <arcgis-map></arcgis-map>
</div>

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

Support for right-to-left (RTL)

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

<html dir="rtl"></html>

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

• Content in components and widgets.
• Component slots specified with start/end. For left-to-right (LTR), “start” is left and “end” is right. For right-to-left (RTL), “start” is right and “end” is left.
• 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 component or widget’s content is affected:

<body>
  <arcgis-scene item-id="9a542f6755274436985617a462ffdf44">
    <arcgis-elevation-profile slot="top-right" dir="rtl"></arcgis-elevation-profile>
  </arcgis-scene>
</body>

Locale support

The JavaScript Maps SDK fully supports string translation as well as date, time, and number formatting for the locales listed below. For other locales, see Locale fallback below.

• 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, time, and number formatting honors the more specific sub-locale as supported by the browser’s Intl object.

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 specific message strings can be overwritten for a component, see the component reference—for example, arcgis-home.messageOverrides or arcgis-print.messageOverrides.

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