> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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`](https://docs.xbox.com/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](https://docs.xbox.com/zh-TW/reference/system/xpackage/functions/xpackagegetuserlocale.md)
* [MicrosoftGame.config 當地語系化](https://docs.xbox.com/zh-TW/build/core-features/common/game-config/MicrosoftGameConfig-Localization.md)

## 相關 API 文件

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


## Related topics

- [Economy v2 當地語系化](https://docs.xbox.com/zh-TW/build/game-principles/localization.md)
- [XPackageGetUserLocale](https://docs.xbox.com/zh-TW/reference/system/xpackage/functions/xpackagegetuserlocale.md)
- [判斷主機位置](https://docs.xbox.com/zh-TW/build/game-principles/localization/determining-console-geolocation.md)
- [遊戲支援與不支援的地區設定](https://docs.xbox.com/zh-TW/build/game-principles/localization/game-supported-and-unsupported-locales.md)
- [主機支援的語言](https://docs.xbox.com/zh-TW/build/game-principles/localization/console-supported-languages.md)