Quickstart: Translating UI resources (HTML)

Article
01/11/2016

[ 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 ]

Put string resources for your UI into resource files. You can then reference those strings from your code or markup.

Instructions

Put strings into resource files, instead of putting them directly in code or markup.
1. Open package.appxmanifest in Visual Studio, go to the Application tab, and set your default language to "en-US". If this is a universal app, do this for each package.appxmanifest in your solution.Note This specifies the default language for the project. The default language resources are used if the user's preferred language or display languages do not match the language resources provided in the application. See Property Pages, JavaScript.
2. Create a folder to contain the resource files.
  1. In the Solution Explorer, right-click the project (the Shared project if this is a universal app) and select Add > New Folder.
  2. Name the new folder "strings".
  3. If the new folder is not visible in Solution Explorer, select Project > Show All Files from the Microsoft Visual Studio menu while the project is still selected.
3. Create a sub-folder and a resource file for English (United States).
  1. Right-click the strings folder and add a new folder beneath it. Name it "en-US". The resource file is placed in a folder that has been named for the BCP-47 language tag. See How to name resources using qualifiers for details on the language qualifier and a list of common language tags.
  2. Right-click the en-US folder and select Add > New Item….
  3. Select "Resources File (.resjson)".
  4. Click Add. This adds a resource file with the default name resources.rejson. We recommend that you use this default filename. Apps can partition their resources into other files, but you must be careful to refer to them correctly (see How to load string resources).
  5. The new file contains default content. Replace the content with the following (which may be very similar to the default):
    
    strings/en-US/resources.resjson
```
{
    "greeting"              : "Hello",
    "_greeting.comment"     : "A welcome greeting.",

    "farewell"              : "Goodbye",
    "_farewell.comment"     : "A goodbye."
}
```
    This is strict JavaScript Object Notation (JSON) syntax where a comma must be placed after each name/value pair, except the last one. In this sample, "greeting" and "farewell" identify the strings that are to be displayed. The other pairs ("_greeting.comment" and "_farewell.comment") are comments that describe the strings. The comments are a good place to provide any special instructions to translators who localize the strings to other languages.
Add string resource identifiers to code and markup.
1. Add references to the Windows Library for JavaScript to your HTML file, if they aren't already there.
  
  Note The following code shows the HTML for the default.html file of the Windows project that is generated when you create a new Blank App (Universal Apps) project in Visual Studio. Note that the file already contains references to the WinJS.
```

<link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet" />
<script src="//Microsoft.WinJS.2.0/js/base.js"></script>
<script src="//Microsoft.WinJS.2.0/js/ui.js"></script>
```
  Note The following code shows the HTML for the default.html file of the WindowsPhone project that is generated when you create a new Blank App (Universal Apps) project in Visual Studio. Note that the file already contains references to the WinJS.
```

<link href="/css/ui-themed.css" rel="stylesheet" />
<script src="//Microsoft.Phone.WinJS.2.1/js/base.js"></script>
<script src="//Microsoft.Phone.WinJS.2.1/js/ui.js"></script>
```
2. In the JavaScript code that accompanies your HTML file, call the WinJS.Resources.processAll function when your HTML is loaded.
```
WinJS.Application.onloaded = function(){
    WinJS.Resources.processAll();
}
```
  If additional HTML is loaded into a WinJS.UI.Pages.PageControl object, call WinJS.Resources.processAll(element) in the page control's IPageControlMembers.ready method, where element is the HTML element (and its child elements) being loaded. This example is based on scenario 6 of the Application resources and localization sample:
```
var output;

var page = WinJS.UI.Pages.define("/html/scenario6.html", {
    ready: function (element, options) {
        output = element.querySelector('#output');
        WinJS.Resources.processAll(output); // Refetch string resources
        WinJS.Resources.addEventListener("contextchanged", refresh, false);
    }
    unload: function () { 
        WinJS.Resources.removeEventListener("contextchanged", refresh, false); 
    } 
});
```
3. In the HTML, refer to the string resources using the resource identifiers ('greeting' and 'farewell') from the resource files.
```
<h2><span data-win-res="{textContent: 'greeting'}"></span></h2>
<h2><span data-win-res="{textContent: 'farewell'}"></span></h2>
```
4. Refer to string resources for attributes.
```
<div data-win-res="{attributes: {'aria-label' : 'String1'}}" >
```
5. Refer to string resources in JavaScript.
```
var el = element.querySelector('#header');
var res = WinJS.Resources.getString('greeting');
el.textContent = res.value;
el.setAttribute('lang', res.lang);
```
The general pattern of the data-win-res attribute for HTML replacement is data-win-res="{propertyname1: 'resource ID', propertyname2: 'resource ID2'}".

Note If the string does not contain any markup, then bind the resource wherever possible to the textContent property instead of innerHTML. The textContent property is much faster to replace than innerHTML.
Add folders and resource files for two other languages.
1. Add another folder under the strings folder for German. Name the folder "de-DE" for Deutsch (Deutschland).
2. Create another Resources.rejson file in the de-DE folder, and replace its content with the following:
  
  strings/de-DE/resources.resjson
```
{
    "greeting"              : "Hallo",
    "_greeting.comment"     : "A welcome greeting.",

    "farewell"              : "Auf Wiedersehen",
    "_farewell.comment"     : "A goodbye."
}
```
3. Create one more folder named "fr-FR", for français (France). Create a new Resources.rejson file and replace its content with the following:
  
  strings/fr-FR/resources.resjson
```
{
    "greeting"              : "Bonjour",
    "_greeting.comment"     : "A welcome greeting.",

    "farewell"              : "Au revoir",
    "_farewell.comment"     : "A goodbye."
}
```
Build and run the app.

Test the app for your default display language.
1. Press F5 to build and run the app.
2. Note that the greeting and farewell are displayed in the user's preferred language.
3. Exit the app.
Note Windows Store apps only. Test the app for the other languages.
1. Open the Control Panel, and select Clock, Language, and Region > Language.
2. Note that the language that was displayed when you ran the app is the top language listed that is English, German, or French. If your top language is not one of these three, the app falls back to the next one on the list that the app supports.
3. If you do not have all three of these languages on your machine, add the missing ones by clicking Add a language and adding them to the list.
4. To test the app with another language, select the language in the list and click Move up until it is at the top. Then run the app.
Note Windows Phone Store apps only. Test the app for the other languages.
1. Bring up Settings on the phone (or phone emulator).
2. Select language.
3. Note that the language that was displayed when you ran the app is the top language listed that is English, German, or French. If your top language is not one of these three, the app falls back to the next one on the list that the app supports.
4. If you do not have all three of these languages on your phone, add the missing ones by tapping add languages and adding them to the list.
5. To test the app with another language, tap and hold the language in the list and then tap move up until it is at the top. Then reset the phone and run the app.

How to name resources using qualifiers

How to load string resources

WinJS.Resources.processAll

Application resources and localization sample

Property Pages, JavaScript

The BCP-47 language tag

Quickstart: Translating UI resources (HTML)

Instructions

Related topics

Additional resources