Change the basemap language

Learn how to localize basemap place labels using the basemap styles service.

The basemap styles service provides a number of basemap layer styles such as topography, streets, and imagery that you can use in maps. Each style accepts a language parameter, which allows you to localize place labels. There are currently over 30 different languages available.

In this tutorial, you will create a Calcite combobox to switch between different languages to update the Basemap style and app locale.

Prerequisites

Steps

Create a new pen

1. To get started, either complete the Display a map tutorial or use this pen.

Get an access token

You need an access token with the correct privileges to access the location services used in this tutorial.

1. Go to the Create an API key tutorial and create an API key with the following privilege(s):
   
   • Privileges
     • Location services > Basemaps
2. In CodePen, set esriConfig.apiKey to your API key..
   Use dark colors for code blocks

   1
   2
   3
   4
   esriConfig.apiKey = "YOUR_ACCESS_TOKEN";
   const map = new Map({
     basemap: "arcgis/topographic" // basemap styles service
   });

To learn about other ways to get an access token, go to Types of authentication.

Add modules

The intl module provides utilities for updating the locale of your application. For more information, see the Localization guide page.

1. In the require statement, add the intl module.
   More info

   The ArcGIS Maps SDK for JavaScript is available as AMD modules and ES modules, but this tutorial is based on AMD. The AMD require function uses references to determine which modules will be loaded – for example, you can specify "esri/Map" for loading the Map module. After the modules are loaded, they are passed as parameters (e.g. Map) to the callback function where they can be used in your application. It is important to keep the module references and callback parameters in the same order. To learn more about the API's different modules visit the Overview Guide page.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
           require([
               "esri/config",
               "esri/Map",
               "esri/views/MapView",
   
               "esri/intl"
   
           ], (esriConfig, Map, MapView, intl) => {
   

   Expand

Update the map view

1. Update the center and zoom properties to focus the display on Europe.
   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
               const view = new MapView({
                   map: map,
   
                   center: [13, 46], // Longitude, latitude
                   zoom: 4, // Zoom level
   
                   container: "viewDiv" // Div element
               });
   

   Expand

Set the current language

Set the current language of the basemap and the locale of the application to Spanish (es). Setting the locale of the application will update the widgets to use the given language and formatting. For instance, when the locale is set to Spanish, the zoom widget tooltip will say Acercar instead of Zoom in.

1. Set the app's locale to Spanish (es) using intl.setLocale().

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
               intl.setLocale("es");
   
   

   Expand

2. Set the basemap from a style to the arcgis/outdoor basemap style with the language property set to es. This will display the basemap's place labels in Spanish.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
               intl.setLocale("es");
   
               const map = new Map({
   
                   basemap: {
                       style: {
                           id: "arcgis/outdoor",
                           language: "es"
                       }
                   }
   
               });
   

   Expand

Create a basemap language function

Create a function that accepts a language code and updates the basemap style formatted with that language.

1. Define a new function updateBasemapLanguage that accepts a language code.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
               const updateBasemapLanguage = (languageCode) => {
   
               };
   

   Expand

2. Use the languageCode variable to update the application's locale and the language of the basemap style.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
               const updateBasemapLanguage = (languageCode) => {
   
                   intl.setLocale(languageCode);
                   view.map.basemap = {
                       style: {
                           id: "arcgis/outdoor",
                           language: languageCode
                       }
                   }
   
               };
   

   Expand

Add a language Calcite combobox

Use the Calcite combobox component to create a dropdown to change the language of the basemap.

1. Add references to Calcite components in the <head> tag.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
       <script type="module" src="https://js.arcgis.com/calcite-components/2.11.1/calcite.esm.js"></script>
       <link rel="stylesheet" type="text/css" href="https://js.arcgis.com/calcite-components/2.11.1/calcite.css" />
   

   Expand

2. Create a HTML div element with a calcite label and combobox component for all the languages.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
       <div id="basemapLanguage" class="esri-widget">
           <calcite-label>Basemap language</calcite-label>
           <calcite-combobox id="languageCombobox" selection-mode="single" clear-disabled="true">
               <calcite-combobox-item value="global" text-label="Global"></calcite-combobox-item>
               <calcite-combobox-item value="local" text-label="Local"></calcite-combobox-item>
               <calcite-combobox-item value="ar" text-label="Arabic"></calcite-combobox-item>
               <calcite-combobox-item value="bs" text-label="Bosnian"></calcite-combobox-item>
               <calcite-combobox-item value="ca" text-label="Catalan"></calcite-combobox-item>
               <calcite-combobox-item value="zh-HK" text-label="Chinese (Hong Kong)"></calcite-combobox-item>
               <calcite-combobox-item value="zh-CN" text-label="Chinese (Simplified)"></calcite-combobox-item>
               <calcite-combobox-item value="zh-TW" text-label="Chinese (Taiwan)"></calcite-combobox-item>
               <calcite-combobox-item value="hr" text-label="Croatian"></calcite-combobox-item>
               <calcite-combobox-item value="cs" text-label="Czech"></calcite-combobox-item>
               <calcite-combobox-item value="da" text-label="Danish"></calcite-combobox-item>
               <calcite-combobox-item value="nl" text-label="Dutch"></calcite-combobox-item>
               <calcite-combobox-item value="en" text-label="English"></calcite-combobox-item>
               <calcite-combobox-item value="et" text-label="Estonian"></calcite-combobox-item>
               <calcite-combobox-item value="fi" text-label="Finnish"></calcite-combobox-item>
               <calcite-combobox-item value="fr" text-label="French"></calcite-combobox-item>
               <calcite-combobox-item value="de" text-label="German"></calcite-combobox-item>
               <calcite-combobox-item value="el" text-label="Greek"></calcite-combobox-item>
               <calcite-combobox-item value="he" text-label="Hebrew"></calcite-combobox-item>
               <calcite-combobox-item value="hu" text-label="Hungarian"></calcite-combobox-item>
               <calcite-combobox-item value="id" text-label="Indonesian"></calcite-combobox-item>
               <calcite-combobox-item value="it" text-label="Italian"></calcite-combobox-item>
               <calcite-combobox-item value="ja" text-label="Japanese"></calcite-combobox-item>
               <calcite-combobox-item value="ko" text-label="Korean"></calcite-combobox-item>
               <calcite-combobox-item value="lv" text-label="Latvian"></calcite-combobox-item>
               <calcite-combobox-item value="lt" text-label="Lithuanian"></calcite-combobox-item>
               <calcite-combobox-item value="nb" text-label="Norwegian"></calcite-combobox-item>
               <calcite-combobox-item value="pl" text-label="Polish"></calcite-combobox-item>
               <calcite-combobox-item value="pt-BR" text-label="Portuguese (Brazil)"></calcite-combobox-item>
               <calcite-combobox-item value="pt-PT" text-label="Portuguese (Portugal)"></calcite-combobox-item>
               <calcite-combobox-item value="ro" text-label="Romanian"></calcite-combobox-item>
               <calcite-combobox-item value="ru" text-label="Russian"></calcite-combobox-item>
               <calcite-combobox-item value="sr" text-label="Serbian"></calcite-combobox-item>
               <calcite-combobox-item value="es" text-label="Spanish" selected></calcite-combobox-item>
               <calcite-combobox-item value="sv" text-label="Swedish"></calcite-combobox-item>
               <calcite-combobox-item value="th" text-label="Thai"></calcite-combobox-item>
               <calcite-combobox-item value="tr" text-label="Turkish"></calcite-combobox-item>
               <calcite-combobox-item value="uk" text-label="Ukrainian"></calcite-combobox-item>
               <calcite-combobox-item value="vi" text-label="Vietnamese"></calcite-combobox-item>
           </calcite-combobox>
       </div>
   

   Expand

3. Add the basemapLanguage div to the view UI.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
               const basemapLanguage = document.getElementById("basemapLanguage");
               // add to the view UI
               view.ui.add(basemapLanguage, "top-right");
   
   

   Expand

4. Apply some CSS styling to the basemapLanguage div within the <style> tags.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
           #basemapLanguage {
               width: 200px;
               padding: 10px;
           }
   
   

   Expand

5. Add an event listener to watch for changes on the combobox. When the combobox value has changed, call the updateBasemapLanguage function to update the basemap language and app locale.

   Expand

   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   21
   22
   23
   24
   25
   26
   27
   28
   29
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
   118
   119
   120
   121
   122
   123
   124
   125
   126
   127
   128
   129
   130
   131
   132
   133
   134
   135
   136
   137
   138
   139
   140
   141
   142
   143
   144
   145
   146
               const basemapLanguage = document.getElementById("basemapLanguage");
               // add to the view UI
               view.ui.add(basemapLanguage, "top-right");
   
               const languageCombobox = document.getElementById("languageCombobox");
               // when the combobox value changes, update the basemap language
               languageCombobox.addEventListener("calciteComboboxChange", (event) => {
                   updateBasemapLanguage(event.target.value);
               });
   

   Expand

Run the App

In CodePen, run your code to display the map.

You should be able to use the calcite combobox to update the basemap language and app locale.

What's Next?

Learn how to use additional API features and ArcGIS services in these tutorials:

• Add a vector tile layer
• Add a feature layer
• Display a custom basemap style