Localizing Application Manifest Resources

The resources (strings and images) used in the package manifest can be localized according to the user’s locale. A resource.pri file, a data file that contains references to images and strings, is automatically created whenever you build the title using Visual Studio 2012 Update 2 or later. This file is auto-generated and is a specifically named file that the OS looks for. The default resources.pri file, in the absence of resources, just contains the name of the title defined in the package manifest. You can check the contents of this file using the XDK/ADK command prompt:

MakePri.exe dump /if resources.pri /of out.xml

The Make Package Resource Index (makepri.exe) tool lists all the resources included in the resources.pri file into an XML format. You can check if all the resources (images and strings) to be localized have been included in this file.

The resources.pri file can be updated to include strings and images for different languages so that the name, splash screens, and logos are in different languages based on the user locale. The sections below will give you more details about localizing strings and images using Visual Studio 2012 Update 2 or above.

All the resources (strings and images) included in the manifest can be localized. The pattern for including localized strings is slightly different from those for images. These are detailed in the following section.

Adding Localizable Strings

The strings in the manifest can be localized based on the user locale and the locales supported by the title. It is important to provide a default string, which acts as a fallback if the user locale is not supported by the game. This section gives more details about adding default and localized strings to a game, which can then be consumed by the package manifest.

Adding Default Strings on Windows 8

  1. Right click the project folder. Optional steps (for better organization):
    1. Select Add.
    2. Select New Filter
    3. Name the new filter Strings.
  2. Right click the Strings folder.
  3. Select Add.
  4. Select New Item.
  5. Select Visual C++\Windows Store.
  6. Choose Resource File(.resw).

This will create a resources.resw at the root of your package directory. This file is where you would add your language-independent resource strings. An editing UI will be presented with a default String1 entry that is blank.

Adding Default Strings On Windows 7

You won’t see the option of adding a .resw file if you are running Windows 7. As a workaround, you can use the template file that is included with the National Language Support APIs and Localization white paper.

  1. Paste the .zip file under C:\Users\<username>\Documents\Visual Studio 2012\Templates\ItemTemplates\Visual C++ Project.
  2. Restart Visual Studio.
  3. The template should now appear in the Visual C++ templates when you click on Add and select the New Item option.
  4. Add AppName with a value. The comments field is a good place to provide instructions to translators who localize the strings to different languages.
  5. Add AppDescription with a value.
  6. Right click on the resources file and go to Properties. Select the Item Type as PRI Resource if it is not already. This ensures that the data from this file is written into the resources.pri file.

Updating the Package Manifest to Include String References

Referencing the newly added string descriptions is done in the package.appxmanifest file using the “ms-resource:” syntax. Note that the name used is the same name added in the .resw file.

        
<VisualElements
  DisplayName="ms-resource:AppName"
  Logo="ATGGraphicsLogo.png"
  SmallLogo="ATGSmallLogo.png"
  Description="ms-resource:AppDescription"
  ForegroundText="dark"
  BackgroundColor="#000040">
  <SplashScreen Image="ATGSplashScreen.png" />
</VisualElements>

Adding Strings for Specific Languages On Windows 8

  1. Create a top-level subfolder in your project’s main folder for each language you support.
  2. Right click on the Strings folder.
  3. Select Add.
  4. Select New Filter.
  5. Name the new folder en-us.
  6. Right click the en-us folder.
  7. Select Add.
  8. Select New Item.
  9. Select Visual C++\Windows Store.
  10. Choose Resource File(.resw).
  11. Choose an output location that includes a subfolder of en-us. For example, C:\MyProject\en-us\resources.resw.
  12. This will create a resources.resw in an en-us folder of your package. This file is where you would add your English language resource strings. An editing UI will be presented with a default String1 entry that is blank.
  13. Ensure that the Item Type in the Properties of the file is PRI Resource.

Repeat this for each additional language your title supports.

Adding Strings for Specific Languages on Windows 7

