Home > ApexMaps Docs > Docs > Localization

Localization

Most of the text on a map is already yours: series names, legend titles, tooltip formatters, a11y.label and a11y.description, a breadcrumb's rootLabel. What is left over is the handful of strings the map has to supply itself because nobody else does, such as the zoom buttons' names and what a region with no value reads as. The top-level locale option translates those.

const map = new ApexMaps(document.querySelector('#map'), {
  geo: { map: 'world/countries@110m' },
  series: [{ name: 'Taux de chômage', joinBy: ['iso_a3', 'code'], data }],
  locale: {
    zoomControls: { zoomIn: 'Agrandir', zoomOut: 'Réduire', reset: 'Réinitialiser' },
    noData: 'Aucune donnée',
  },
})

await map.render()

Every key falls back to its English default, and a group is merged key by key rather than replaced, so translating zoomIn alone keeps the English zoomOut instead of leaving it blank. A page can translate the buttons and leave everything else alone.

Every string

`locale` key	Default	Where it appears
`zoomControls.group`	`'Zoom'`	Accessible name of the on-screen zoom controls group.
`zoomControls.zoomIn`	`'Zoom in'`	The `+` button's accessible name and hover tooltip.
`zoomControls.zoomOut`	`'Zoom out'`	The `-` button's accessible name and hover tooltip.
`zoomControls.reset`	`'Reset view'`	The reset button's accessible name and hover tooltip.
`breadcrumb.label`	`'Drilldown trail'`	Accessible name of the drilldown breadcrumb.
`breadcrumb.root`	`'All areas'`	The first crumb, used only when neither `drilldown.breadcrumb.rootLabel` nor the map's own level name gives one.
`dataTable.caption`	`'Map data'`	Caption of the hidden data table when the series has no name.
`dataTable.area`	`'Area'`	First column heading of the data table on a region map.
`dataTable.item`	`'Item'`	First column heading of the data table on a point, line or arc map.
`dataTable.value`	`'Value'`	Value column heading of the data table when the series has no name.
`noData`	`'No data'`	What a region or point with no value reads as: in the tooltip, the data table, the keyboard announcement and the legend's no-data entry. A series' own `scale.nullLabel` still wins for its legend.
`sizeLegend`	`'Circle sizes: {sizes}'`	Accessible name of the bubble size legend. `{sizes}` is the list of sizes it shows.
`drilldown.announce`	`'Showing {count} {level}.'`	Announced to screen readers after a drill that leaves the map at the top level. `{count}` is the number of areas, `{level}` the level's name.
`drilldown.announceIn`	`'Showing {count} {level} in {where}. Press Escape to go back.'`	Announced below the top level. `{where}` is the drilldown trail, joined with commas.
`drilldown.areas`	`'areas'`	What `{level}` becomes when the map does not name its level.

Templates

sizeLegend, drilldown.announce and drilldown.announceIn are templates with {name} placeholders, filled in where the text is used. That lets a translation put the count or the place wherever its grammar wants it rather than where English puts it:

locale: {
  drilldown: {
    announce: '{count} {level} affichées.',
    announceIn: '{where} : {count} {level} affichées. Échap pour revenir.',
    areas: 'zones',
  },
}

A placeholder the template does not recognize is left as written.

Rules worth knowing

An empty string is kept. noData: '' is treated as a deliberate choice, not a missing translation, so it does not fall back to English.
Unknown keys and values of the wrong type are ignored, so a typo leaves the default in place rather than blanking a label.
updateOptions() and responsive rules reach the locale. A new locale passed to updateOptions() retitles the zoom buttons and the breadcrumb in place, without rebuilding them.

Localization

Every string

Templates

Rules worth knowing

See also