How to localize WinJS controls (HTML)

  • Article

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

Localize the labels and icons of your WinJS controls along with the rest of your app's content.

Prerequisites

Localizing properties

WinJS controls may have attributes that need to be localized, such as:

  • Labels and icons on app bar commands
  • Menu item labels
  • Toggle switch labels in Settings flyouts
  • ARIA labels used for accessibility

Add resource identifiers to the markup for your WinJS controls to refer to localized strings.

In the app bar example below, a data-win-res attribute is added to each app bar command with this pattern:

data-win-res="{winControl: {propertyName1:'resourceID1',propertyName2:'resourceID2'}}"

Each propertyName maps to one of the control's properties (such as label or title), and resourceID refers to the resource identifier of the string to be loaded from resource files. See the example of strings/en-US/resources.resjson, below.

In the JavaScript code that accompanies this markup, the WinJS.Resources.processAll function must be called when the HTML is loaded to replace the attributes and properties in each data-win-res attribute with resource strings.

App bar example

This example demonstrates how to localize command strings on an app bar.

<div data-win-control="WinJS.UI.AppBar" data-win-options="">
<button data-win-control="WinJS.UI.AppBarCommand" 
     data-win-res="{winControl: {label:'command1Label',tooltip:'command1Tooltip'}}"
     data-win-options="{id:'cmdCommand1',icon:'add',section:'global'}">
</button>
<button data-win-control="WinJS.UI.AppBarCommand"
     data-win-res="{winControl: {label:'command2Label',tooltip:'command2Tooltip'}}"
     data-win-options="{id:'cmdCommand2',icon:'remove',section:'global'}">
</button>
</div>

(function () {

    "use strict";
    var page = WinJS.UI.Pages.define("/html/localize-appbar.html", {
    ready: function (element, options) {
        // Load resources.
        loadResources();
        // Enable listener so they get updated when user changes language selection.
        WinJS.Resources.addEventListener("contextchanged", loadResources);
    }
});

// Handle loading of resources.
function loadResources() {
    WinJS.Resources.processAll();
}

})();

Resource files

strings/en-US/resources.resjson

{
    "command1Label"            : "en-US Command1",
    "command1Tooltip"          : "en-US Command1 Tooltip",

    "command2Label"            : "en-US Command2",
    "command2Tooltip"          : "en-US Command2 Tooltip"
}

strings/fr-FR/resources.resjson

{
    "command1Label"            : "fr-FR Command1",
    "command1Tooltip"          : "fr-FR Command1 Tooltip",

    "command2Label"            : "fr-FR Command2",
    "command2Tooltip"          : "fr-FR Command2 Tooltip"
}

strings/de-DE/resources.resjson

{
    "command1Label"            : "de-DE Command1",
    "command1Tooltip"          : "de-DE Command1 Tooltip",

    "command2Label"            : "de-DE Command2",
    "command2Tooltip"          : "de-DE Command2 Tooltip"
}

This markup demonstrates how to localize a menu control. It also requires JavaScript and resource files similar to the app bar example.

<div id="headerMenu" data-win-control="WinJS.UI.Menu">
    <button data-win-control="WinJS.UI.MenuCommand" 
        data-win-res="{winControl: {label:'item1Label'}}" 
        data-win-options="{id:'firstMenuItem'}">
    </button>
    <button data-win-control="WinJS.UI.MenuCommand" 
        data-win-res="{winControl: {label:'item2Label'}}" 
        data-win-options="{id:'secondMenuItem'}">
    </button>
    <hr data-win-control="WinJS.UI.MenuCommand" 
        data-win-options="{id:'separator',type:'separator'}" />
    <button data-win-control="WinJS.UI.MenuCommand" 
        data-win-res="{winControl: {label:'itemNLabel'}}" 
        data-win-options="{id:'lastMenuItem'}">
    </button>
</div>

Toggle switch example

This markup demonstrates how to localize a ToggleSwitch control. It also requires JavaScript and resource files similar to the app bar example.

<div data-win-control="WinJS.UI.ToggleSwitch" 
    data-win-res="{winControl: {labelOn:'switch1LabelOn',labelOff:'switch1LabelOff',
    title:'switch1Title'}}"
    data-win-options="">
</div>

HTML AppBar control sample

HTML flyout control sample

HTML ToggleSwitch control sample