Globalization and accessibility for tile and toast notifications (Windows Runtime apps)
This topic discusses the steps that you should take to globalize your tile and toast notifications through localization, scaling, and accessibility. We discuss the protocols by which you reference text and images that are either part of your app's package or saved to local storage, the avenues by which you address different languages and cultures, ease of access settings, and the sizing of your images on different devices. If you are already using the app resources platform in your apps, you will be familiar with these structural and naming conventions.
Text can be localized by storing the strings in different languages in a resource file—Resources.resjson (JavaScript) or Resources.resw (C# and C++).
Images can be localized, scaled, and made accessible through high contrast. How images are handled depends on their source.
Local images. Images in local storage (ms-appdata:///local/) are not handled by the resources platform discussed in this topic. Because the system does not choose the appropriate file version, the app itself must ensure that the appropriate file versions are placed into local storage.
Cloud images. A query string can be appended to the image's URL. The table below shows the different query strings.
Note To add a query string to the image Uniform Resource Identifier (URI) when you retrieve an image from a web server, you must override the default and set the addImageQuery attribute to "true" in the tile or toast notification XML payload. The addImageQuery attribute appears in the visual, binding, and image elements of both the tile and toast schemas. If addImageQuery is explicitly set in more than one of those elements, the value in a child element overrides the value in its parent or other ancestor. For instance, an addImageQuery value of "true" in an image element overrides an addImageQuery of "false" in its parent binding element.
| Type | Query string | Possible values | Example |
|---|---|---|---|
| Scale | ms-scale |
|
?ms-scale=100 |
| Accessibility | ms-contrast |
|
?ms-contrast=standard |
| Localization | ms-lang | The BCP-47 language tag specified in the notification template's lang attribute, or the default app language if lang is omitted. | ?ms-lang=en-US |
How to structure your app package for globalization and accessibility
Note The structure and naming conventions shown in this topic are only one scheme for naming and organizing files for globalization. You can use file name decorations (such as "scale-140"), arrange the files in appropriately named folders, or use a combination of the two as we outline in this topic.
- Text
Create a folder named "strings". This container is optional, but allows for better organization.
In the "strings" folder, create a subfolder for your default language, named with its BCP-47 specification (for instance, "en-US"). In that subfolder, add a Resources.resjson file (for JavaScript) or Resources.resw file (for C# and C++) that contains the strings for your default language. An example is shown here:
/ProjectFolder /strings /en-US resources.resjsonLocalization: Add another folder for each supported non-default language, named with their BCP-47 specifications. In each folder, place a Resources.resjson or Resources.resw file that contains the localized strings for that language. An example is shown here:
/ProjectFolder /strings /en-US resources.resjson /fr-FR resources.resjson /ja-JP resources.resjson
- Images
Note This applies only to images provided in the app's package (ms-appx), not to images in local storage (ms-appdata:///local/).
Create a folder named "images". Add the images for your default language, named with its BCP-47 specification, directly to the root of this folder.
Localization: Within the "images" folder, create folders for each supported non-default language, each named with their BCP-47 specification. Add the images for each language to their respective folder as shown here:
/ProjectFolder /images welcome.png /fr-FR welcome.png /ja-JP welcome.pngNote Corresponding image files for different languages must all have the same file name.
Accessibility: Under each language-specific folder, including the default language, create a folder for each supported contrast setting. Within each of those folders, place the image file specific to that contrast setting. Note that all of the files still have the same file name.
/ProjectFolder /images welcome.png /contrast-black welcome.png /contrast-white welcome.png /fr-FR welcome.png /contrast-black welcome.png /contrast-white welcome.png /ja-JP welcome.png /contrast-black welcome.png /contrast-white welcome.pngScaling: Each of the images discussed above should be supplied in scale-specific variants, with their file names decorated with the proper scale identifier. Note that this decoration is not recognized by the app resources platform as part of the file name, so that all of these files still effectively have the same name. The following example shows an image structure for en-US and ja-JP language resources. A single image is available for every scale and contrast value in both languages.
/ProjectFolder /images welcome.scale-80.png welcome.scale-100.png welcome.scale-140.png /contrast-black welcome.scale-80.png welcome.scale-100.png welcome.scale-140.png /contrast-white welcome.scale-80.png welcome.scale-100.png welcome.scale-140.png /ja-JP welcome.scale-80.png welcome.scale-100.png welcome.scale-140.png /contrast-black welcome.scale-80.png welcome.scale-100.png welcome.scale-140.png /contrast-white welcome.scale-80.png welcome.scale-100.png welcome.scale-140.png
For more information, see these topics:
- Globalizing your app
- Designing for globalization and localization (concepts)
- Application resources and localization samples
- Making tiles accessible
How to use localized images and text in a notification
This section explains how to refer to your globalized resources in your notifications so that Windows can select the appropriate version based on the device settings.
Text
In the text element of your template content, use the "ms-resource:" prefix in the text body, followed by the string tag as defined in the Resources.resjson or Resources.resw file. For instance, assume that you have a \fr-FR\Resources.resjson file that contains the following entry:
"greeting" : "Bonjour",
The element <text id="1">ms-resource:greeting</text> in your template's XML content would cause that string to be retrieved if the UI language was determined to be French.
If the body of a text element omits the "ms-resource:" prefix, it is treated as literal text.
Local images
Images included in the app package
Add the "ms-appx:///" prefix to the resource path in your template's image element. For example:
<image id="1" src="ms-appx:///images/welcome.png"/>
For images included in the app package, Windows identifies the correct image through the file structure and/or decoration to the file name. When you provide a globalized image resource in your template, supply only the file name.
- Correct: <image id="1" src="ms-appx:///images/welcome.png"/>
- Incorrect: <image id="1" src="ms-appx:///images/welcome.scale-100.png"/>
- Incorrect: <image id="1" src="ms-appx:///images/contrast-black/welcome.scale-100.png"/>
Images saved to local storage
Add the "ms-appdata:///local/" prefix to the path to the file relative to local storage (Windows.Storage.ApplicationData.current.localFolder). Image versions in local storage cannot be recognized by Windows based on the storage structure as in the app resources platform.
<image id="1" src="ms-appdata:///local/welcome.png"/>
Images saved in the Roaming or Temp folders
These images cannot be used.
Web images
Use an HTTP handler to inspect the query string for the language, scale, and contrast, the values of which can then be used.
Related topics
Application resources and localization samples
Tile and tile notification overview
Quickstart: Creating a default tile using the Visual Studio manifest editor
Quickstart: Sending a toast notification