Noções básicas sobre idiomas de perfil do usuário e idiomas de manifesto do app

Um usuário do Windows pode usar Configurações>Hora e idioma>Região e idioma para configurar uma lista ordenada de idiomas preferidos ou apenas um único idioma preferido. Um idioma pode ter uma variante regional. Por exemplo, é possível selecionar o espanhol falado na Espanha, o espanhol falado no México, o espanhol falado nos Estados Unidos, entre outros.

Também em Configurações>Hora e idioma>Região e idioma, mas separado de idioma, o usuário pode especificar sua localização (conhecida como região) no mundo. Observe que a configuração de idioma (e variante regional) não é um determinante da configuração de região e vice-versa. Por exemplo, um usuário pode estar morando na França, mas escolher um idioma preferencial do Windows de Español (México).

Para aplicativos do Windows, um idioma é representado como uma marca de idioma BCP-47. Por exemplo, a marca de idioma BCP-47 "en-US" corresponde ao inglês (Estados Unidos) em Configurações. As APIs apropriadas do Windows Runtime aceitam e retornam representações de sequências de marca de idioma BCP-47.

Consulte também o registro de submarca de idioma IANA.

As três seções a seguir definem os termos da "lista de idiomas do perfil de usuário", da "lista de idiomas do manifesto do aplicativo" e da "lista de idiomas do runtime do aplicativo". Usaremos esses termos neste tópico e em outros tópicos nesta área de recursos, por isso é importante saber o que eles significam.

Lista de idiomas do perfil de usuário

A lista de idiomas do perfil de usuário é o nome da lista configurada pelo usuário em Configurações>Hora e idioma>Região e idioma>Idiomas. No código, você pode usar a propriedade GlobalizationPreferences.Languages para acessar a lista de idiomas do perfil de usuário como uma lista somente leitura de sequências, onde cada sequência é uma única marca de idioma BCP-47, como "en-US" ou "ja-JP".

    IReadOnlyList<string> userLanguages = Windows.System.UserProfile.GlobalizationPreferences.Languages;

Lista de idiomas do manifesto do aplicativo

A lista de idiomas do manifesto do aplicativo é a lista de idiomas para os quais o aplicativo declara (ou declarará) compatibilidade. Essa lista cresce à medida que você progride o aplicativo pelo ciclo de vida de desenvolvimento até a localização.

A lista é determinada em tempo de compilação, mas há duas opções para controlar exatamente como isso acontece. Uma opção é permitir que o Visual Studio determine a lista a partir dos arquivos no projeto. Para fazer isso, primeiro defina o idioma padrão do app na guia Aplicativo no arquivo de origem do manifesto do pacote do aplicativo (Package.appxmanifest). Em seguida, confirme se o mesmo arquivo contém essa configuração (o que acontece por padrão).

  <Resources>
    <Resource Language="x-generate" />
  </Resources>

Cada vez que o Visual Studio produz o arquivo do manifesto do pacote do aplicativo criado (AppxManifest.xml), ele expande esse único elemento Resource no arquivo de origem em uma união de todos os qualificadores de idioma que ele encontra no projeto (consulte Personalizar os recursos de idioma, escala, alto contraste e outros qualificadores). Por exemplo, se você começou a localizar e tem recursos de sequência, imagem e/ou arquivo cujos nomes de arquivo ou pasta incluem "en-US", "ja-JP" e "fr-FR", o arquivo AppxManifest.xml criado conterá o seguinte (a primeira entrada na lista é o idioma padrão definido).

  <Resources>
    <Resource Language="EN-US" />
    <Resource Language="JA-JP" />
    <Resource Language="FR-FR" />
  </Resources>

A outra opção é substituir esse único elemento "x-generate" <Resource> no arquivo de origem do manifesto do pacote do aplicativo (Package.appxmanifest) pela lista expandida de elementos <Resource> (tendo o cuidado de listar o idioma padrão primeiro). Essa opção envolve mais trabalho de manutenção para você, mas pode ser uma opção apropriada se você usar um sistema de build personalizado.

Para começar, a lista de idiomas do manifesto do aplicativo conterá apenas um idioma. Talvez seja en-US. Mas, em algum momento, à medida que você configura manualmente o manifesto ou adiciona recursos traduzidos ao projeto, essa lista aumentará.

Quando o aplicativo está na Microsoft Store, os idiomas na lista de idiomas do manifesto do aplicativo são os que são exibidos aos clientes. Para obter uma lista de marcas de idioma BCP-47 compatíveis especificamente com a Microsoft Store, consulte Idiomas com suporte.

No código, é possível usar a propriedade ApplicationLanguages.ManifestLanguages para acessar a lista de idiomas do manifesto do aplicativo como uma lista somente leitura de sequências, em que cada sequência é uma única marca de idioma BCP-47.

    IReadOnlyList<string> userLanguages = Windows.Globalization.ApplicationLanguages.ManifestLanguages;

