Skip to main content

Change your map’s label language

Additional Developer Resources

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 in 2 ways:

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, each containing the label name in a different language. For a complete list of supported languages, see the Mapbox Streets v8 tileset documentation.

Method 1: Change label language in Mapbox Studio​

You can change the language of map labels in Mapbox Studio in two ways:

Right to left support

Mapbox Studio has right to left text support by default using the mapbox-gl-rtl-text plugin. Other methods need to implement this manually.

Option 1: Components​

Components are groupings of similar map layers and can be used to change the language of labels on multiple layers with less configuration. The available components vary from style to style, but for each component containing labels you can change the language by doing the following:

  1. Create a new style or edit an existing one in Mapbox Studio.
  2. Switch to the Layers tab.
  3. Click the blue plus button.
  4. Hover over Components.
  5. Click Place Labels.
  6. In the Place Label menu that appears, scroll down until you see Languages and select the preferred language.
Matching the language to the country's language

In the list of available languages, you will see Local as an option. Select this option if you would like the label language to match the country's language on the map.

For example Korea would read as 한국 while Spain would read as España.

Option 2: Layers​

Change the language of each of the individual layers in the Layers tab separately:

  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.
  • Note: This will either be the Place Labels layer from a default mapbox style, or your own custom layer you added if you are changing a custom data set.
  1. Select the sub label whose language you want to change.
  2. Under the Text tab, click the Text field value.
  3. In the menu that appears click in the formula box. You may see fields labeled name and name_<lanuagecode>, where the language code is the language of the labels. You can switch out the name_<lanuagecode> for your preferred language. View the entire list of options in our [Tileset Reference guide]](https://docs.mapbox.com/data/tilesets/reference/mapbox-streets-v8/#names).
  • Note: If you are using a custom tileset, this may be named differently or may not exist at all.
  1. Click the desired field and the map's labels will update.

Now you will need to iterate through any other label layers you may have and change them according to your needs.

Custom data sets

This method is useful if you want to change the labels on a custom data set. But note that you will need to provide translations for any custom data you include and tag it as needed.

Method 2: Change the label language at runtime via code​

You can change the language of your map dynamically using Mapbox GL JS, the Mapbox Maps SDK for Android, or the Mapbox Maps SDK for iOS.

Mapbox GL JS​

You can change the language of your labels with Mapbox GL JS in two ways:

  • Option 1: Changing the map labels with .setLayoutProperty(), allowing for a quick and manual implementation.
  • Option 2: Using the Mapbox GL Language plugin which offers the ability to match the browser's current language.

Option 1: Using the .setLayoutProperty() method as demonstrated in the following example:

EXAMPLE
Change a map's language

This example shows how to use setLayoutProperty to switch languages dynamically.

Option 2: Using the Mapbox GL Language plugin to automatically change the layers of a map style with the text-field by matching language to the default language in the user's browser. To learn more about the Mapbox GL Language plugin, see the related GitHub page.

Right to left support

If you are looking to add right to left support to your language labels, view our mapbox-gl-rtl-text plugin. This plugin adds support for text written in the Arabic and Hebrew languages as demonstrated in the example below:

EXAMPLE
Add support for right-to-left scripts

This example showcases how to add right to left support to your webpage using Mapbox.

Mapbox Maps SDK for Android​

You can change the language of your labels with Mapbox Maps SDK for Android using Style#localizeLabels(locale: Locale).

Change the language by either:

Match the map to device's language​

To match the map's language to the device follow this code snippet or the example below:

val locale = resources.configuration.locale
mapView.getMapboxMap().getStyle {
  style.localizeLabels(locale)
}
EXAMPLE
Localization Plugin

This example showcases how to localize the map labels to match the device's current language.

Switch the map's language with a UI toggle​

To allow users to manually switch the map's language, followed this example:

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​

You can change the language of your labels with Mapbox Maps SDK for iOS using Style.localizeLabels.

Change the language by either:

Match the map to device's language​

To match the map's language to the device follow this code snippet below:

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

Switch the map's language with a UI toggle​

To allow users to manually switch the map's 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.

Additional Developer Resources
Was this page helpful?