> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 确定主机区域设置与语言

> 确定当前 XBOX 主机的区域设置与语言，让你的 GDK 游戏能够选择正确的语言包与本地化资源。

使用 [`GetUserDefaultLocaleName`](https://learn.microsoft.com/windows/win32/api/winnls/nf-winnls-getuserdefaultlocalename) 获取当前登录会话的区域设置:

```cpp theme={null}
wchar_t localeName[LOCALE_NAME_MAX_LENGTH];
int retVal = GetUserDefaultLocaleName(localeName, ARRAYSIZE(localeName));
// The value is returned in localeName.
```

游戏通常并不关心确切的区域设置 —— 它们关心的是**应该加载哪些语言资源**。请选择游戏包中与用户所选设置“最接近”的语言。有三项输入很重要:

1. 在 `MicrosoftGame.config` 中声明的语言。
2. 在包布局文件中声明的语言。
3. 设备上所选的语言。

使用 [`XPackageGetUserLocale`](/reference/system/xpackage/functions/xpackagegetuserlocale) 始终获得最接近的受支持语言:

```cpp theme={null}
char gameLocale[LOCALE_NAME_MAX_LENGTH];
HRESULT hr = XPackageGetUserLocale(_countof(gameLocale), gameLocale);
if (SUCCEEDED(hr))
{
    printf("Game using locale: %s\n", gameLocale);
}
```

## 示例

### 1. 用户区域设置与受支持资源匹配

用户选择**法语 / 法国 (fr-FR)**。`MicrosoftGame.config`:

```xml theme={null}
<Resources>
    <Resource Language="en-US"/>
    <Resource Language="fr-FR"/>
    <Resource Language="de-DE"/>
    <Resource Language="en-GB"/>
</Resources>
```

* `XPackageGetUserLocale` 返回 `fr-FR`。
* `GetUserDefaultLocaleName` 返回 `fr-FR`。

### 2. 用户区域设置未在清单中,但存在相同语言

用户选择**英语 / 英国 (en-GB)**。`MicrosoftGame.config`:

```xml theme={null}
<Resources>
    <Resource Language="en-US"/>
    <Resource Language="fr-FR"/>
    <Resource Language="de-DE"/>
</Resources>
```

* `XPackageGetUserLocale` 返回 `en-US`(在同一语言内的回退)。
* `GetUserDefaultLocaleName` 返回 `en-GB`(始终是主机上的值)。

### 3. 用户语言完全不存在

用户区域设置为 `fr-FR`。`MicrosoftGame.config`:

```xml theme={null}
<Resources>
    <Resource Language="en-US"/>
    <Resource Language="de-DE"/>
</Resources>
```

* `XPackageGetUserLocale` 返回 `en-US`(`Resources` 中的第一项)。
* `GetUserDefaultLocaleName` 返回 `fr-FR`。

## 小结

* `GetUserDefaultLocaleName` —— 主机上所设置的值,不考虑游戏声明的语言。
* `XPackageGetUserLocale` —— 应加载哪种语言,使用以下逻辑:
  1. 如果用户的区域设置存在于 `MicrosoftGame.config` 中,则返回它。
  2. 否则在清单中查找相同语言的区域设置(基于用户区域设置的最佳回退)。
  3. 否则返回 `Resources` 中的第一个区域设置。
  4. 如果没有列出任何语言,则返回主机语言。

## 另请参阅

* [XPackageGetUserLocale](/reference/system/xpackage/functions/xpackagegetuserlocale)
* [MicrosoftGame.config 本地化](/build/core-features/common/game-config/MicrosoftGameConfig-Localization)

## 相关 API 文档

* [XGameRuntime features reference](/reference/system/xgameruntimefeature/xgameruntimefeature_members) —— `XGameRuntimeLocale` 获取当前活跃的区域设置
* [XPackage API reference](/reference/system/xpackage/xpackage_members) —— 支持区域设置的包资源查询


## Related topics

- [本地化与全球化概览](/zh-CN/build/game-principles/localization.md)
- [XPackageGetUserLocale](/zh-CN/reference/system/xpackage/functions/xpackagegetuserlocale.md)
- [确定主机所在地区](/zh-CN/build/game-principles/localization/determining-console-geolocation.md)
- [主机支持的语言](/zh-CN/build/game-principles/localization/console-supported-languages.md)
- [游戏支持与不支持的区域设置](/zh-CN/build/game-principles/localization/game-supported-and-unsupported-locales.md)