> ## 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 타이틀이 올바른 언어 팩과 현지화된 리소스를 선택할 수 있도록 현재 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`](/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. 사용자 로케일이 지원되는 리소스와 일치

사용자가 **French / France (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. 사용자 로케일은 매니페스트에 없지만 동일 언어가 존재

사용자가 **English / UK (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 기능 레퍼런스](/reference/system/xgameruntimefeature/xgameruntimefeature_members) — 활성 로케일을 위한 `XGameRuntimeLocale`
* [XPackage API 레퍼런스](/reference/system/xpackage/xpackage_members) — 로케일 인식 패키지 리소스 쿼리


## Related topics

- [현지화 및 국제화 개요](/ko/build/game-principles/localization.md)
- [게임에서 지원 및 지원하지 않는 로케일](/ko/build/game-principles/localization/game-supported-and-unsupported-locales.md)
- [콘솔에서 지원하는 언어](/ko/build/game-principles/localization/console-supported-languages.md)
- [콘솔 위치 확인](/ko/build/game-principles/localization/determining-console-geolocation.md)
- [MicrosoftGame.config Element - Resource](/ko/reference/system/microsoftgameconfig/elements/microsoftgameconfig-element-resource.md)