All docsHelpTroubleshootingChange your map’s label language

Change your map’s label language

When building a map from a Mapbox template style, map labels will appear in English by default. You can change the language of your map's labels directly in the Mapbox Studio style editor or dynamically using Mapbox GL JS, the Mapbox Maps SDK for Android, or the Mapbox Maps SDK for iOS.

Languages available

All Mapbox template maps use the Mapbox Streets vector tileset for map features. In this tileset, there are different name fields for each label layer. For a complete list of supported languages, see the Mapbox Streets v8 tileset documentation.

Right-to-left language support

Mapbox GL JS

The mapbox-gl-rtl-text plugin adds support for text written in the Arabic and Hebrew languages.

example
Add support for right-to-left scripts

Use the mapbox-gl-rtl-text plugin to support right-to-left languages such as Arabic and Hebrew.

Mapbox Studio

Mapbox Studio loads the mapbox-gl-rtl-text plugin by default.

Change label language in Mapbox Studio

You can change the language of map labels in Mapbox Studio by using style component properties or layer properties.

Components

In template styles built with style components, you can change the language of labels using component properties. The available components vary from style to style, but for each component containing labels:

  1. Click the name of the component.
  2. Find the Language property and select a language from the dropdown menu.
  3. Repeat for all components containing labels.

Layers

To change the language of individual layers in the Layers tab:

  1. Create a new style or edit an existing one in Mapbox Studio.
  2. Switch to the Layers tab.
  3. Select the layer that contains the labels you'd like to edit.
  4. Under the Text tab, click the value next to Text field. A panel will appear with all language options for the layer.
  5. Click the desired language; the map will update on select.

Change label language dynamically

Mapbox GL JS

If you are comfortable with JavaScript, you can change the language of your labels dynamically by using the .setLayoutProperty() method in Mapbox GL JS. See the language switcher Mapbox GL JS example for more details.

example
Change a map's language

Use setLayoutProperty to switch languages dynamically.

You can also use the Mapbox GL Language plugin to automatically change the layers of a map style to use the text-field that matches the browser language. Read more about this and other capabilities of the Mapbox GL Language plugin on GitHub.

Mapbox Maps SDK for Android

With the Mapbox Maps SDK for Android, you can change the language of labels on your map dynamically at runtime.

Use Style#localizeLabels(locale: Locale) if you want to change the language of the entire map all at once. This plugin detects the set language of the Android device and then changes all map text to that language. This also enables you to change the entire map to a specific language. This could be useful if you want to provide your user the ability to switch the map to a specific language at a specific time, rather than locking the map to the device's set default language or a particular language.

val locale = resources.configuration.locale
mapView.getMapboxMap().getStyle {
  style.localizeLabels(locale)
}
example
Change a map's language

Example showcasing how to localize a map client side to a specific locale using Style#localizeLabels(locale: Locale). This function will to localize a map into a selected locale if the symbol layers are using a Mapbox source and the locale is being provided as part of the vector source data.

You can also change labels to a specific language, either throughout the map or only for certain kinds of labels. For example, here's how you would change a map's city labels to Russian:

mapView.getMapboxMap().getStyle { style ->
  // Get an existing layer by referencing its
  // unique layer ID
  val layer = style.getLayerAs<SymbolLayer>("settlement-label")
  // Update layer properties
  layer.textField("{name_ru}")
}

Mapbox Maps SDK for iOS

With the Mapbox Maps SDK for iOS, you can change the language of labels on your map dynamically at runtime.

Use Style.localizeLabels automatically change the language of labels to the system's preferred language at runtime.

mapView.mapboxMap.style.localizeLabels(into: Locale(identifier: "es"))

You can also change labels to a specific language, either throughout the map or only for certain kinds of labels. For example, here's how you would change a map's city labels to Russian:

do {
  // Get an existing layer by referencing its
  // unique layer ID
  try mapView.mapboxMap.style.updateLayer(withId: "settlement-label", type: SymbolLayer.self) { layer in
    // Update layer properties
    layer.textField = "{name_ru}"
  }
} catch {
  print("Ran into an error updating the layer: \(error)")
}

See the Maps SDK for iOS documentation for more information.