Proper way for translating background map text labels

[bastianolea]

I was trying to translate a {mapgl} MapLibre map's continent/country/city labels, following these instructions, but could not make it work:

library(mapgl)

# Expresión que toma el nombre en español y, si no existe, usa el nombre por defecto
etiqueta_es <- list("coalesce", list("get", "name:es"), list("get", "name"))

maplibre(
  style = carto_style("dark-matter"),
  attributionControl = FALSE,
  minZoom = 2,
  maxZoom = 11
) |>
  set_layout_property(
    layer_id = "place_country_1",
    name = "text-field",
    value = etiqueta_es
  ) |>
  set_layout_property(
    layer_id = "place_country_2",
    name = "text-field",
    value = etiqueta_es
  ) |>
  # Opcional: continente y estados/provincias también en español
  set_layout_property(
    layer_id = "place_continent",
    name = "text-field",
    value = etiqueta_es
  ) |>
  set_layout_property(
    layer_id = "place_state",
    name = "text-field",
    value = etiqueta_es
  )

After some fiddling, documentation reading, and help from Posit Assistant, I was able to translate the base map into Spanish using the following function:

library(mapgl)

#' Translate map labels to a different language
#'
#' Rewrites the `text-field` layout property of label layers in a MapLibre /
#' Mapbox style so that place names are displayed in the requested language.
#' This works around the fact that setting `text-field` after the map has
#' rendered (via [set_layout_property()]) can fail to take effect when the
#' vector source loads asynchronously: instead, the style itself is modified
#' before the map is created.
#'
#' The style's vector tiles must expose localized name fields following the
#' OpenMapTiles convention (`name:es`, `name:fr`, ...). Carto basemaps
#' (e.g. `carto_style("dark-matter")`) and other OpenMapTiles-based styles
#' satisfy this. If a feature has no name in the requested language, the
#' default `name` field is used as a fallback.
#'
#' @param style Either a URL to a style JSON or an already-parsed style as a
#'   list (e.g. from [jsonlite::fromJSON()] with `simplifyVector = FALSE`).
#' @param language ISO language code used to build the localized name field,
#'   e.g. `"es"`, `"fr"`, `"pt"`, `"de"`.
#' @param source_layers Character vector of `source-layer` names whose symbol
#'   layers should be translated. Defaults to `"place"`, which covers country,
#'   continent, state and city labels in OpenMapTiles styles.
#'
#' @return The modified style as a list, ready to pass to [maplibre()] (or
#'   [mapboxgl()]) via the `style` argument.
#'
#' @examples
#' \dontrun{
#' maplibre(style = translate_labels(carto_style("dark-matter"), "es"))
#'
#' # Translate water and road labels too
#' maplibre(
#'   style = translate_labels(
#'     carto_style("positron"),
#'     language = "fr",
#'     source_layers = c("place", "water_name", "transportation_name")
#'   )
#' )
#' }
#'
#' @export
translate_labels <- function(style, language = "en", source_layers = "place") {
  if (is.character(style)) {
    style <- jsonlite::fromJSON(style, simplifyVector = FALSE)
  }
  
  # Use the localized name, falling back to the default name when missing
  text_field <- list(
    "coalesce",
    list("get", paste0("name:", language)),
    list("get", "name")
  )
  
  style$layers <- lapply(style$layers, function(layer) {
    is_label <- identical(layer$type, "symbol") &&
      !is.null(layer$`source-layer`) &&
      layer$`source-layer` %in% source_layers
    if (is_label) {
      layer$layout$`text-field` <- text_field
    }
    layer
  })
  
  style
}

maplibre(
  style = translate_labels(carto_style("dark-matter"), language = "es"),
  attributionControl = FALSE,
  minZoom = 2,
  maxZoom = 11
)

Now base map text appears in Spanish instead of english!

I was wondering if there was another proper method for translating base map text with {mapgl} that I missed, of if I did a mistake with set_layout_property(), or maybe this is missing functionality that could be improved with the proposed function.

