Add support for localizations

[GeekyEggo]

Background

The Stream Deck SDK provides support for localization in the form of multiple manifest files suffixed with locale codes, e.g. manifest.de.json; official, Stream Deck offers support for the following languages:

• Chinese: zh_CN
• German: de
• English: en
• French: fr
• Japanese: ja
• Korean: ko
• Spanish: es

Proposal

For content rendered as part of sdpi-components, it should be possible to offer a means of displaying translated content. This should be achievable in a centralized way that reduces duplication of both resources, and changes as part of sdpi-components.

Design

A new top-level object-instance will be added to the SDPIComponents namespace on the window, named i18n. This new object will enable interaction with translations, including specifying available resources. It will be up to the consumer to provide resources, and interact with this object to specify the available languages and their resources. An example of this interaction is:

SDPIComponents.i18n.locales = {
    en: {
        greeting: 'Hello'
    },
    es: {
        greeting: 'Hola'
    },
    fr: {
        greeting: 'Salut'
    }
};

When discovering a localization, the following hierarchy is used:

• Key present in language pack matching info.language.
• Key present in default language pack (en).
• No resources, fallback to raw value, e.g. __MSG_hello__.

Example

Given the following translations, and property inspector HTML.

SDPIComponents.i18n.locales = {
    en: {
        fav_color: "Favourite Color",
        please_choose_color: "Please choose a color",
        red: "Red",
        green: "Green",
        blue: "Blue",
    },
    ...
};

<sdpi-item label="__fav_color__">
    <sdpi-select setting="color" placeholder="__MSG_please_choose_color__">
        <optgroup label="__MSG_primary_colors__">
            <option value="#ff0000">__MSG_red__</option>
            <option value="#00ff00">__MSG_green__</option>
            <option value="#0000ff">__MSG_blue__</option>
        </optgroup>
    </sdpi-select>
</sdpi-item>

When the language is en, the element will render as follows:

<sdpi-item label="Favourite Color">
    <sdpi-select setting="color" placeholder="Please choose a color">
        <optgroup label="Primary Colors">
            <option value="#ff0000">Red</option>
            <option value="#00ff00">Green</option>
            <option value="#0000ff">Blue</option>
        </optgroup>
    </sdpi-select>
</sdpi-item>

Changes

To accommodate translations, the following initial changes will need to be made.

• Add a new sdpi-i18n element that provides a way of rendering content from a resource.
• Update labels for:
  • sdpi-item
  • sdpi-checkbox
  • sdpi-checkbox-list ¹
• Update option, and option group, labels for:
  • sdpi-radio ¹
  • sdpi-select ¹
• Update dynamic data sources to be localized.
• Update loading text to be localized.
• Update placeholder for:
  • sdpi-select
  • sdpi-textfield

¹ Translations will be applied to dynamic data sources.