Skip to main content

Translations

iCUE widgets support localization through JSON translation files and the tr() helper.

Translation File​

File Location​

Place the translation file in the same directory as index.html.

MyWidget/
├── index.html
├── translation.json
└── resources/
    └── icon.svg

File Format​

{
    "en": {
        "translation": {
            "Hello": "Hello",
            "Settings": "Settings"
        }
    },
    "de": {
        "translation": {
            "Hello": "Hallo",
            "Settings": "Einstellungen"
        }
    },
    "uk": {
        "translation": {
            "Hello": "Привіт",
            "Settings": "Налаштування"
        }
    }
}

Supported Languages​

CodeLanguage
enEnglish (default, required)
deGerman
esSpanish
frFrench
itItalian
jaJapanese
koKorean
ptPortuguese
ruRussian
zh_CNChinese (Simplified)
zh_TWChinese (Traditional)
ukUkrainian

Note: en is required and is used as the fallback language for missing translations.

Using Translations​

In Meta Parameters​

Use tr('key') in data-label, title, and other attributes:

<title>tr('My Widget')</title>

<meta
    name="x-icue-property"
    content="textColor"
    data-label="tr('Text Color')"
    data-type="color"
    data-default="'#ffffff'"
/>

<script type="application/json" id="x-icue-groups">
    [
        {
            "title": "tr('Appearance')",
            "properties": ["textColor", "backgroundColor"]
        }
    ]
</script>

In JavaScript​

The tr() function returns a Promise:

async function updateUI() {
    const label = await tr("Hello");
    document.getElementById("greeting").textContent = label;
}

tr("Settings").then((text) => {
    document.getElementById("title").textContent = text;
});

Multiple translations:

async function initTranslations() {
    const [hello, settings, save] = await Promise.all([
        tr("Hello"),
        tr("Settings"),
        tr("Save"),
    ]);
    document.getElementById("greeting").textContent = hello;
    document.getElementById("title").textContent = settings;
    document.getElementById("saveBtn").textContent = save;
}

Complete Example​

translation.json:

{
    "en": {
        "translation": {
            "Clock": "Clock",
            "Time Zone": "Time Zone",
            "Text Color": "Text Color",
            "Appearance": "Appearance"
        }
    },
    "uk": {
        "translation": {
            "Clock": "Годинник",
            "Time Zone": "Часовий пояс",
            "Text Color": "Колір тексту",
            "Appearance": "Зовнішній вигляд"
        }
    }
}

index.html:

<!doctype html>
<html lang="en">
    <head>
        <title>tr('Clock')</title>

        <meta
            name="x-icue-property"
            content="timeZone"
            data-label="tr('Time Zone')"
            data-type="combobox"
            data-values="[{'key':'utc','value':tr('UTC')},{'key':'est','value':tr('EST')},{'key':'cst','value':tr('CST')}]"
        />

        <meta
            name="x-icue-property"
            content="textColor"
            data-label="tr('Text Color')"
            data-type="color"
            data-default="'#ffffff'"
        />

        <script type="application/json" id="x-icue-groups">
            [
                {
                    "title": "tr('Appearance')",
                    "properties": ["timeZone", "textColor"]
                }
            ]
        </script>
    </head>
    <body>
        <div id="time"></div>
    </body>
</html>