Appearance

Change the Map Language ​

The Mapsted Maps JavaScript API supports multi-language properties. Entity names, category labels, floor names, and wayfinding instructions are all served in the configured language.

Open in Sandbox ↗

setLanguage switches the active language without reloading the page or re-initializing the API.

Prerequisites ​

  • The library initialised and in the READY state (API lifecycle).
  • The target language must be configured for your property in the Mapsted CMS.

Setting a language at init time ​

Pass the language field on InitOptions using a BCP 47 language tag:

CDN ​

html
<script src="https://mapi.mapsted.com/v4.0.1/maps.js?id=1234"></script>
<script>
  await mapsted.maps.init({
    element: '#map',
    language: 'fr',  // French
  });
</script>

npm ​

js
import * as maps from '@mapsted/maps-js-api';

await maps.init({
  element: '#map',
  propertyId: 1234,
  language: 'fr',  // French
});

Switching language at runtime ​

Call setLanguage at any time after init resolves. It accepts a BCP 47 language tag and throws MAPSTED-1082 if the tag is not valid BCP 47.

CDN ​

html
<script src="https://mapi.mapsted.com/v4.0.1/maps.js?id=1234"></script>
<script>
  await mapsted.maps.init({ element: '#map' });
  // Switch to Arabic at runtime
  await mapsted.maps.setLanguage('ar');
</script>

npm ​

js
import * as maps from '@mapsted/maps-js-api';

await maps.init({
  element: '#map',
  propertyId: 1234,
});
// Switch to Arabic at runtime
await maps.setLanguage('ar');

setLanguage is async. It sends a CHANGE_LANGUAGE message to the map iframe and updates the API's internal state after the message is dispatched. The camera position and selection state are preserved.

Reading the current language ​

Two complementary APIs are available depending on where the source of truth matters.

getLanguage() round-trips to the iframe and returns whatever language the iframe currently has active, whether it was set via init({ language }), setLanguage(), a URL ?lang=… param, the CMS property default, or the iframe's built-in language-switcher UI. Use this when you need the freshest value without having to subscribe to state changes:

js
// CDN
const current = await mapsted.maps.getLanguage();
console.log(current); // e.g. 'fr'
js
// npm
import * as maps from '@mapsted/maps-js-api';

const current = await maps.getLanguage();

Throws MAPSTED-1090 if called before the API is READY.

getState().language — cached value ​

The active language code is also available as language on the MapState snapshot returned by getState():

js
// CDN
const state = await mapsted.maps.getState();
console.log(state.language); // e.g. 'fr', or null before map is ready
js
// npm
import * as maps from '@mapsted/maps-js-api';

const state = await maps.getState();
console.log(state.language); // string | null

MapState.language is null until the map is fully loaded and reflects the API's local cache — calls to setLanguage() update it, but iframe-originated changes (URL param, CMS default, built-in switcher) are only visible to getLanguage().

Building a language switcher ​

The example below uses getState() to pre-select the active language and subscribe() to keep the picker in sync with state changes. The list of available language codes is property-specific — retrieve it from your CMS integration or hard-code based on your property configuration (see Current public-API scope below).

js
// CDN
const langSelect = document.getElementById('language-select');

// Pre-select the active language
const { language: currentLang } = await mapsted.maps.getState();
if (currentLang) langSelect.value = currentLang;

// Handle user selection
langSelect.addEventListener('change', async () => {
  await mapsted.maps.setLanguage(langSelect.value);
});

// Keep the picker in sync when language changes (e.g., from another call)
mapsted.maps.subscribe((state) => {
  if (state.language && state.language !== langSelect.value) {
    langSelect.value = state.language;
  }
});
js
// npm
import * as maps from '@mapsted/maps-js-api';

const langSelect = document.getElementById('language-select');

const { language: currentLang } = await maps.getState();
if (currentLang) langSelect.value = currentLang;

langSelect.addEventListener('change', async () => {
  await maps.setLanguage(langSelect.value);
});

maps.subscribe((state) => {
  if (state.language && state.language !== langSelect.value) {
    langSelect.value = state.language;
  }
});

Right-to-left layouts ​

When you switch to a right-to-left language (Arabic, Hebrew, etc.), the API adjusts its internal UI elements (floor selector, search box, route panel). Your outer page layout is not affected — apply dir="rtl" to your document or container element yourself based on the language code returned by getState():

js
// CDN
langSelect.addEventListener('change', async () => {
  await mapsted.maps.setLanguage(langSelect.value);
  const state = await mapsted.maps.getState();
  document.documentElement.dir = ['ar', 'he', 'fa', 'ur'].includes(state.language ?? '')
    ? 'rtl'
    : 'ltr';
});
js
// npm
import * as maps from '@mapsted/maps-js-api';

langSelect.addEventListener('change', async () => {
  await maps.setLanguage(langSelect.value);
  const state = await maps.getState();
  document.documentElement.dir = ['ar', 'he', 'fa', 'ur'].includes(state.language ?? '')
    ? 'rtl'
    : 'ltr';
});

Persisting language preference ​

Save the user's choice in localStorage so it survives page reloads:

js
// CDN
<script src="https://mapi.mapsted.com/v4.0.1/maps.js?id=1234"></script>
<script>
  const stored = localStorage.getItem('mapLanguage') ?? 'en';

  await mapsted.maps.init({
    element: '#map',
    language: stored,
  });

  mapsted.maps.subscribe((state) => {
    if (state.language) {
      localStorage.setItem('mapLanguage', state.language);
    }
  });
</script>
js
// npm
import * as maps from '@mapsted/maps-js-api';

const stored = localStorage.getItem('mapLanguage') ?? 'en';

await maps.init({
  element: '#map',
  propertyId: 1234,
  language: stored,
});

maps.subscribe((state) => {
  if (state.language) {
    localStorage.setItem('mapLanguage', state.language);
  }
});

Current public-API scope ​

getSupportedLanguages() is not available. The list of languages supported by a property must be managed on the host application side (e.g., fetched from your own CMS or configured statically). If runtime discovery of available languages is needed, contact info@mapsted.com to request this as a future API addition.

languageFallback and languageChange events are not part of the event surface. These events do not fire. Use subscribe() to observe MapState.language changes, or call getState() to read the current language after setLanguage resolves.

Migration note (V2 / V3) ​

changeLanguage() was the V2/V3 name. It is still exported from the migration shim and delegates to setLanguage() with a deprecation warning. Update call sites to use setLanguage() directly.