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
  • 80 (Start screen only)
  • 100
  • 140
  • 180
?ms-scale=100
Accessibility ms-contrast
  • standard
  • black
  • white
?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.resjson
      
    • Localization: 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.png
      

      Note  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.png
      
    • Scaling: 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:

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.

Globalizing your app

Choosing your app images

Making tiles accessible

Application resources and localization samples

Tiles XML schema

Toast XML schema

Tile and tile notification overview

Quickstart: Creating a default tile using the Visual Studio manifest editor

Quickstart: Sending a toast notification

The tile template catalog

The toast template catalog

Guidelines and checklist for tiles and badges

Guidelines and checklist for toast notifications