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

# 判斷主機的地區設定與語言

> 在 GDK 遊戲中使用 GetUserDefaultLocaleName 與 XPackageGetUserLocale 偵測 XBOX 主機語言,並載入最接近的當地語系化資源。

使用 [`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`](/zh-TW/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](/zh-TW/reference/system/xpackage/functions/xpackagegetuserlocale)
* [MicrosoftGame.config 當地語系化](/zh-TW/build/core-features/common/game-config/MicrosoftGameConfig-Localization)

## 相關 API 文件

* [XGameRuntime 功能參考](/zh-TW/reference/system/xgameruntimefeature/xgameruntimefeature_members):用於取得作用中地區設定的 `XGameRuntimeLocale`
* [XPackage API 參考](/zh-TW/reference/system/xpackage/xpackage_members):可感知地區設定的套件資源查詢


## Related topics

- [媒體驗證測試步驟](/zh-TW/publishing/game-publishing/concepts/certification/certification-media-validation-test-steps.md)
- [認證主機 BVT 指南](/zh-TW/publishing/game-publishing/concepts/certification/certification-console-bvt-guide.md)
- [XBOX 主機遊戲的認證測試 XBOX 需求](/zh-TW/publishing/certification/console-cert-tested-requirements.md)
- [認證逐步指南](/zh-TW/publishing/game-publishing/concepts/certification/certification-guide.md)
- [XR-003 提交的遊戲品質](/zh-TW/publishing/certification/xr/xr-003.md)