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

# XPackageGetUserLocale

> XPackageGetUserLocale

# XPackageGetUserLocale

获取当前用户区域设置。

<a id="syntaxSection" />

## 语法

```cpp theme={null}
HRESULT XPackageGetUserLocale(
    size_t localeSize,
    char* locale
)  
```

<a id="parametersSection" />

### 参数

*localeSize*   \_In\_\
类型：size\_t

成功时，*locale* 中字符串的大小。

*locale*   \_Out\_writes\_(localeSize)\
类型：char\*

成功时，包含用户区域设置。

<a id="retvalSection" />

### 返回值

类型：HRESULT

HRESULT 成功或错误代码。

<a id="remarksSection" />

## 备注

<Note>此函数在时间敏感线程上调用不安全。有关详细信息，请参阅[时间敏感线程](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)。</Note>

此函数获取与程序包区域设置最匹配的用户区域设置。如果未为程序包声明任何区域设置信息，则此函数成功但不会在 `locale` 中返回用户区域设置。如果程序包区域设置与已安装的用户区域设置匹配，则该函数成功并在 `locale` 中返回用户区域设置。如果程序包区域设置与已安装的用户区域设置不完全匹配，则该函数会尝试查找最匹配的已安装用户区域设置。如果该函数找不到近似匹配项，则会发生错误；否则，该函数成功并在 `locale` 中返回最匹配的已安装用户区域设置。

如果你正在使用智能交付来控制为你的游戏安装哪些语言，则用户为主机设置的区域设置对应的区块可能当前未安装。这要求游戏始终验证所需的区块是否已安装，并在未安装时回退到另一种语言：这需要相当多的关于区域设置及其如何回退到最接近语言的知识。此函数提供了一种获取当前用户区域设置或最匹配回退项的方法，而无需实现你自己的区域设置分析和回退过程。

以下代码示例演示如何使用此函数。

```cpp theme={null}
char gameLocale[LOCALE_NAME_MAX_LENGTH];

// Get the best user locale that is installed
HRESULT hr = XPackageGetUserLocale(_countof(gameLocale), gameLocale);
if (SUCCEEDED(hr))
{
    printf("Game using locale: %s\n", gameLocale);
}
```

<a id="requirementsSection" />

## 要求

**头文件：** XPackage.h

**库：** xgameruntime.lib

**支持的平台：** Windows、XBOX One 系列主机和 XBOX Series 主机

<a id="seealsoSection" />

## 概念性文档

* [智能交付：语言说明符](/build/core-features/common/packaging/intelligentdelivery-language)
* [时间敏感线程](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)
* [确定主机区域设置和语言](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/game-principles/localization/determining_console_locale)

## 另请参阅

[XPackage](/reference/system/xpackage/xpackage_members)\
[流式安装和智能交付](/build/core-features/common/packaging/overviews/streaming_install-intelligent_delivery)


## Related topics

- [确定主机区域设置与语言](/zh-CN/build/game-principles/localization/determining-console-locale.md)
- [本地化与全球化概览](/zh-CN/build/game-principles/localization.md)
- [XPackage](/zh-CN/reference/system/xpackage/xpackage_members.md)
- [面向 GDK 的 Unity C# API 包装器](/zh-CN/build/gdk-and-engines/unity/unity-api-wrappers.md)
- [支持的 NLS 函数](/zh-CN/build/game-principles/localization/supported-nls-apis.md)