本地化打包的资源

2025-05-01

可以根据用户的区域设置本地化在 MicrosoftGame.config 文件中使用的资源（字符串和图像）。每当使用 Visual Studio 2019 或更高版本生成游戏时，都会自动创建 resource.pri 文件（一个包含对字符串和图像的引用的数据文件）。这是一个自动生成的文件，是操作系统查找的具有特殊名称的文件。如果没有资源，默认的 resources.pri 文件只包含在 MicrosftGame.config 中定义的游戏名称。可以使用 Microsoft 游戏开发工具包 (GDK) 命令提示符检查此文件的内容，如下所示。

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

此命令将 resources.pri 文件所含的所有资源转储为 XML 格式。可以检查此文件是否包含要本地化的所有资源（字符串和图像）。可将 resources.pri 文件更新为包含面向不同语言的字符串/图像。名称、启动屏幕和徽标采用的是基于用户区域设置的不同语言。以下部分提供有关使用 Visual Studio 2019 或更高版本本地化字符串和图像的更多详细信息。

本地化应用名和说明

.config 文件中所含的所有资源（字符串和图像）均可本地化。用于包括本地化字符串的模式与用于包括本地化图像的模式略有不同。下一节详述可本地化的字符串。

添加可本地化的字符串

可以根据用户区域设置以及游戏支持的区域设置对 .config 文件中的字符串进行本地化。务必提供一个默认字符串，用作游戏不支持该用户区域设置时的回退。本节更详细地介绍了如何向游戏添加稍后可由 MicrosoftGame.config 文件使用的默认和本地化字符串。

在 Visual Studio 解决方案资源管理器中添加默认字符串

右键单击项目文件夹。可选步骤（以便更好地组织）如下所示。
选择“添加”，再选择“新筛选器”。
将新筛选器命名为“字符串”。
右键单击“Strings”文件夹。
依次选择“添加”、“新项”、“Visual C++\资源”。
选择“程序集资源文件(.resx)”。
这会在程序包根目录处创建一个 resources.resx 文件。可在此文件中添加与语言无关的资源字符串。系统显示一个带有空白的 String1 默认项的编辑 UI。

注意

Microsoft 游戏开发工具包 (GDK) 游戏所需的文件扩展名为 .resw 文件。 Visual Studio 不支持添加此扩展名，因此建议将 resources.resx 文件重命名为 resources.resw，以避免生成 resources.pri 文件时出现问题。

将程序包更新为包含字符串引用

通过使用“ms-resource:”句法，在 MicrosoftGame.config 文件中可以引用新添加的字符串说明。请注意，所使用的名称正是在资源文件中添加的名称。

  <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"/>

在 Visual Studio 解决方案资源管理器中为特定语言添加字符串

在项目的主文件夹中为支持的每种语言创建一个顶级子文件夹。
右键单击“Strings”文件夹。
选择“添加”，再选择“新筛选器”。
将新文件夹命名为“en-us”，再右键单击该文件夹。
依次选择“添加”、“新项”、“Visual C++/资源”。
选择“程序集资源文件(.resx)”。
选择一个包含 en-us 子文件夹的输出位置。例如：C:\MyProject\en-us\resources.resx。
这会在程序包的 en-us 文件夹中创建一个 resources.resx 文件。可在此文件中添加英语资源字符串。系统显示一个带有空白的 String1 默认项的编辑 UI。
确保该文件“属性”中的“项目类型”为“PRI 资源”。
对游戏支持的每种其他语言重复上述步骤。

注意

更新 MicrosoftGame.config 文件中的语言

在 MicrosoftGame.config 文件的 Resources 部分下添加支持的每一种语言，如下所示。

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

将 MicrosoftGame.config 文件中的语言更新为包括繁体中文

如果游戏支持或计划支持繁体中文，则列表中已有 zh-TW 或 zh-HK。为了确保语言回退正确，请将 zh-SG 和 zh-CN 也添加到列表中。

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

在 Visual Studio 解决方案资源管理器中添加可本地化的图像

MicrosoftGame.config 具有适用于 Logo、 SmallLogo和 SplashScreen 的图像。可以为每种语言本地化这些图像。

对程序包清单中所有可本地化的图像执行以下步骤。

在项目的主文件夹中为支持的每种语言创建一个顶级子文件夹。
右键单击“Resource Files”文件夹。
选择“添加”，再选择“新筛选器”。
将新文件夹命名为“en-us”，再右键单击该文件夹。
选择“添加”，再选择“现有项”。
转到项目文件夹中的“en-us”子文件夹。选择要本地化的所有图像。
右键单击图像，然后转到“属性”。
确保“项目类型”设置为“图像”，“内容”设置为是。
对游戏支持的每种其他语言重复上述步骤。

如果程序包根文件夹中的每个 Logo、SmallLogo、SplashScreen 和 StoreLogo 不支持所选语言，请创建一个供使用的默认图像。

更新 MicrosoftGame.config 文件中的语言

如前面的示例中所示，更新 .config 文件中的 Resources 部分。

更新 MicrosoftGame.config 文件中的图像路径

使用创建的图像名称更新 .config 文件中的图像路径。程序包的根文件夹中必须有默认图像。无论使用哪种语言，都会先检查该特定语言文件夹中是否有图像文件；如果有，就使用该文件。或者，如果语言文件夹中缺少图像，或者不支持该语言（即语言文件夹缺失），则默认使用根文件夹中的图像文件，如下所示。

  <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"/>

