DEV Community

Sam
Sam

Posted on • Originally published at spwoodcock.dev on

How to add translations to the MapLibre UI?

#webdev #geospatial #programming #typescript

How do translations work in MapLibre

  • MapLibre has very little built-in UI to speak of, as it’s mostly for displaying map data in whichever language the user decides.

  • However, there are a small number of control prompts, help texts, and tooltips to consider:

maplibre-tooltip

  • As of 2025-11, this consists of: 
export const defaultLocale = { "AttributionControl.ToggleAttribution": "Toggle attribution", "AttributionControl.MapFeedback": "Map feedback", "FullscreenControl.Enter": "Enter fullscreen", "FullscreenControl.Exit": "Exit fullscreen", "GeolocateControl.FindMyLocation": "Find my location", "GeolocateControl.LocationNotAvailable": "Location not available", "LogoControl.Title": "MapLibre logo", "Map.Title": "Map", "Marker.Title": "Map marker", "NavigationControl.ResetBearing": "Reset bearing to north", "NavigationControl.ZoomIn": "Zoom in", "NavigationControl.ZoomOut": "Zoom out", "Popup.Close": "Close popup", "ScaleControl.Feet": "ft", "ScaleControl.Meters": "m", "ScaleControl.Kilometers": "km", "ScaleControl.Miles": "mi", "ScaleControl.NauticalMiles": "nm", "GlobeControl.Enable": "Enable globe", "GlobeControl.Disable": "Disable globe", "TerrainControl.Enable": "Enable terrain", "TerrainControl.Disable": "Disable terrain", "CooperativeGesturesHandler.WindowsHelpText": "Use Ctrl + scroll to zoom the map", "CooperativeGesturesHandler.MacHelpText": "Use ⌘ + scroll to zoom the map", "CooperativeGesturesHandler.MobileHelpText": "Use two fingers to move the map", };
Enter fullscreen mode Exit fullscreen mode
  • Currently, the user is required to create their own translation file, then import and use it during MapLibre object instantiation: 
import maplibregl from "maplibre-gl"; // fr.ts contains the same content as above, translated import { fr } from "./locales/fr.ts"; new maplibregl.Map({ container: "map", style: "https://demotiles.maplibre.org/globe.json", center: [0, 0], zoom: 2, locale: fr, // Use the translation here });
Enter fullscreen mode Exit fullscreen mode

Introducing maplibre-ui-translations

  • In a web app I am developing, it is required for the user to change language dynamically, via a dropdown selector.
  • In order to simplify this, I decided to make a community plugin, maplibre-ui-translations.
  • The plugin is simple and has a single purpose: provide community-driven translations for the MapLibre UI elements in various languages, allowing the user to either: a. Change to a single different language. b. Support changing language via a dropdown selector or similar.
  • It handles the re-rendering of the MapLibre UI on language change via the helper function updateMaplibreLocale.

Example:

import maplibregl from "maplibre-gl"; import { defaultLocale } from "maplibre-gl/src/ui/default_locale"; import { updateMaplibreLocale, maplibreLocales, } from "maplibre-ui-translations"; const map = new maplibregl.Map({ container: "map", style: "https://demotiles.maplibre.org/globe.json", center: [0, 0], zoom: 2, locale: defaultLocale, }); document.querySelector("#lang-switcher")?.addEventListener("change", (e) => { const selectedCode = (e.target as HTMLSelectElement).value; updateMaplibreLocale(map, selectedCode); });
Enter fullscreen mode Exit fullscreen mode

Your help is needed!

  • If you are bilingual and could assist with the community translations, I have made a Weblate project for it.
  • The current translations are mostly machine translations, so validation of those would also be appreciated!
  • The plugin can be found in the MapLibre Plugin docs

Top comments (0)