Share via

Localization of packaged resources

  • Article

The resources (strings and images) that are used in the MicrosoftGame.config file can be localized according to the user's locale. A resource.pri file, a data file that contains references to strings and images, is automatically created whenever you build the title by using Visual Studio 2019 or later. This file is autogenerated and is a specifically named file that the operating system looks for. The default resources.pri file, in the absence of resources, contains only the name of the title that's defined in the MicrosoftGame.config file. You can check the contents of this file by using the Microsoft Game Development Kit (GDK) command prompt, shown as follows.

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

This command dumps all the resources that are included in the resources.pri file into an XML format. You can check if all the resources (strings and images) to be localized have been included in this file. The resources.pri file can be updated to include strings/images for different languages. The name, startup screens, and logos are in different languages that are based on the user's locale. The following sections give you more details about localizing strings and images by using Visual Studio 2019 or later.

Localizing app name and description

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

Adding localizable strings

The strings in the .config file can be localized based on the user's locale and the locales that are supported by the title. It's important to provide a default string, which acts as a fallback if the user's locale isn't 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 MicrosoftGame.config file.

Add default strings in Visual Studio Solution Explorer

  1. Right-click the project folder. Optional steps (for better organization) are as follows.
  2. Select Add, and then select New Filter.
  3. Name the new filter Strings.
  4. Right-click the Strings folder.
  5. Select Add, New Item, and then select Visual C++\Resource.
  6. Select Assembly Resource File (.resx).
  7. This creates a resources.resx file at the root of your package directory. This file is where you would add your language-independent resource strings. An editing UI is presented with a default String1 entry that's blank.

Note

The file extension required for Microsoft Game Development Kit (GDK) titles is a .resw file. Visual Studio doesn't support adding this extension so it is recommended to rename the resources.resx file to resources.resw to avoid issues when generating the resources.pri file.

Update the package to include string references

Referencing the newly added string descriptions is done in the MicrosoftGame.config file by using the "ms-resource:" syntax. Note that the name used is the same name that was added in the resource file.

  <ShellVisuals DefaultDisplayName="ms-resource:AppName"
                PublisherDisplayName="Publisher Display name"
                StoreLogo="StoreLogo.png"
                Square150x150Logo="Logo.png"
                Square44x44Logo="SmallLogo.png"
                Description="ms-resource:AppDescription"
                BackgroundColor="#000040"
                SplashScreenImage="SplashScreen.png"/>

Add strings for specific languages in Visual Studio Solution Explorer

  1. Create a top-level subfolder in your project's main folder for each language that you support.
  2. Right-click the Strings folder.
  3. Select Add, and then select New Filter.
  4. Name the new folder en-us, and then right-click that folder.
  5. Select Add, New Item, and then select Visual C++/Resources.
  6. Select Assembly Resource File (.resx).
  7. Choose an output location that includes a subfolder of en-us. For example, C:\MyProject\en-us\resources.resx.
  8. This creates a resources.resx file in an en-us folder of your package. This file is where you would add your English language resource strings. An editing UI is presented with a default String1 entry that's blank.
  9. Ensure that the Item Type in the Properties of the file is PRI Resource.
  10. Repeat these steps for each additional language that your title supports.

Note

The file extension required for Microsoft Game Development Kit (GDK) titles is a .resw file. Visual Studio doesn't support adding this extension so it is recommended to rename the resources.resx file to resources.resw to avoid issues when generating the resources.pri file.

Update languages in the MicrosoftGame.config file

Add each supported language under the Resources section of the MicrosoftGame.config file, shown as follows.

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

Update languages in the MicrosoftGame.config file to include Traditional Chinese

If your game supports or plans to support Traditional Chinese, either zh-TW or zh-HK is already in the list. To ensure proper language fallback, also add zh-SG and zh-CN to the list, shown as follows.

