anchorBefore You Begin

Install and initialize the SDK as described in Get Started with the Desktop SDK. Your widget must run inside Webex Contact Center Desktop.

anchorLocalization Module

The Desktop.i18n module creates and maintains the localization bundles for lit-element based widgets (in case you considered Starter Widget as a base).

The localization module is built based on the i18next package and enables the widget developer to utilize the Desktop internationalization mechanism and load additional localization bundles to it. For more information on i18next, refer the following resources:

• For Desktop.i18n instantiating object, see https://www.i18next.com/overview/api#instance-creation.
• For i18n instance back-end configuration, see https://github.com/i18next/i18next-http-backend.
• For i18n instance languageDetector configuration, see https://github.com/i18next/i18next-browser-languageDetector.
• For i18n instance init options, see https://www.i18next.com/overview/configuration-options.

Using this module implies that your widget has lit-element and lit-html libraries.

import {
    Desktop
} from "@wxcc-desktop/sdk";

// CreateOptions are optional.
const i18n = Desktop.i18n.createInstance();
const i18nMixin = Desktop.i18n.createMixin({
    i18n /*Injecting i18n service instance into lit-element mixin */
})

// FYI you can see default options like so
console.log(Desktop.i18n.DEFAULT_INIT_OPTIONS); // => i18n.init options that are using by Desktop by default

// To get started, Init i18n with options to be able call "t" function translations
if (!i18n.isInitialized) {
    // Here, you are adding (merging) your localization package with the Desktop existing set of packages
    const initOptions = Desktop.i18n.getMergedInitOptions(Desktop.i18n.DEFAULT_INIT_OPTIONS || {}, {
        defaultNS: "my-ns", // "ns" here stands for the default JSON file name containing the localization
        ns: ["my-ns"],
        fallbackLng: "en",
        backend: {
            loadPath: "/.../path-to-locales/.../{{lng}}/{{ns}}.json"
        }
    });

    i18n.init(initOptions).catch(err => console.log(err));
}

When the service is initialized, create components with the mixin you created earlier:

The mixin subscribes to i18n initialization and language-change events. It requests component updates when initialization completes or the active language changes, and exposes translations through this.t(...).

import {
    customElement,
    LitElement
} from "lit-element";
import {
    html
} from "lit-html";

@customElement("my-awesome-component")
export class MyAwesomeComponent extends i18nMixin(LitElement) {
    render() {
        return html`
          <p>${this.t("my-ns:key1")}</p>
          <p>${this.t("my-ns:key2")}</p>
        `;
    }
}

Methods

init(initOptions)

Initiates the localization module.

Example

i18n.init(initOptions);

Parameters

createInstance(createOptions)

Creates the localization bundles for lit-element based widgets.

Example

const i18n = Desktop.i18n.createInstance();
// returns instance described in https://www.i18next.com/overview/api#instance-creation

Parameters

createMixin()

Creates the localization (i18n) service instance into lit-element mixing.

Example

const i18nMixin = Desktop.i18n.createMixin({
  i18n /*Injecting i18n service instance into lit-element mixin */
});

getMergedInitOptions()

Adds or merges your localization package with the existing set of packages in Desktop.

Example

const initOptions = Desktop.i18n.getMergedInitOptions(
  Desktop.i18n.DEFAULT_INIT_OPTIONS || {},
  {
    defaultNS: "my-ns", // "ns" here stands for the default JSON file name containing the localization
    ns: ["my-ns"],
    fallbackLng: "en",
    backend: {
      loadPath: "/.../path-to-locales/.../{{lng}}/{{ns}}.json"
    }
  }
);

The following table lists the payload details:

cleanup()

Triggers the clean up when init service returns an undefined response.

Example

class MyWidget {
cleanup() {
    this.SERVICE = undefined;

    this.logger.info("Cleaned");
}
}

anchorRelated Pages

• Agent Desktop overview
• Desktop SDK Reference

anchorVerify Localization

Load your namespace files, render a known translation key, and switch the Desktop language. Confirm that the widget rerenders with the matching translation. If keys appear instead of translations, check the namespace and locale-file URL.