[bastianolea]

Sadly, it seems this only works properly for the "dark-matter" style. I found a solution for Shiny maps using proxys, which I provide below, but I can't seem to apply this solution to non-Shiny maps.

Passing a parsed Carto style as an inline R list to maplibre() produces a completely blank map for "voyager" and "positron" with MapLibre GL JS v5. "dark-matter" is unaffected. This is reproducible without any label modification:

# blank map:
maplibre(style = jsonlite::fromJSON(carto_style("voyager"), simplifyVector = FALSE))

# works:
maplibre(style = carto_style("voyager"))

The cause is that MapLibre GL JS v5 does not migrate legacy zoom-based stops property functions when the style is passed inline — the migration only happens when the style is fetched from a URL. No error is thrown.

This affects any workflow that modifies a style in R before passing it to maplibre(), including label translation.

Workaround for Shiny

Pass the style URL directly and apply set_layout_property via proxy after the map loads. input$<id>_bbox fires inside map.on("load") and is a reliable trigger.

All three Carto themes share identical layer IDs, so the layer list can be computed once at startup from any of them.

# Outside server() — runs once at startup
label_ids <- Filter(Negate(is.na), sapply(
  jsonlite::fromJSON(carto_style("voyager"), simplifyVector = FALSE)$layers,
  function(l) {
    if (identical(l$type, "symbol") && identical(l$`source-layer`, "place"))
      l$id else NA_character_
  }
))

# Inside server()
output$map <- renderMaplibre({
  maplibre(style = carto_style("voyager"))  # URL, not a parsed list
})

observeEvent(input$map_bbox, {
  text_field <- list("coalesce", list("get", "name:es"), list("get", "name"))
  proxy <- maplibre_proxy("map", session)
  for (lid in label_ids) {
    proxy <- set_layout_property(proxy, layer_id = lid,
                                 name = "text-field", value = text_field)
  }
}, once = TRUE)

---

This can be implemented as the following functions:

#' Get the label layer IDs from a style
#'
#' Returns the IDs of all symbol layers whose `source-layer` matches
#' `source_layers`. Useful for pre-computing layer IDs at app startup to avoid
#' repeated HTTP requests across user sessions.
#'
#' All three Carto themes (`"dark-matter"`, `"voyager"`, `"positron"`) share
#' identical layer IDs — this only needs to be called once with any of them,
#' regardless of which theme the map actually uses.
#'
#' @param style A URL to a style JSON or an already-parsed style list.
#' @param source_layers Character vector of `source-layer` names to match.
#'   Defaults to `"place"`.
#'
#' @return A character vector of layer IDs.
#'
#' @seealso [apply_label_translation()]
#'
#' @export
get_label_layer_ids <- function(style, source_layers = "place") {
  if (is.character(style)) {
    style <- jsonlite::fromJSON(style, simplifyVector = FALSE)
  }

  Filter(
    Negate(is.na),
    sapply(style$layers, function(layer) {
      is_label <- identical(layer$type, "symbol") &&
        !is.null(layer$`source-layer`) &&
        layer$`source-layer` %in% source_layers
      if (is_label) layer$id else NA_character_
    })
  )
}


