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

# 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`](https://docs.xbox.com/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](https://docs.xbox.com/pt-BR/reference/system/xpackage/functions/xpackagegetuserlocale.md)
* [Localização do MicrosoftGame.config](https://docs.xbox.com/pt-BR/build/core-features/common/game-config/MicrosoftGameConfig-Localization.md)

## Documentação de API relacionada

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


## Related topics

- [Visão geral](https://docs.xbox.com/pt-BR/build/game-principles/localization.md)
- [Determinação da localização do console](https://docs.xbox.com/pt-BR/build/game-principles/localization/determining-console-geolocation.md)
- [Fallback de idioma dos serviços do Xbox](https://docs.xbox.com/pt-BR/services/xbox-services/community/localized-strings/live-language-fallback.md)
- [Idiomas compatíveis com o console](https://docs.xbox.com/pt-BR/build/game-principles/localization/console-supported-languages.md)
- [Localidades compatíveis e não compatíveis com o jogo](https://docs.xbox.com/pt-BR/build/game-principles/localization/game-supported-and-unsupported-locales.md)