Display maps in other languages and worldviews
Maps can be configured to display labels in different languages and render geographic features — such as borders and place names — according to different regional perspectives. Developers have full flexibility in how these settings are applied, whether driven by device locale, the user's current location, explicit user preferences, hard-coded values, or any custom logic that fits their use case.
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.
How internationalized maps work
The web or mobile client defines the desired language when the map is initialized. When the map loads, a network request fetches only localized tiles instead of tiles for all languages. This ensures that the response does not include more data than the end user needs.
One exception applies to mobile developers who need access to all languages and worldviews on the client, for example, to be able to access other languages while offline. These developers can enable a setting that requests tiles containing all languages and worldviews from Mapbox servers, and can then choose the desired language or worldview on the client without re-downloading data.
Enable internationalization
The following sections describe how to enable internationalized maps on web and mobile.
Web
These instructions are for GL JS v2.11.0 or later.
To enable internationalization on web, you should first define language and worldview variables using the codes provided in our available languages and available worldviews.
Then, use setLanguage() or setWorldview() to set the language and worldview for map labels and features. You can also pass auto to infer the end user's preferred locale.
const locale = 'en'; // You can use ‘auto’ to infer the user’s preferred locale
const worldview = 'US';
map.setLanguage(locale);
map.setWorldview(worldview);
Mobile
These instructions are for Maps SDK v10.5.0 or later.
On mobile, you can serve internationalized labels by forcing a specific language or by choosing one dynamically based on the device language.
First, define language and worldview variables using the codes provided in our available languages and available worldviews. Then, use the platform-specific methods to set the language and worldview.
Mapbox Maps SDK for Android
// Localize using device language
// Create a settings service instance as PERSISTENT, the language set will // be persisted across the application lifecycle.
private val settingsService: SettingsServiceInterface by lazy {
SettingsServiceFactory.getInstance(
SettingsServiceStorageType.PERSISTENT
)
}
val locale = context.getResources().getConfiguration().locale
// set language in bcp-47 tag
val language = locale.language().toLanguageTag();
settingsService.set(MapboxCommonSettings.LANGUAGE, Value(language))
// set worldview
val worldView = "US"
settingsService.set(MapboxCommonSettings.WORLDVIEW, Value(worldView))
// Force a locale
val language = Locale.JAPANESE.toLanguageTag();
settingsService.set(MapboxCommonSettings.LANGUAGE, Value(language))
Mapbox Maps SDK for iOS
// Create a persistent SettingsService instance. Values set via this service
// are persisted accross app lifecycle
let settingsService = SettingsServiceFactory.getInstance(storageType: .persistent)
// Configure the preferred map label language.
// - Use a BCP-47 language tag (e.g., "en-US", "fr-CA", "zh-Hans").
let language = Locale.preferredLanguages.first ?? "en-US"
let setLocaleResult = settingsService.set(key: MapboxCommonSettings.language, value: language)
// Optionally, you can inspect `setLocaleResult` to verify success or handle errors.
// For example, log failures for diagnostics in development builds.
// print("Set language result: \(setLocaleResult)")
// Configure the worldview for map data.
let setWorldViewResult = settingsService.set(key: MapboxCommonSettings.worldview, value: "US")
// As above, you may wish to check `setWorldViewResult` for success/failure.
// print("Set worldview result: \(setWorldViewResult)")
Fetch all languages and worldviews
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.
In the previous examples, the Mapbox SDKs request localized tiles that contain only the requested language in the name attribute of supported features. This means that cached and offline data is tied to a particular language and worldview. Switching languages while offline is not possible with this approach.
To resolve this limitation, Mapbox supports fetching all languages and worldviews so that you can configure which language and worldview to display on the client. This feature packs all languages and worldviews into a tile or tilepack. The SDK then selects the appropriate language and worldview locally while parsing the tile. Configure the language and worldview in the SDK as described in the previous section.
To enable this feature, set com.mapbox.maps.internal.enable_local_i18n to true.
Mapbox Maps SDK 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
)
}
settingsService.set("com.mapbox.maps.internal.enable_local_i18n", Value(true))
Mapbox Maps SDK for iOS
// Create a persistent SettingsService instance. Values set via this service
// are persisted accross app lifecycle
let settingsService = SettingsServiceFactory.getInstance(storageType: .persistent)
let result = settingsService.set(key: "com.mapbox.maps.internal.enable_local_i18n", value: true)
The client now requests tiles with all supported languages and worldviews. You cannot restrict the set of languages or worldviews that are returned. If you want to make only a subset of languages or worldviews available to end users, do so programmatically on the client side by passing only the desired language and worldview codes using the code snippets in the previous section.
Using custom label layers with Mapbox tilesets
Label layers in Mapbox Standard and 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 as its source, you should set the text-field to name to fetch the localized label.
"text-field": ["get", "name"]
Available languages
Some languages may not have localized labels for every feature. In those cases, the feature will default to English.
| 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 |