Display maps in other languages and worldviews
Developers can configure their maps to display labels and geographic features appropriate for specific audiences. These settings can be based upon device locale settings, current location, user preferences, hard-coded values, or any other mechanism the developer wishes to use.
No additional configuration is required to display maps in the language and worldview of the user's browser or device locale.
If you want to manually specify the language on your map, the code snippets in the next section show you how. You will learn how to configure maps to use a specific language and worldview as well as change the language and worldview dynamically after the map has loaded (for example, allowing the user to switch languages using a control).
Language selection prioritizes locally-appropriate feature names and alphabets. When data for the selected feature or language is not available, an appropriate fallback will be prioritized. For a list of supported languages, see the list of available languages.
Developers can also configure the worldview of the map. A worldview identifies geographic features whose characteristics are defined differently by audiences belonging to various regional, cultural, or political groups. This most commonly affects how and whether disputed boundaries and labels are displayed. For a list of supported worldviews, see the list of available worldviews.
Maps that use either of these features are referred to as internationalized maps.
Setting the language and worldview of a Mapbox map
By default Mapbox maps will use the browser or device locale to determine the language and worldview of map labels and features. You can override this behavior to specify a particular language or worldview when initializing a map, or you can change the language and worldview dynamically after the map has loaded. The method for doing so varies by platform.
Setting the language and worldview in web maps (Mapbox GL JS)
These instructions are for GL JS v2.11.0 or later.
When instantiating a map, you can set the language and worldview options on the Map object to specify the language and worldview for map labels and features.
// Initialize a map with Chinese labels and features for a mainland Chinese audience
const map = new mapboxgl.Map({
container: 'map',
style: 'mapbox://styles/mapbox/standard',
language: 'zh-Hans',
worldview: 'CN'
});
After a map has been initialized, you can change the language and worldview dynamically using setLanguage() and setWorldview() on the Map instance.
// Change language to English and worldview to US
map.setLanguage('en');
map.setWorldview('US');
Setting the language and worldview in mobile maps (iOS, Android, and Flutter)
These instructions are for Maps SDK v10.5.0 or later.
In Mapbox mobile maps, the same set of methods are called to set the language and worldview before map initialization and after the map has loaded. The method for doing so varies by platform, but the keys and values used to set the language and worldview are the same across platforms.
Maps SDK for Android
To set the language and worldview in an Android map, create a SettingsService instance and call set() with the appropriate keys and values. You can call this before or after map initialization, and call it multiple times to change the language and worldview dynamically.
// Create a settings service instance as PERSISTENT, the language set will be persisted across the application lifecycle.
private val settingsService: SettingsService by lazy {
SettingsServiceFactory.getInstance(
SettingsServiceStorageType.PERSISTENT
)
}
...
// Set the map language and worldview by calling `settingsService.set()` with the appropriate keys and values.
settingsService.set(MapboxCommonSettings.LANGUAGE, Value("zh-Hans"))
settingsService.set(MapboxCommonSettings.WORLDVIEW, Value("CN"))
Maps SDK for iOS
To set the language and worldview in an iOS map, create a SettingsService instance and call set() with the appropriate keys and values. You can call this before or after map initialization, and call it multiple times to change the language and worldview dynamically.
// Create a persistent SettingsService instance. Values set via this service are persisted across app lifecycle.
let settingsService = SettingsServiceFactory.getInstance(storageType: .persistent)
...
// Set the map language and worldview by calling `settingsService.set()` with the appropriate keys and values.
_ = settingsService.set(key: MapboxCommonSettings.language, value: "zh-Hans")
_ = settingsService.set(key: MapboxCommonSettings.worldview, value: "CN")
Maps SDK for Flutter
To set the language and worldview, use the MapboxMapsOptions class, which includes setLanguage() and setWorldview() methods. You can call these before or after map initialization, and call them multiple times to change the language and worldview dynamically.
// set the map language and worldview by calling `setLanguage()` and `setWorldview()` with the appropriate values.
MapboxMapsOptions.setLanguage("zh-Hans");
MapboxMapsOptions.setWorldview("CN");
How internationalized maps work
The web or mobile map SDK defines the desired language when the map is initialized, either using the browser/device locale or a manually specified value. Behind the scenes, the SDK requests vector tiles from Mapbox servers that contain labels in the appropriate language and features for the appropriate worldview.
Changing the language or worldview after the map has loaded triggers a new request for tiles in the appropriate language and worldview.
This process — server-side localization — is the default method for internationalizing maps. Vector tiles contain only the requested language and worldview, minimizing data transferred to and stored on the client. Cached and offline vector tiles include only a single language and worldview, so users cannot switch languages while offline.
Client-side localization for Offline mobile maps
To enable switching languages while offline, Mapbox supports client-side localization for mobile maps. With this feature, the client requests tiles with data for all languages and worldviews so that it can configure which language and worldview to display locally. This means that cached and offline data can be used to display maps in any language and worldview, regardless of the language and worldview settings when the tiles were originally requested.
These instructions are for Mapbox Maps SDK v11.8.0 or later.
This feature is available only in the Mapbox Mobile SDKs. Mapbox GL JS does not support this feature.
To enable client-side localization, use the settings service to set com.mapbox.maps.internal.enable_local_i18n to true.
Enable client-side localization for Android
// Create a settings service instance as PERSISTENT, the setting will
// be persisted across the application lifecycle.
private val settingsService: SettingsServiceInterface by lazy {
SettingsServiceFactory.getInstance(
SettingsServiceStorageType.PERSISTENT
)
}
// Enable client-side localization by setting "com.mapbox.maps.internal.enable_local_i18n" to true.
settingsService.set("com.mapbox.maps.internal.enable_local_i18n", Value(true))
...
// Set the map language and worldview by calling `settingsService.set()` as usual. The sdk will change the label language and worldview locally without requesting new tiles from the server.
settingsService.set(MapboxCommonSettings.LANGUAGE, Value("zh-Hans"))
settingsService.set(MapboxCommonSettings.WORLDVIEW, Value("CN"))
Enable client-side localization for iOS
// Create a persistent SettingsService instance. Values set via this service
// are persisted across app lifecycle
let settingsService = SettingsServiceFactory.getInstance(storageType: .persistent)
// Enable client-side localization by setting "com.mapbox.maps.internal.enable_local_i18n" to true.
let result = settingsService.set(key: "com.mapbox.maps.internal.enable_local_i18n", value: true)
// Set the map language and worldview by calling `settingsService.set()` as usual. The SDK will change the label language and worldview locally without requesting new tiles from the server.
settingsService.set(key: MapboxCommonSettings.language, value: "zh-Hans")
settingsService.set(key: MapboxCommonSettings.worldview, value: "CN")
The client now requests tiles with all supported languages and worldviews. You cannot restrict the set of languages or worldviews that are returned. You can manually limit the set of languages and worldviews available to end users by controlling the options in your language and worldview-switching UI controls.
Using custom label layers with Mapbox tilesets
Label layers in Mapbox Standard and Mapbox Classic styles will honor the language and worldview settings that you've applied to the map. If you add a custom layer that uses a Mapbox-maintained tileset (such as streets-v8) as its source, you should set the text-field to name to display the localized label.
"text-field": ["get", "name"]
Available languages
If a translated label isn't found for a feature, we fall back to its local name — the name used natively in the region where the feature is located. For example, if you set the language to Arabic (ar) and zoom into a region in France where we don't have an Arabic translation (e.g., Le Château-d'Oléron), we'll display the French name instead.
| Code | Language |
|---|---|
ar | Arabic |
bg | Bulgarian |
bs | Bosnian |
ca | Catalan |
cs | Czech |
da | Danish |
de | German |
el | Greek |
en | English |
es | Spanish |
et | Estonian |
fa | Farsi |
fi | Finnish |
fr | French |
he | Hebrew |
hr | Croatian |
hu | Hungarian |
id | Indonesian |
it | Italian |
ja | Japanese |
ka | Georgian |
ko | Korean |
lv | Latvian |
ms | Malay |
nb | Norwegian Bokmål |
nl | Dutch |
no | Norwegian |
pl | Polish |
pt | Portuguese |
ro | Romanian |
ru | Russian |
sk | Slovak |
sl | Slovenian |
sq | Albanian |
sr | Serbian |
sv | Swedish |
th | Thai |
tl | Tagalog |
tr | Turkish |
uk | Ukrainian |
vi | Vietnamese |
zh-Hans | Simplified Chinese |
zh-Hant | Traditional Chinese |
Available worldviews
| Value | Description |
|---|---|
US (default) | Features for an American audience. Choose this option if you don't require an explicit worldview from our supported list. |
AR | Features for an Argentinian audience |
CL | Features for a Chilean audience |
CN | Features for a mainland Chinese audience |
IN | Features for an Indian audience |
JP | Features for a Japanese audience |
MA | Features for a Moroccan audience |
RS | Features for a Serbian audience. |
RU | Features for a Russian audience |
TR | Features for a Turkish audience |
VN | Features for a Vietnamese audience |
all | Features common for all worldviews |