#' Apply label translation via a Maplibre proxy (recommended in Shiny)
#'
#' Sets the `text-field` layout property of label layers in an already-rendered
#' MapLibre map, translating place names to the requested language. Because it
#' operates on a map that loaded from its URL, it is not affected by the
#' MapLibre GL JS v5 inline style issue and works with all Carto themes.
#'
#' ## Typical Shiny usage
#'
#' Pre-compute layer IDs once at startup (outside `server`) to avoid repeated
#' HTTP requests — all Carto themes share the same IDs:
#'
#' ```r
#' label_ids <- get_label_layer_ids(carto_style("voyager"))
#' ```
#'
#' Inside `server`, initialize the map with the URL directly and apply the
#' translation once after the map finishes loading. The `<id>_bbox` input is
#' set by mapgl inside `map.on("load")`:
#'
#' ```r
#' output$map <- renderMaplibre({
#'   maplibre(style = carto_style("voyager"), ...)
#' })
#'
#' observeEvent(input$map_bbox, {
#'   maplibre_proxy("map", session) |>
#'     apply_label_translation(label_ids, language = "es")
#' }, once = TRUE)
#' ```
#'
#' @param proxy A `maplibre_proxy` object (from [mapgl::maplibre_proxy()]).
#' @param layer_ids Character vector of layer IDs to translate, as returned by
#'   [get_label_layer_ids()]. Also accepts a style URL or parsed list, in which
#'   case [get_label_layer_ids()] is called internally (less efficient if the
#'   map re-renders multiple times).
#' @param language ISO language code, e.g. `"es"`, `"fr"`, `"pt"`, `"de"`.
#' @param source_layers Passed to [get_label_layer_ids()] when `layer_ids` is
#'   a URL or list. Ignored when `layer_ids` is already a character vector.
#'   Defaults to `"place"`.
#'
#' @return The proxy object (invisibly), for use in a pipeline.
#'
#' @seealso [get_label_layer_ids()], [translate_labels()]
#'
#' @export
apply_label_translation <- function(
  proxy,
  layer_ids,
  language = "en",
  source_layers = "place"
) {
  # Accept either pre-computed IDs or a style URL/list for convenience
  if (
    !is.character(layer_ids) ||
      length(layer_ids) == 1 && grepl("^https?://|^\\{", layer_ids)
  ) {
    layer_ids <- get_label_layer_ids(layer_ids, source_layers)
  }

  text_field <- list(
    "coalesce",
    list("get", paste0("name:", language)),
    list("get", "name")
  )

  for (lid in layer_ids) {
    proxy <- mapgl::set_layout_property(
      proxy,
      layer_id = lid,
      name     = "text-field",
      value    = text_field
    )
  }

  invisible(proxy)
}

Here is a minimal reproducible Shiny app using the translate funcions:

library(shiny)
library(bslib)
library(mapgl)

# Helper functions ----

get_label_layer_ids <- function(style, source_layers = "place") {
  if (is.character(style)) {
    style <- jsonlite::fromJSON(style, simplifyVector = FALSE)
  }
  Filter(
    Negate(is.na),
    sapply(style$layers, function(layer) {
      is_label <- identical(layer$type, "symbol") &&
        !is.null(layer$`source-layer`) &&
        layer$`source-layer` %in% source_layers
      if (is_label) layer$id else NA_character_
    })
  )
}

apply_label_translation <- function(proxy, layer_ids, language = "en") {
  text_field <- list(
    "coalesce",
    list("get", paste0("name:", language)),
    list("get", "name")
  )
  for (lid in layer_ids) {
    proxy <- set_layout_property(
      proxy,
      layer_id = lid,
      name     = "text-field",
      value    = text_field
    )
  }
  invisible(proxy)
}

# Pre-compute once at startup — all Carto themes share the same layer IDs
label_ids <- get_label_layer_ids(carto_style("voyager"))

# UI ----

ui <- page_fillable(
  maplibreOutput("mapa", height = "100%")
)

# Server ----

server <- function(input, output, session) {

  output$mapa <- renderMaplibre({
    maplibre(style = carto_style("voyager"))
  })

  # Apply translation once after the map finishes loading.
  # input$mapa_bbox is fired by mapgl inside map.on("load").
  observeEvent(input$mapa_bbox, {
    maplibre_proxy("mapa", session) |>
      apply_label_translation(label_ids, language = "es")
  }, once = TRUE)

}

shinyApp(ui, server)

Disclaimer: I used AI to get to this solution, but I iterated a lot to get to a solution that I could pass to you, as I'm not yet able to contribute directly to your (awesome) package.