注意

可以创建一个文件夹（例如“图像”），并在此文件夹中创建语言文件夹，而不是在根目录中创建所有语言文件夹。默认图像随后将显示在“Images”文件夹下（例如，C:\MyProject\Images）。这有助于更好地组织图像。游戏可按任何方式自由组织资源。在本例中，路径如下所示。

  <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"/>

游戏本地化提示

所有图像和字符串都位于其各自的文件夹后，它们会被自动用于 resources.pri 文件中。无论使用哪种语言，都会先检查特定语言文件夹中是否有资源；如果有，就使用该资源。另外，如果语言文件夹中没有图像，或者该语言不受不支持（即语言文件夹缺失），则使用默认资源。

在此，请注意游戏内和程序包资源本地化之间的差异。在 MicrosoftGame.config 文件中，默认资源用于解析字符串和图像。但是，在游戏内案例中，建议使用 GetUserDefaultLocaleName() API 返回的语言。前面提到过，你可以使用 Microsoft 游戏开发工具包 (GDK) 命令提示符检查 resources.pri 文件的内容，如下所示。

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

注意

请包括至少一个具有以下属性值的图像资源：Item Type 为 Image，Content 为 Yes。这对于确保在运行时解析本地化字符串是必要的。不包括此图像资源会将名称显示为“ms-resource:AppName”，而不是从资源文件中解析的游戏名称。

区块布局

应将区块布局文件更新为在本地化流程中包括生成的 resources.pri 文件。不需要包括资源文件，因为这些文件中的所有字符串均打包在 resources.pri 文件中。但是，你必须包括清单文件中正在使用的所有图像文件。 resources.pri 文件表示图像文件的路径，并且不包含图像本身。在区块布局文件的启动区块中包括这些图像文件和 resources.pri 文件，如下所示。

  <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)

智能交付

可使用语言和区域设置在布局文件中标记区块，指定其包含仅与指定标记值相关联的本地化内容。将已本地化的内容分隔，这样可以通过仅安装用户主机设定的语言所需的内容来缩短用户的安装时间。这种分隔还可让你选择排除与测试不相关的标记区块，从而减少测试使用 MakePkg.exe 创建的安装程序包时的迭代次数。例如，如果你想要测试法语音频文件，可以通过推送只含法语内容的文件来减少 xbappinstall 命令所需的时间。请考虑对这些示例使用以下布局文件。

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

利用智能安装唯一需要的步骤是：使用布局文件中的 Languages 标记。

注意

智能交付也可以使用多个其他标记，例如 OnDemand 或 Devices。此主题不包含对智能交付和区块布局标记的全面概述。有关详细信息，请参阅智能交付概述或智能交付：语言说明符。

用户体验

拆分已本地化的资产的主要好处是减少用户安装大小。用户启动使用 Languages 标记的游戏下载时，主机不会从任何不与基于用户设置的相应语言/区域设置关联的区块中下载内容。如果用户的语言和/或区域设置未出现在布局文件的任何 Languages 标记中，系统将确定最合适的替代项，以确保游戏所需的资产可用。以下一些示例显示了上述布局文件中将下载的区块，具体取决于用户的设置。

如果用户的主机设置为“en-US”，主机安装区块 1005 和 1008。
如果用户的主机设置为“fr-FR”，主机仅安装区块 1006。
如果用户的主机设置为“en-GB”，系统会发现没有对英式英语的显式支持。在这种情况下，控制台会查找支持的最佳替代语言“en-US”，在本例中安装区块 1005 和 1008。
无论用户的语言设置如何，下载的都是不包含 Languages 标记的任何区块。

测试智能交付

智能交付可缩小玩游戏所需的安装程序包的大小。测试安装流程最简单的方法是在 GDK 命令提示符中使用 xbappinstall 命令。 GDN 提供的 StreamingInstall 示例概述了从布局文件创建安装包和将其安装在开发主机上进行测试所需的基本步骤。

如果布局文件包含智能交付所需的标记，并且只运行 xbappinstall（仅含包路径），该行为将类似于零售体验。不会安装使用不同于主机设置的语言标记的区块。

如果想要测试多种语言和区域设置，无论主机设置如何，均可使用 /Languages 标志强制安装多种语言的所有区块。使用 /AllChunks 标志将整个程序包安装到主机。

如果要在初始安装后测试更改主机语言设置，需要 /w 标志。这使主机和托管程序包的开发电脑之间的连接在安装完成后保持打开状态。此后，你可以安装更多区块。这对于测试将只使用 /AllChunks 标志安装的 OnDemand 内容非常有用。

另请参阅

本地化和全球化（概述）
MicrosoftGame.config 本地化

通过

本地化打包的资源

本地化应用名和说明

添加可本地化的字符串

在 Visual Studio 解决方案资源管理器中添加默认字符串

将程序包更新为包含字符串引用

在 Visual Studio 解决方案资源管理器中为特定语言添加字符串

更新 MicrosoftGame.config 文件中的语言

将 MicrosoftGame.config 文件中的语言更新为包括繁体中文

在 Visual Studio 解决方案资源管理器中添加可本地化的图像

更新 MicrosoftGame.config 文件中的语言

更新 MicrosoftGame.config 文件中的图像路径

游戏本地化提示

区块布局

智能交付

用户体验

测试智能交付

另请参阅

其他资源