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.

Set the API key

To access ArcGIS services, you need an API key.

1. Go to your dashboard to get an API key.
2. In CodePen, set the apiKey to your key, so it can be used to access basemap layer and location services.

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

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.

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) => {

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.5.1/calcite.esm.js"></script>
       <link rel="stylesheet" type="text/css" href="https://js.arcgis.com/calcite-components/2.5.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