How to add translations to the MapLibre UI?
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:
-
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",
};- 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
});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);
});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