Lista de idiomas do runtime do aplicativo

A terceira lista de idiomas de interesse é a interseção entre as duas listas que acabamos de descrever. No runtime, a lista de idiomas para os quais o aplicativo declarou compatibilidade (a lista de idiomas do manifesto do aplicativo) é comparada com a lista de idiomas para os quais o usuário declarou uma preferência (a lista de idiomas do perfil de usuário). A lista de idiomas do runtime do aplicativo é definida como essa interseção (se a interseção não estiver vazia) ou apenas para o idioma padrão do aplicativo (se a interseção estiver vazia).

Mais especificamente, a lista de idiomas do runtime do aplicativo é composta por esses itens.

1. (Opcional) Substituição de idioma principal. O PrimaryLanguageOverride é uma configuração de substituição simples para aplicativos que dão aos usuários sua própria opção de idioma independente ou aplicativos que têm algum motivo importante para substituir as opções de idioma padrão. Para saber mais, consulte Amostra de recursos e localização de aplicativos.
2. Os idiomas do usuário compatíveis com o aplicativo. Esta é a lista de idiomas do perfil de usuário filtrada pela lista de idiomas do manifesto do aplicativo. A filtragem dos idiomas do usuário por aqueles compatíveis com o aplicativo mantém a consistência entre Software Development Kits (SDKs), bibliotecas de classes, pacotes de estrutura dependentes e o aplicativo.
3. Se 1 e 2 estiverem vazios, o idioma padrão ou o primeiro compatível com o aplicativo. Se a lista de idiomas do perfil de usuário não contiver nenhum idioma compatível com o aplicativo, o idioma do runtime do aplicativo será o primeiro idioma compatível.

No código, é possível usar a propriedade ResourceContext.QualifierValues para acessar a lista de idiomas do runtime do aplicativo na forma de uma sequência que contém uma lista delimitada por ponto e vírgula de marcas de idioma BCP-47.

    string runtimeLanguages = Windows.ApplicationModel.Resources.Core.ResourceContext.GetForCurrentView().QualifierValues["Language"];

Também é possível acessá-la como uma lista somente leitura de sequências, cada uma contendo uma única marca de idioma BCP-47. É possível usar a propriedade ResourceContext.Languages ou a propriedade ApplicationLanguages.Languages para fazer isso.

    IReadOnlyList<string> runtimeLanguages = Windows.ApplicationModel.Resources.Core.ResourceContext.GetForCurrentView().Languages;

    runtimeLanguages = Windows.Globalization.ApplicationLanguages.Languages;

A lista de idiomas do runtime do aplicativo determina os recursos que o Windows carrega para o aplicativo e também os idiomas usados para formatar datas, horas, números e outros componentes. Confira Globalize seus formatos de data/hora/número.

Observação Se o idioma do perfil de usuário e o idioma do manifesto do aplicativo forem variantes regionais um do outro, a variante regional do usuário será usada como o idioma do runtime do aplicativo. Por exemplo, se o usuário preferir en-GB e o aplicativo for compatível com en-US, a linguagem do runtime do aplicativo será en-GB. Isso garante que datas, horas e números sejam formatados de acordo com as expectativas do usuário (en-GB), mas os recursos localizados ainda sejam carregados (devido à correspondência de idioma) no idioma compatível com o aplicativo (en-US).

Qualificar arquivos de recurso com seu idioma

Nomeie os arquivos de recurso, ou suas pastas, com qualificadores de recurso de idioma. Para saber mais sobre qualificadores de idioma, confira Personalizar os recursos de idioma, escala, alto contraste e outros qualificadores. Um arquivo de recurso pode ser uma imagem (ou outro ativo) ou um arquivo contêiner de recurso, como um .resw que contém sequências de texto.

Observação Até mesmo os recursos no idioma padrão do aplicativo devem especificar o qualificador de idioma. Por exemplo, se o idioma padrão do aplicativo for inglês (Estados Unidos), qualifique os ativos como \Assets\Images\en-US\logo.png.

• O Windows executa correspondências complexas, inclusive entre variantes regionais, como en-US e en-GB. Portanto, inclua a submarca de região conforme apropriado. Confira Como o Sistema de Gerenciamento de Recursos faz a correspondência de marcas de idioma.
• Especifique uma submarca de script de idioma no qualificador quando não houver nenhum valor Suppress-Script definido para o idioma. Por exemplo, em vez de zh-CN ou zh-TW, use zh-Hant, zh-Hant-TW ou zh-Hans (para obter mais detalhes, consulte o registro de submarcas de idioma IANA).
• Para idiomas que têm um único dialeto padrão, não há necessidade de incluir o qualificador de região. Por exemplo, use ja em vez de ja-JP.
• Algumas ferramentas e outros componentes, como tradutores automáticos, podem encontrar marcas de idioma específicas, como informações de dialeto regional, úteis para entender os dados.