<Resources>
    <Resource Language="en"/>
    <Resource Language="en-US"/>
    <Resource Language="en-GB"/>
    <Resource Language="fr"/>
    <Resource Language="fr-FR"/>
    <Resource Language="de-DE"/>
    <Resource Language="ja-JP"/>
    <Resource Language="zh-TW"/>
    <Resource Language="zh-SG"/>
    <Resource Language="zh-CN"/>
  </Resources>

Add localizable images in Visual Studio Solution Explorer

The MicrosoftGame.config has images for Logo, SmallLogo, and SplashScreen. These can be localized for each language.

Use the following steps 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 the Resource Files folder.
  3. Select Add, and then select New Filter.
  4. Name the new folder en-us, and then right-click that folder.
  5. Select Add, and then select Exiting Item.
  6. Go to the en-us subfolder in your project's folder. Select all the images that you want localized.
  7. Right-click the image, and then go to Properties.
  8. Ensure that the Item Type is set to Image and that the Content is set to Yes.
  9. Repeat these steps for each additional language that your title supports.

Create a default image to be used if the selected language isn't supported for each of Logo, SmallLogo, SplashScreen, and StoreLogo in the root folder of the package.

Update languages in the MicrosoftGame.config file

Update the Resources section in the .config file as shown in the previous example.

Update the image path in the MicrosoftGame.config file

Update the image paths in the .config file with the name of the image that was created. The default image must be present in the root folder of the package. For any language, it first checks for the image file in the particular language folder and uses that file, if it's available. Otherwise, if the image is missing from the language folder or the language isn't supported (that is, if the language folder is missing), it defaults to the image file in the root folder, shown as follows.

  <ShellVisuals DefaultDisplayName="ms-resource:AppName"
                PublisherDisplayName="Publisher Display name"
                StoreLogo="StoreLogo.png"
                Square150x150Logo="Logo.png"
                Square44x44Logo="SmallLogo.png"
                Description="ms-resource:AppDescription"
                BackgroundColor="#000040"
                SplashScreenImage="SplashScreen.png"/>

Note

Instead of creating all the language folders in the root, you can create a folder (for example, Images) and create the language folders within this folder. The default images would then be present under the Images folder (for example, C:\MyProject\Images). This helps to better organize the images. The title is free to organize resources in any way. In this case, the paths would be as follows.

  <ShellVisuals DefaultDisplayName="ms-resource:AppName"
                PublisherDisplayName="Publisher Display name"
                StoreLogo="Images\StoreLogo.png"
                Square150x150Logo="Images\Logo.png"
                Square44x44Logo="Images\SmallLogo.png"
                Description="ms-resource:AppDescription"
                BackgroundColor="#000040"
                SplashScreenImage="Images\SplashScreen.png"/>

Title localization tips

After all the strings and images are in their respective folders, they're automatically consumed into the resources.pri file. For any language, it first checks for the resources in the particular language folder and uses it, if it's available. Otherwise, if the image is missing from the language folder or the language isn't supported (that is, if the language folder is missing), it picks up the default resource.

Be aware of the difference here between the in-title and package resource localization. In the MicrosoftGame.config file, the default resource is used to resolve the strings and images. In the in-title case, however, we recommend that you use the language that's returned by the GetUserDefaultLocaleName() API. As previously mentioned, you can check the contents of the resources.pri file by using the Microsoft Game Development Kit (GDK) command prompt, shown as follows.

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 displays the name as "ms-resource:AppName" instead of the resolved name of the title from the resources file.

Chunk layout

The chunk layout file should be updated to include the resources.pri file that's generated as part of the localization process. The resource files need not be included because all the strings from these files are packed in the resources.pri file. However, you have to include all the image files that are being used in the manifest file. The resources.pri file indicates the path to the image files and doesn't contain the image itself. Include these image files and the resources.pri file in the launch chunk of the chunk layout file, shown as follows.

  <Chunk Id="1000" Marker="Launch">
    … (All required files)
    <FileGroup DestinationPath="\Images" SourcePath="Images" Include="*.*"/>
    <FileGroup DestinationPath="\Images\en-US" SourcePath="Images\en-US" Include="*.*"/>
    <FileGroup DestinationPath="\Images\fr-FR" SourcePath="Images\fr-FR" Include="*.*"/>
    … (Other language files)
    <FileGroup DestinationPath="\" SourcePath="." Include="resources.pri"/>
  </Chunk>
  … (Other Chunks)

