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

# Determinação da localidade e do idioma do console

> Use GetUserDefaultLocaleName e XPackageGetUserLocale para detectar o idioma do console XBOX e carregar os recursos localizados mais próximos no seu título do GDK.

Obtenha a localidade da sessão conectada com [`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.
```

Normalmente, os jogos não se importam com a localidade exata — eles se importam com **quais recursos de idioma carregar**. Escolha o idioma do pacote do jogo que seja o "mais próximo" do que o usuário selecionou. Três entradas são importantes:

1. Idiomas declarados no `MicrosoftGame.config`.
2. Idiomas declarados no arquivo de layout do pacote.
3. Idioma selecionado no dispositivo.

Use [`XPackageGetUserLocale`](/pt-BR/reference/system/xpackage/functions/xpackagegetuserlocale) para sempre obter o idioma compatível mais próximo:

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

## Exemplos

### 1. A localidade do usuário corresponde a um recurso compatível

O usuário seleciona **Francês / França (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` retorna `fr-FR`.
* `GetUserDefaultLocaleName` retorna `fr-FR`.

### 2. A localidade do usuário não está no manifesto, mas o mesmo idioma existe

O usuário seleciona **Inglês / Reino Unido (en-GB)**. `MicrosoftGame.config`:

```xml theme={null}
<Resources>
    <Resource Language="en-US"/>
    <Resource Language="fr-FR"/>
    <Resource Language="de-DE"/>
</Resources>
```

* `XPackageGetUserLocale` retorna `en-US` (fallback dentro do mesmo idioma).
* `GetUserDefaultLocaleName` retorna `en-GB` (sempre o valor do console).

### 3. O idioma do usuário não está presente

A localidade do usuário é `fr-FR`. `MicrosoftGame.config`:

```xml theme={null}
<Resources>
    <Resource Language="en-US"/>
    <Resource Language="de-DE"/>
</Resources>
```

* `XPackageGetUserLocale` retorna `en-US` (primeira entrada em `Resources`).
* `GetUserDefaultLocaleName` retorna `fr-FR`.

## Resumo

* `GetUserDefaultLocaleName` — o que está definido no console, ignorando os idiomas declarados pelo jogo.
* `XPackageGetUserLocale` — qual idioma carregar, usando esta lógica:
  1. Se a localidade do usuário estiver no `MicrosoftGame.config`, retorna essa localidade.
  2. Caso contrário, encontra uma localidade do mesmo idioma no manifesto (o melhor fallback com base na localidade do usuário).
  3. Caso contrário, retorna a primeira localidade em `Resources`.
  4. Se nenhum idioma estiver listado, retorna o idioma do console.

## Veja também

* [XPackageGetUserLocale](/pt-BR/reference/system/xpackage/functions/xpackagegetuserlocale)
* [Localização do MicrosoftGame.config](/pt-BR/build/core-features/common/game-config/MicrosoftGameConfig-Localization)

## Documentação de API relacionada

* [Referência de recursos do XGameRuntime](/pt-BR/reference/system/xgameruntimefeature/xgameruntimefeature_members) — `XGameRuntimeLocale` para a localidade ativa
* [Referência da API XPackage](/pt-BR/reference/system/xpackage/xpackage_members) — consultas de recursos do pacote com reconhecimento de localidade


## Related topics

- [Etapas do teste de validação de mídia](/pt-BR/publishing/game-publishing/concepts/certification/certification-media-validation-test-steps.md)
- [XR-003 Qualidade do título para envio](/pt-BR/publishing/certification/xr/xr-003.md)
- [Guia passo a passo da certificação](/pt-BR/publishing/game-publishing/concepts/certification/certification-guide.md)
- [Guia de BVT de console da certificação](/pt-BR/publishing/game-publishing/concepts/certification/certification-console-bvt-guide.md)
- [Requisitos do XBOX para jogos do XBOX](/pt-BR/publishing/certification/xbox-requirements.md)