You won’t see the option of adding a .resw file if you are running Windows 7. As a workaround, you can use the template file that is included with the National Language Support APIs and Localization white paper. Paste the .zip file under C:\Users\<username>\Documents\Visual Studio 2012\Templates\ItemTemplates\Visual C++ Project. Then restart Visual Studio. The template should now appear in the Visual C++ templates when you click on Add, and select the New Item option.

Update Languages in the Package Manifest

Add each supported language under the <Resources> section of the package manifest that you support.

<Resources>
  <Resource Language="en-US"/>
  <Resource Language="fr-FR"/>
  <Resource Language="de-DE"/>
</Resources>

Update the Package Manifest to Include the Strings

Add the string to be localized with the “ms-resource:” tag as shown in the previous example.

Adding Localizable Images

The package manifest has images for Logo, SmallLogo, WideLogo, and SplashScreen. These can be localized for each language. Follow the steps below for all localizable images in the package manifest:

  1. Create a top-level subfolder in your project’s main folder for each language you support.
  2. Right click on the Resource Files folder.
  3. Select Add.
  4. Select New Filter.
  5. Name the new folder en-us.
  6. Right click the en-us folder.
  7. Select Add.
  8. Select Exiting Item.
  9. Navigate to the en-us subfolder in your project’s folder and select all images you want localized.
  10. Right click on the image and go to Properties. Make sure that the Item Type is set to Image and the Content is set to Yes.
  11. Repeat this for each additional language your title supports.
  12. Create a default image to be used in case the selected language is not supported, for each of Logo, SmallLogo, WideLogo, and SplashScreen in the root folder of the package. For information about image sizes, see the VisualElements, SplashScreen, DefaultTile reference pages.

Update Languages in the Package Manifest

Update the Resources section in the package manifest as shown in the previous example.

Update the Image Path in the Manifest

Update the image paths in the manifest with the name of the image created. The default image must be present in the root folder of the package. For any language, it will first check for the image file in the particular language folder and use that file if available. Otherwise, if the image is missing from the language folder or the language is not supported (i.e., if the language folder is missing), it defaults to the image file in the root folder.

<VisualElements
  DisplayName="ms-resource:AppName"
  Logo="ATGGraphicsLogo.png"
  SmallLogo="ATGSmallLogo.png"
  Description="ms-resource:AppDescription"
  ForegroundText="dark"
  BackgroundColor="#000040">
  <SplashScreen Image="ATGSplashScreen.png" />
</VisualElements>

Note that instead of creating all the language folders in the root, you can create a folder (for example, Images) and then create the language folders within this folder. The default images will then be present under the Images folder (for example, C:\MyProject\Images). This will help in better organization of images. The title is free to organize resources in any manner. In this case, the paths will be:

<VisualElements
  DisplayName="ms-resource:AppName"
  Logo="Images\ATGGraphicsLogo.png"
  SmallLogo=" Images\ATGSmallLogo.png"
  Description="ms-resource:AppDescription"
  ForegroundText="dark"
  BackgroundColor="#000040">
  <SplashScreen Image=" Images\ATGSplashScreen.png" />
</VisualElements>

Title Localization Tips

Once all the images and strings are in their respective folders, they are automatically consumed into the resources.pri file. For any language, it will first check for the resources in the particular language folder and use it, if available. Otherwise, if the image is missing from the language folder or the language is not supported (i.e., if the language folder is missing), it picks up the default resource. Note the difference here between the in-title and package manifest resource localization. In the package manifest, the default resource is used to resolve the strings and images. In the in-title case, however, it is recommended that you use the language returned by the GetUserDefaultLocaleName() API. As mentioned above, you can check the contents of the resources.pri file using the XDK/ADK command prompt:

MakePri.exe dump /if resources.pri /of out.xml

Note Include at least one image resource with the following values in its Properties: Item Type as Image and Content as Yes. This is necessary to ensure that the localized string is resolved during runtime. Not including this will display the name as “ms-resource:AppName” instead of the resolved name of the title from the resources file.

See also

Application Model

Application Model Reference