Nem todos os recursos precisam ser localizados

A localização pode não ser necessária para todos os recursos.

• No mínimo, verifique se todos os recursos existem no idioma padrão.
• Um subconjunto de alguns recursos pode ser suficiente para um idioma intimamente relacionado (localização parcial). Por exemplo, talvez você não localize toda a interface do usuário do aplicativo em catalão se o aplicativo tiver um conjunto completo de recursos em espanhol. Para usuários que falam catalão e depois espanhol, os recursos que não estão disponíveis em catalão aparecem em espanhol.
• Alguns recursos podem exigir exceções para idiomas específicos, enquanto a maioria dos outros recursos é mapeada para um recurso comum. Nesse caso, marque o recurso a ser usado para todos os idiomas com a marca de idioma indeterminado 'und'. O Windows interpreta a marca de idioma 'und' como um curinga (semelhante a '*'), pois corresponde ao idioma principal do aplicativo após qualquer outra correspondência específica. Por exemplo, se alguns recursos são diferentes para o finlandês, mas o resto dos recursos é o mesmo para todos os idiomas, então o recurso finlandês deve ser marcado com a marca do idioma finlandês, e o restante deve ser marcado com 'und'.
• Para recursos baseados em um script de idioma, como uma fonte ou altura de texto, use a marca de idioma indeterminado com um script especificado: 'und-<script>'. Por exemplo, para fontes latinas use und-Latn\\fonts.css e para fontes cirílicas use und-Cryl\\fonts.css.

Definir o cabeçalho de solicitação HTTP Accept-Language

Considere se os serviços Web que você chama têm a mesma extensão de localização que o aplicativo. As solicitações HTTP feitas a partir de aplicativos do Windows em solicitações típicas da Web e XMLHttpRequest (XHR) usam o cabeçalho de solicitação HTTP Accept-Language padrão. Por padrão, o cabeçalho HTTP é definido como a lista de idiomas do perfil de usuário. Cada idioma na lista é expandido para incluir neutros do idioma e uma ponderação (q). Por exemplo, a lista de idiomas de um usuário de fr-FR e en-US resulta em um cabeçalho de solicitação HTTP Accept-Language de fr-FR, fr, en-US, en ("fr-FR,fr;q=0.8,en-US;q=0.5,en;q=0.3"). Mas se o aplicativo de clima (por exemplo) estiver exibindo uma interface do usuário em francês (França), mas o idioma principal do usuário na lista de preferências for alemão, será necessário solicitar explicitamente francês (França) do serviço para manter a consistência no aplicativo.

APIs no namespace Windows.Globalization

Normalmente, as APIs no namespace Windows.Globalization usam a lista de idioma do runtime do aplicativo para determinar o idioma. Se nenhum dos idiomas tiver um formato correspondente, a localidade do usuário será usada. Essa é a mesma localidade usada para o relógio do sistema. A localidade do usuário está disponível em Configurações>Hora e idioma>Região e idioma>Configurações adicionais de data, hora e regionais>Região: Alterar formatos de data, hora ou número. As APIs do Windows.Globalization também têm substituições para especificar uma lista de idiomas a serem usados, em vez da lista de idiomas do runtime do aplicativo.

Usando a classe Language, é possível inspecionar detalhes sobre um idioma específico, como o script do idioma, o nome de exibição e o nome nativo.

Usar a região geográfica quando apropriado

Em Configurações>Hora e idioma>Região e idioma>País ou região, o usuário pode especificar sua localização no mundo. É possível usar essas configurações, em vez do idioma, para escolher o conteúdo a ser exibido para o usuário. Por exemplo, um aplicativo de notícias pode exibir como padrão o conteúdo dessa região.

No código, você pode acessar essa configuração usando a propriedade GlobalizationPreferences.HomeGeographicRegion.

Usando a classe GeographicRegion, é possível inspecionar detalhes sobre uma região específica, como seu nome de exibição, nome nativo e moedas em uso.

Exemplos

A tabela a seguir contém exemplos do que o usuário veria na interface do usuário do aplicativo em várias configurações de idioma e região.

APIs importantes

• GlobalizationPreferences.Languages
• ApplicationLanguages.ManifestLanguages
• PrimaryLanguageOverride
• ResourceContext.QualifierValues
• ResourceContext.Languages
• ApplicationLanguages.Languages
• Windows.Globalization
• Idioma
• GlobalizationPreferences.HomeGeographicRegion
• GeographicRegion

Tópicos relacionados

• Marca de idioma BCP-47
• Registro de submarcas de idioma IANA
• Personalizar os recursos de idioma, escala, alto contraste e outros qualificadores
• Idiomas com suporte
• Globalize seus formatos de data/hora/número
• Como o Sistema de Gerenciamento de Recursos faz a correspondência de marcas de idioma

Amostras

• Amostra de recursos e localização de aplicativos