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