How to Change the Language of Place Labels¶

Our default map styles show the names of places (countries, cities, towns, waterways, etc.) in up to two languages by default. The first is the "Latin" name (the local name if it happens to use a Latin script; otherwise the English name or a romanization), and the second is the local name (if the local name does not use a Latin script). We chose this approach to preserve readability for a large audience while still showing local names. However, some applications will benefit from explicit localization. This tutorial will show you how!

Editing the style¶

The first step is to pick the style you want to localize. You can start with one of our own, or design your own.

Next, it's time to customize the style! The property you need to look at is text-field, under the layout property of each layer. Our styles come with a rather complex expression that does string concatenation and fallback logic. The simplest way to change language labels is to replace the text-field key with a value like {name:fr}. The braces tell the renderer that it should use the value of the field for the text label. In this case, it will use the name:fr field, thus always picking the French name of the feature.

But what if the city, mountain, river, etc. doesn't have a French name? You can easily add fallback logic using the coalesce expression. For example, the following will use a French name if one exists, falling back to a Latin-based name next, and then finally falling back to the local name if there is no Latin name in our data.

"text-field": [
  "coalesce",
  [
    "get",
    "name:fr"
  ],
  [
    "get",
    "name:latin"
  ],
  [
    "get",
    "name"
  ]
]

Do this for every layer in your style that makes sense to localize. Some (for example, route numbers) can be left alone.

Using the style¶

Rather than using our hosted styles, you'll need to point your map rendering library (MapLibre, Leaflet, etc.) at the new style. You will need to host this on your web server or bundle it with your app as noted in our guide on creating a custom style.

We've collected everything together in an example repository. The example uses Leaflet, but it works equally well in MapLibre GL JS or any other framework that supports MapLibre JSON styles.