콘솔 로캘 및 언어 결정

아티클
05/09/2023

GetUserDefaultLocaleName API를 사용하면 로캘 이름을 검색할 수 있습니다. 이 경우 User(은)는 로그인한 세션입니다. 이 API는 실제로 콘솔이 설정된 로캘을 검색합니다(아래 그림 참조).

wchar_t localeName[LOCALE_NAME_MAX_LENGTH];
int retVal = GetUserDefaultLocaleName( localeName, ARRAYSIZE( localeName ) );
// The value is returned in localeName.

일반적으로 게임은 장치에 지정된 로캘이나 언어에 사실상 신경 쓰지 않습니다. 실제로 신경 쓰는 것은 어떤 언어 리소스를 로딩해야 하는가입니다. 고급 수준의 경우 장치에서 사용자가 선택한 항목과 "가장 가까운" 게임 패키지에서 언어를 선택하는 것이 좋습니다. 이러한 선택에 기여하는 세 가지가 있습니다.

게임의 microsoftgame.config에서 선언되는 언어.
패키지 레이아웃 파일에서 선언되는 언어.
장치에 선택되는 언어.

"가장 가까운" 언어를 선택하는 것은 어려울 수 있습니다. 개발자는 XPackageGetUserLocale 함수를 사용하여 이 작업을 쉽게 할 수 있습니다. 항상 "가장 가까운" 언어가 반환됩니다. 게임은 어떤 게임 리소스를 로딩할지 파악하려면 이 언어를 사용해야 합니다. 다음 코드는 함수 사용법을 보여줍니다.

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);
}

몇 가지 시나리오가 가능한데, 이는 다음 예제에 설명되어 있습니다.

예제 1

콘솔에서 어떤 사용자가 언어 설정에 대해 프랑스어를 선택하고 국가 설정에 대해 프랑스(fr-FR)를 선택합니다. 이 사용자의 로캘은 fr-FR입니다. microsoftgame.config의 Resources 섹션에 다음이 포함된 게임이 사용자에게 있습니다.

<Resources>
    <Resource Language="en-US"/>
    <Resource Language="fr-FR"/>
    <Resource Language="de-DE"/>
    <Resource Language="en-GB"/>
</Resources>

이는 영어-미국(en-US), 프랑스어-프랑스(fr-FR), 독일어-독일(de-DE) 및 영어-영국(en-GB)에 대한 현지화된 문자열과 이미지가 게임에 있다는 것을 의미합니다. 이 사용자의 로캘은 매니페스트에서 지원하는 로캘과 일치하므로 XPackageGetUserLocale(은)는 fr-FR 값을 반환합니다. 모든 게임 내 텍스트는 프랑스어(fr-FR)로 표시됩니다. XPackageGetUserLocale의 반환값은 fr-FR입니다. GetUserDefaultLocaleName의 반환값도 fr-FR입니다.

예제 2

콘솔에서 어떤 사용자가 언어 설정에 대해 영어를 선택하고 국가 설정에 대해 영국(en-GB)을 선택합니다. 이 사용자의 로캘은 en-GB입니다. microsoftgame.config의 Resources 섹션에 다음이 포함된 게임이 사용자에게 있습니다.

<Resources>
    <Resource Language="en-US"/>
    <Resource Language="fr-FR"/>
    <Resource Language="de-DE"/>
</Resources>

이 사용자의 로캘은 매니페스트에 나타나지 않기 때문에 동일한 언어(영어)가 있는 대체 로캘이 기본 언어로 선택됩니다. 이 경우 en-US이므로 XPackageGetUserLocale(은)는 이 값을 반환합니다. 모든 게임 내 텍스트는 영어(en-US)로 표시됩니다. XPackageGetUserLocale 반환값은 en-US입니다. GetUserDefaultLocaleName 반환값은 en-GB입니다. GetUserDefaultLocaleName(은)는 게임이 선언한 것과 상관없이 콘솔에서 설정된 것을 반환한다는 것을 유념합니다.

예제 3

위의 예제와 비슷한 시나리오에서, 어떤 사용자가 콘솔에서 설정함으로 인해 사용자 로캘이 fr-FR입니다. MicrosoftGame.config의 Resources 섹션에는 다음이 있습니다.

<Resources>
    <Resource Language="en-US"/>
    <Resource Language="de-DE"/>
</Resources>

이 사용자의 로캘이 .config 파일에 없고 언어가 동일한 다른 로캘이 존재하지 않기 때문에 Resources 태그의 첫 번째 언어가 기본 언어(en-US)로 선택됩니다. XPackageGetUserLocale은(는) 이 값을 반환합니다. 모든 게임 내 텍스트는 영어(en-US)로 표시됩니다. XPackageGetUserLocale 반환값은 en-US입니다. GetUserDefaultLocaleName의 반환값은 fr-FR입니다.

요약

GetUserDefaultLocaleName(이)가 콘솔의 로캘을 반환합니다. 이렇게 하면 게임이 선언할 수 있는 것과 상관없이 장치에서 사용자가 설정한 것이 반환됩니다.

XPackageGetUserLocale에 의해 반환되는 언어는 다음을 기준으로 합니다.

사용자가 선택한 로캘이 microsoftgame.config 파일에 있는 경우 그 로캘이 반환됩니다.
microsoftgame.config 파일에서 로캘을 구할 수 없는 경우 이름이 동일한 다른 로캘을 찾습니다. 언어가 동일한 로캘이 여러 개 있는 경우 최상의 대체 로캘이 반환됩니다. 대체 언어는 사용자의 로캘을 기준으로 합니다.
앞서 언급한 두 가지 상황에서 실패하는 경우 Resources 섹션에 있는 첫 번째 로캘이 선택됩니다.
사용자가 선택한 언어에 로캘이 없는 경우 Resources 섹션의 첫 번째 로캘 항목이 선택됩니다.
microsoftgame.config에 언어가 하나도 없으면 XPackageGetUserLocale(은)는 콘솔 언어를 반환합니다.

참고 항목

GetUserDefaultLocaleName
XPackageGetUserLocale
지역화 및 세계화
MicrosoftGame.config 지역화

다음을 통해 공유

콘솔 로캘 및 언어 결정

예제 1

예제 2

예제 3

요약

참고 항목

추가 리소스