Intelligent Delivery

You can tag chunks in your layout file with languages and locales to specify that they contain localized content to be associated only with the specified tag value. Separating localized content reduces installation times for users by installing only the content needed for the language that their console is set to. This separation can also reduce iteration times when testing an installation package that was created with MakePkg.exe by giving you the option of excluding tagged chunks that aren't relevant to testing. For example, if you want to test French audio files, you can reduce the time that's required for an xbapp install command by pushing only the French content files. Consider the following layout file for these examples.

  <Chunk Id="1005" Languages="en-US">
    <FileGroup DestinationPath="\assets\audio" SourcePath="." Include="en_us_commentary.mp3"/>
  </Chunk>
  <Chunk Id="1006" Languages="fr-FR">
    <FileGroup DestinationPath="\assets\audio" SourcePath="." Include="fr_fr_commentary.mp3"/>
  </Chunk>
  <Chunk Id="1007" Languages="es-MX">
    <FileGroup DestinationPath="\assets\audio" SourcePath="." Include="es_mx_commentary.mp3"/>
  </Chunk>

  <Chunk Id="1008" Languages="es-MX, en-US">
    <FileGroup DestinationPath="\assets" SourcePath="." Include="mixed_content.dat"/>
  </Chunk>

Using the Languages tag in your layout file is the only step required to take advantage of intelligent installation.

Note

Intelligent Delivery can also make use of several other tags such as OnDemand or Devices. It's beyond the scope of this topic to provide a comprehensive overview of Intelligent Delivery and chunk layout tags. For more information, see the Intelligent Delivery overview or Intelligent Delivery: language specifiers.

User experience

The primary benefit of splitting your localized assets is the reduced installation size for the user. When a user initiates the download of a game that uses the Languages tag, the console won't download the content from any chunks that aren't associated with the appropriate language/locale that are based on the user's settings. If the user's language and/or locale isn't present in any of the Languages tags in your layout file, the system determines the most appropriate substitute to ensure that the assets required for gameplay are available. Following are some examples that show which chunks from the preceding layout file would be downloaded, depending on the user's settings.

  • If the user's console is set to "en-US", the console installs chunks 1005 and 1008.
  • If the user's console is set to "fr-FR", the console installs only chunk 1006.
  • If the user's console is set to "en-GB", the system sees that there's no explicit support for UK English. In this case, the console finds the best alternative language that's supported—"en-US", in this case—and installs chunks 1005 and 1008.
  • Any chunk that doesn't include the Languages tag is downloaded, regardless of the user's language settings.

Testing Intelligent Delivery

Intelligent Delivery reduces the size of the installation package that's required to play a game. Testing the installation process is most easily done with the xbapp install command from a GDK command prompt. The StreamingInstall sample available on GDN shows an overview of the basic steps that are required to create an installation package from a layout file and install it on your development console for testing.

If your layout file contains the tags that are needed for Intelligent Delivery and you simply run xbapp install with only the package path, the behavior is similar to the retail experience. Chunks tagged with languages that are different from the console's setting aren't installed.

If you want to test multiple languages and locales, use the /Languages flag to force the installation of all chunks for multiple languages, regardless of the console settings. Using the /AllChunks flag installs the entire package to the console.

If you want to test changing the console language settings after the initial installation, the /w flag is required. This keeps the connection open between the console and the development PC that's hosting the package after the installation is complete. You can then install more chunks at a later time. This is especially useful for testing OnDemand content that would otherwise be installed only by using the /AllChunks flag.

See also

Localization and globalization (overview)
MicrosoftGame.config localization