LocaleService

Localization service for a Viewer.

• A LocaleService is a container of string translations ("messages") for various locales.
• A Viewer has its own default LocaleService at Viewer#localeService.
• We can replace that with our own LocaleService, or a custom subclass, via the Viewer's constructor.
• Viewer plugins that need localized translations will attempt to them for the currently active locale from the LocaleService.
• Whenever we switch the LocaleService to a different locale, plugins will automatically refresh their translations for that locale.

Usage

In the example below, we'll create a Viewer that uses an XKTLoaderPlugin to load a BIM model, and a NavCubePlugin, which shows a camera navigation cube in the corner of the canvas.

We'll also configure our Viewer with our own LocaleService instance, configured with English, Māori and French translations for our NavCubePlugin.

We could instead have just used the Viewer's default LocaleService, but this example demonstrates how we might configure the Viewer our own custom LocaleService subclass.

The translations fetched by our NavCubePlugin will be:

• "NavCube.front"
• "NavCube.back"
• "NavCube.top"
• "NavCube.bottom"
• "NavCube.left"
• "NavCube.right"

These are paths that resolve to our translations for the currently active locale, and are hard-coded within the NavCubePlugin.

For example, if the LocaleService's locale is set to "fr", then the path "NavCube.back" will drill down into messages->fr->NavCube->front and fetch "Arrière".

If we didn't provide that particular translation in our LocaleService, or any translations for that locale, then the NavCubePlugin will just fall back on its own default hard-coded translation, which in this case is "BACK".

[Run example]

import {Viewer, LocaleService, NavCubePlugin, XKTLoaderPlugin} from "xeokit-sdk.es.js";

const viewer = new Viewer({

     canvasId: "myCanvas",

     localeService: new LocaleService({
         messages: {
             "en": { // English
                 "NavCube": {
                     "front": "Front",
                     "back": "Back",
                     "top": "Top",
                     "bottom": "Bottom",
                     "left": "Left",
                     "right": "Right"
                 }
             },
             "mi": { // Māori
                 "NavCube": {
                     "front": "Mua",
                     "back": "Tuarā",
                     "top": "Runga",
                     "bottom": "Raro",
                     "left": "Mauī",
                     "right": "Tika"
                 }
             },
             "fr": { // Francais
                 "NavCube": {
                     "front": "Avant",
                     "back": "Arrière",
                     "top": "Supérieur",
                     "bottom": "Inférieur",
                     "left": "Gauche",
                     "right": "Droit"
                 }
             }
         },
         locale: "en"
     })
 });

viewer.camera.eye = [-3.93, 2.85, 27.01];
viewer.camera.look = [4.40, 3.72, 8.89];
viewer.camera.up = [-0.01, 0.99, 0.03];

const navCubePlugin = new NavCubePlugin(viewer, {
     canvasID: "myNavCubeCanvas"
 });

const xktLoader = new XKTLoaderPlugin(viewer);

const model = xktLoader.load({
    id: "myModel",
    src: "./models/xkt/Duplex.ifc.xkt",
    edges: true
});

We can dynamically switch our Viewer to a different locale at any time, which will update the text on the faces of our NavCube:

viewer.localeService.locale = "mi"; // Switch to Māori

We can load new translations at any time:

viewer.localeService.loadMessages({
    "jp": { // Japanese
        "NavCube": {
            "front": "前部",
            "back": "裏",
            "top": "上",
            "bottom": "底",
            "left": "左",
            "right": "右"
        }
    }
});

And we can clear the translations if needed:

viewer.localeService.clearMessages();

We can get an "updated" event from the LocaleService whenever we switch locales or load messages, which is useful for triggering UI elements to refresh themselves with updated translations. Internally, our NavCubePlugin subscribes to this event, fetching new strings for itself via LocaleService#translate each time the event is fired.

viewer.localeService.on("updated", () => {
    console.log( viewer.localeService.translate("NavCube.left") );
});