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. This guide also outlines changing label language in Mapbox Studio Classic.

Languages available

All Mapbox template maps use the Mapbox Streets vector tileset for map features. In this tileset, there are seven different name fields for each of the label layers:

  • name — the name or names used locally for the place
  • name_en — English (if available)
  • name_es — Spanish (if available)
  • name_fr — French (if available)
  • name_de — German (if available)
  • name_ru — Russian (if available)
  • name_zh — Chinese (if available)
  • name_zh-Hans — Simplified Chinese (if available)
  • name_pt — Portuguese (if available)
  • name_ar — Arabic (if available)

Change label language in Mapbox Studio

Layer by layer

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

screenshot in Mapbox Studio changing text-field input box with new language

screenshot in Mapbox Studio of resulting new language in map style

Multiple layers at once

Instead of changing each label layer individually, you can use the Filter layers panel to change all the label layer’s languages at once.

Click the Filter layers panel and then Filter by value. Choose Text fields from the list of categories and select each instance of {name_en} from the list. As you choose each of these, you will see your list of layers grow. Click on the top of the layer list, hold down the Shift key, and click on the last layer in the list. Once all the layers have been selected, you will be prompted to choose a value for all the layers.

screenshot of Mapbox Studio changing text field using filter layers

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.

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:

Layer mapText = map.getLayer("place-city-lg-n");
mapText.setProperties(textField("{name_ru}"));

See the Maps SDK for Android documentation for details and the language switch example in the Mapbox Android demo app for more code implementation.

Mapbox Maps SDK for iOS

With the Mapbox Maps SDK for iOS, you can automatically change the language of labels to the system’s preferred language.

func mapView(_ mapView: MGLMapView, didFinishLoading style: MGLStyle) {
     style.localizesLabels = true
}
- (void)mapView:(MGLMapView *)mapView didFinishLoadingStyle:(MGLStyle *)style {
    style.localizesLabels = YES;
}

You can also change the language of labels on your map dynamically at runtime:

// 'style' in this case refers to an MGLStyle object
let layer = style.layer(withIdentifier: "place-city-sm") as! MGLSymbolStyleLayer
layer.text = MGLStyleValue(rawValue: "{name_es}")
// 'style' in this case refers to an MGLStyle object
MGLSymbolStyleLayer *layer = (MGLSymbolStyleLayer *)[style layerWithIdentifier:@"place-city-sm"];
layer.text = [MGLStyleValue valueWithRawValue:@"{name_es}"];

See the Maps SDK for iOS documentation for more information.

Change label language in Mapbox Studio Classic

Most of the Mapbox preset styles in Mapbox Studio Classic will have a @name variable in the CartoCSS. This is where you can set the language. Below are the options and an example of how to set the value of @name to '[name_en]' or English labels.

// Language options: name (local), name_en, name_fr, name_es, name_de
@name: '[name_en]';

Swap out any of the language options inside the brackets to change your labels to that language.

Next, you must set all the labels with the property text-name with the value @name. For example:

#country_label[zoom>=3] {
  text-name: @name;
  ...
}