Fornecer recursos localizados para idiomas e culturas em um aplicativo ASP.NET Core

Por Rick Anderson, Damien Bowden, Bart Calixto, Nadeem Afana e Hisham Bin Ateya

Uma tarefa para localizar um aplicativo é fornecer cadeias de caracteres localizadas em arquivos de recursos. Este artigo é sobre como trabalhar com arquivos de recursos.

SupportedCultures e SupportedUICultures

ASP.NET Core tem duas coleções de valores culturais, SupportedCultures e SupportedUICultures. O CultureInfo objeto for SupportedCultures determina os resultados de funções dependentes da cultura, como formatação de data, hora, número e moeda. SupportedCultures também determina a ordem de classificação do texto, convenções de caixa e comparações de cadeia de caracteres. Consulte StringComparer.CurrentCulture para obter mais informações sobre como o servidor obtém as definições culturais. O SupportedUICultures determina quais cadeias de caracteres traduzidas (de arquivos .resx) são pesquisadas pelo ResourceManager. O ResourceManager simplesmente procura cadeias de caracteres específicas da cultura que são determinadas pelo CurrentUICulture. Cada thread no .NET tem CurrentCulture e CurrentUICulture objetos. ASP.NET Core inspeciona esses valores ao renderizar funções dependentes da cultura. Por exemplo, se a cultura do thread atual estiver definida como "en-US" (inglês, Estados Unidos), DateTime.Now.ToLongDateString() exibirá "quinta-feira, 18 de fevereiro de 2016", mas se CurrentCulture estiver definida como "es-ES" (espanhol, Espanha) a saída será "jueves, 18 de febrero de 2016".

Ficheiros de recursos

NOTA:ResX Viewer and Editor fornece um mecanismo alternativo para trabalhar com arquivos de recursos usando o Visual Studio Code.

Um arquivo de recurso é um mecanismo útil para separar cadeias de caracteres localizáveis do código. As cadeias de caracteres traduzidas para o idioma não padrão são isoladas em arquivos de recursos .resx . Por exemplo, talvez você queira criar um arquivo de recurso espanhol chamado Welcome.es.resx contendo cadeias de caracteres traduzidas. "es" é o código da língua espanhola. Para criar este arquivo de recurso no Visual Studio:

1. No Gerenciador de Soluções, clique com o botão direito do mouse na pasta que conterá o arquivo de recurso e selecione Adicionar>Novo Item.

   

2. Na caixa Pesquisar modelos instalados , digite "recurso" e nomeie o arquivo.

   

3. Insira o valor da chave (cadeia de caracteres nativa) na coluna Nome e a cadeia de caracteres traduzida na coluna Valor .

   

   Visual Studio mostra o arquivo Welcome.es.resx .

   

Nomeação de ficheiros de recursos

Os recursos são nomeados pelo nome completo do tipo da sua classe menos o nome da assemblagem. Por exemplo, um recurso francês em um projeto cujo assembly principal é LocalizationWebsite.Web.dll para a classe LocalizationWebsite.Web.Startup seria chamado Startup.fr.resx. Um recurso para a classe LocalizationWebsite.Web.Controllers.HomeController seria chamado Controllers.HomeController.fr.resx. Se o namespace da classe de destino não for o mesmo que o nome do assembly, será necessário o nome completo do tipo. Por exemplo, no projeto de exemplo, um recurso para o tipo ExtraNamespace.Tools seria chamado ExtraNamespace.Tools.fr.resx.

No projeto de exemplo, o método ConfigureServices define ResourcesPath como "Resources", portanto, o caminho relativo do projeto para o arquivo de recurso francês do controlador Home é Resources/Controllers.HomeController.fr.resx. Como alternativa, você pode usar pastas para organizar arquivos de recursos. Para o controlador doméstico, o caminho seria Resources/Controllers/HomeController.fr.resx. Se você não usar a ResourcesPath opção, o arquivo .resx irá para o diretório base do projeto. O arquivo de recurso para HomeController seria chamado Controllers.HomeController.fr.resx. A escolha de usar a convenção de nomenclatura por ponto ou por caminho depende de como pretendes organizar os teus ficheiros de recursos.

Nome do recurso	Nomeação de ponto ou caminho
Recursos/Controllers.HomeController.fr.resx	Ponto
Recursos/Controladores/HomeController.fr.resx	Caminho

Os ficheiros de recursos que usam @inject IViewLocalizer nas Razor vistas seguem um padrão semelhante. O ficheiro de recursos para uma visualização pode ser nomeado através de nomes de ponto ou de caminho. Razor Os arquivos de recursos de exibição imitam o caminho do arquivo de exibição associado. Supondo que definimos o ResourcesPath como "Recursos", o arquivo de recurso francês associado à Views/Home/About.cshtml exibição pode ser um dos seguintes:

• Recursos/Visualizações/Home/About.fr.resx

• Recursos/Visualizações.Home.Sobre.fr.resx

Se não usar a ResourcesPath opção, o ficheiro .resx para uma vista estará localizado na mesma pasta que a vista.

RootNamespaceAttribute

O RootNamespaceAttribute atributo fornece o namespace raiz de um assembly quando o namespace raiz de um assembly é diferente do nome do assembly.

Advertência

Isso pode ocorrer quando o nome de um projeto não é um identificador .NET válido. Por exemplo, my-project-name.csproj usará o namespace my_project_name raiz e o nome my-project-name do assembly, levando a esse erro.

Se o namespace raiz de um assembly for diferente do nome do assembly:

• A localização não funciona por padrão.
• A localização falha devido à forma como os recursos são pesquisados dentro do componente. RootNamespace é um valor de tempo de compilação que não está disponível para o processo de execução.

Se o RootNamespace for diferente do AssemblyName, inclua o seguinte em AssemblyInfo.cs (com valores de parâmetros substituídos pelos valores reais):

using System.Reflection;
using Microsoft.Extensions.Localization;

[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]

O código anterior permite a resolução bem-sucedida de arquivos resx.

Comportamento de substituição da cultura

Ao procurar um recurso, a localização recorre a um "retrocesso cultural". A partir da cultura solicitada, se não for encontrada, ela reverte para a cultura mãe dessa cultura. A título de comentário, a propriedade CultureInfo.Parent representa a cultura de origem. Isso geralmente (mas nem sempre) significa remover o significante nacional do código de língua e cultura. Por exemplo, o dialeto do espanhol falado no México é "es-MX". Tem o parente "es", espanhol não específico de nenhum país.

Imagine que o seu site recebe um pedido de um recurso web de "Bem-vindo" com base na cultura "fr-CA". O sistema de localização procura os seguintes recursos, em ordem, e seleciona a primeira correspondência:

• Bem-vindo.fr-CA.resx
• Bem-vindo.fr.resx
• Welcome.resx (se o NeutralResourcesLanguage for "fr-CA")

Por exemplo, se você remover o designador de cultura ".fr" e tiver a cultura definida como francês, o arquivo de recurso padrão será lido e as cadeias de caracteres serão localizadas. O Gerenciador de recursos designa um recurso padrão ou de fallback para quando nada atende à cultura solicitada. Se você quiser apenas retornar a chave quando faltar um recurso para a cultura solicitada, você não deve ter um arquivo de recurso padrão.

Gerar arquivos de recursos com o Visual Studio

Se você criar um arquivo de recurso no Visual Studio sem uma cultura no nome do arquivo (por exemplo, Welcome.resx), o Visual Studio criará uma classe C# com uma propriedade para cada cadeia de caracteres. Isso geralmente não é o que você quer com ASP.NET Core. Normalmente, você não tem um arquivo de recurso .resx padrão (um arquivo .resx sem o nome da cultura). Sugerimos que você crie o arquivo .resx com um nome de cultura (por exemplo , Welcome.fr.resx). Quando você cria um arquivo .resx com um nome de cultura, o Visual Studio não gera o arquivo de classe.

Adicionar outras culturas

Cada combinação de idioma e cultura (diferente do idioma padrão) requer um arquivo de recurso exclusivo. Você cria arquivos de recursos para diferentes culturas e localidades criando novos arquivos de recursos nos quais os códigos de idioma fazem parte do nome do arquivo (por exemplo, en-us, fr-cae en-gb). Esses códigos são colocados entre o nome do arquivo e a extensão de arquivo .resx , como em Bem-vindo.es-MX.resx (Espanhol/México).

Próximos passos

A localização de um aplicativo também envolve as seguintes tarefas:

• Torne o conteúdo do aplicativo localizável.
• Implementar uma estratégia para selecionar o idioma/cultura para cada solicitação

Recursos adicionais

• Provedor de cultura para URLs utilizando o middleware como filtros no ASP.NET Core
• Aplicando o RouteDataRequest CultureProvider globalmente com middleware como filtros
• Globalização e localização no ASP.NET Core
• Tornar o conteúdo de um aplicativo ASP.NET Core localizável
• Estratégias para selecionar idioma e cultura em um aplicativo ASP.NET Core localizado
• Solucionar problemas de localização do ASP.NET Core
• Globalização e localização de aplicativos .NET
• projeto Localization.StarterWeb usado no artigo.
• Recursos em ficheiros .resx
• Localização & Genéricos