Implementar uma estratégia para selecionar o idioma/cultura de cada solicitação em um aplicativo ASP.NET Core localizado

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

Uma tarefa para localizar um aplicativo é implementar uma estratégia para selecionar a cultura apropriada para cada resposta retornada pelo aplicativo.

Configurar middleware de localização

A cultura atual em uma solicitação é definida no Middleware de localização. O middleware de localização é habilitado no Program.cs. O middleware de localização precisa ser configurado antes de qualquer middleware que possa verificar a cultura de solicitação (por exemplo, app.UseMvcWithDefaultRoute()).

builder.Services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[] { "en-US", "fr" };
    options.SetDefaultCulture(supportedCultures[0])
        .AddSupportedCultures(supportedCultures)
        .AddSupportedUICultures(supportedCultures);
});

UseRequestLocalization inicializa um objeto RequestLocalizationOptions. Em cada solicitação, a lista de RequestCultureProvider em RequestLocalizationOptions é enumerada e o primeiro provedor que pode determinar com êxito a cultura de solicitação é usado. Os provedores padrão são obtidos da classe RequestLocalizationOptions:

1. QueryStringRequestCultureProvider
2. CookieRequestCultureProvider
3. AcceptLanguageHeaderRequestCultureProvider

A lista padrão é apresentada do mais específico ao menos específico. Mais adiante neste artigo, você verá como alterar a ordem e até mesmo adicionar um provedor de cultura personalizado. Se nenhum dos provedores pode determinar a cultura de solicitação, o DefaultRequestCulture é usado.

QueryStringRequestCultureProvider

Alguns aplicativos usarão uma cadeia de caracteres de consulta para definir a CultureInfo. Para aplicativos que usam a abordagem do cabeçalho Accept-Language ou cookie, a adição de uma cadeia de caracteres de consulta à URL é útil para depurar e testar o código. Por padrão, o QueryStringRequestCultureProvider é registrado como o primeiro provedor de localização na lista RequestCultureProvider. Passe os parâmetros culture e ui-culture da cadeia de caracteres de consulta. O seguinte exemplo define a cultura específica (idioma e região) como espanhol/México:

http://localhost:5000/?culture=es-MX&ui-culture=es-MX

Se apenas culture ou ui-culture for passado, o provedor de cadeia de caracteres de consulta definirá os dois valores usando o que foi passado. Por exemplo, a definição apenas da cultura definirá a Culture e a UICulture:

http://localhost:5000/?culture=es-MX

CookieRequestCultureProvider

Em geral, aplicativos de produção fornecerão um mecanismo para definir a cultura com cookie de cultura do ASP.NET Core. Use o método MakeCookieValue para criar um cookie.

A CookieRequestCultureProvider DefaultCookieName retorna o nome padrão cookie usado para rastrear as informações de cultura preferidas do usuário. O nome padrão cookie é .AspNetCore.Culture.

O formato do cookie é c=%LANGCODE%|uic=%LANGCODE%, em que c é Culture e uic é UICulture, por exemplo:

c=en-UK|uic=en-US

Se apenas uma das informações de cultura ou cultura da interface do usuário for fornecida, então essa cultura será usada tanto para as informações de cultura quanto para a cultura da interface do usuário.

O cabeçalho HTTP Accept-Language

O cabeçalho Accept-Language é configurável na maioria dos navegadores e originalmente foi criado para especificar o idioma do usuário. Essa configuração indica que o navegador foi definido para enviar ou herdou do sistema operacional subjacente. O cabeçalho HTTP Accept-Language de uma solicitação do navegador não é uma maneira infalível de detectar o idioma preferencial do usuário (consulte Definindo preferências de idioma em um navegador). Um aplicativo de produção deve incluir uma maneira para que um usuário personalize sua opção de cultura.

Definir o cabeçalho HTTP Accept-Language no Edge

1. Pesquisar Configurações para Idiomas preferidos.

2. Os idiomas preferidos estão listados na caixa Idiomas preferidos.

3. Selecione Adicionar idiomas para adicionar à lista.

4. Selecione Mais ações... ao lado de um idioma para alterar a ordem de preferência.

O cabeçalho HTTP Content-Language

O cabeçalho da entidade Content-Language :

• É usado para descrever os idiomas destinados ao público-alvo.
• Permite que um usuário se diferencie de acordo com o idioma preferido dos próprios usuários.

Cabeçalhos de entidade são usados em solicitações HTTP e respostas.

O cabeçalho Content-Language pode ser adicionado definindo a propriedade ApplyCurrentCultureToResponseHeaders.

Adicionando o cabeçalho Content-Language:

• Permite o RequestLocalizationMiddleware definir o cabeçalho Content-Language com o CurrentUICulture.
• Elimina a necessidade de definir o cabeçalho de resposta Content-Language explicitamente.

app.UseRequestLocalization(new RequestLocalizationOptions
{
    ApplyCurrentCultureToResponseHeaders = true
});

Aplicar o RouteDataRequest CultureProvider

O RouteDataRequestCultureProvider define a cultura com base no valor do valor da rota culture. Confira o provedor de cultura de URLs usando middlewares como filtros para obter informações sobre:

• Uso do middleware como o recurso de filtros do ASP.NET Core.
• Como usar RouteDataRequestCultureProvider para definir a cultura de um aplicativo a partir da URL.

Confira Aplicar o RouteDataRequest CultureProvider globalmente com middlewares como filtros para obter informações sobre como aplicar o RouteDataRequestCultureProvider globalmente.

Usar um provedor personalizado

Suponha que você deseje permitir que os clientes armazenem seus idiomas e culturas nos bancos de dados. Você pode escrever um provedor para pesquisar esses valores para o usuário. O seguinte código mostra como adicionar um provedor personalizado:

private const string enUSCulture = "en-US";

services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[]
    {
        new CultureInfo(enUSCulture),
        new CultureInfo("fr")
    };

    options.DefaultRequestCulture = new RequestCulture(culture: enUSCulture, uiCulture: enUSCulture);
    options.SupportedCultures = supportedCultures;
    options.SupportedUICultures = supportedCultures;

    options.AddInitialRequestCultureProvider(new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return await Task.FromResult(new ProviderCultureResult("en"));
    }));
});

Use RequestLocalizationOptions para adicionar ou remover provedores de localização.

Alterar a ordem dos provedores de cultura de solicitação

RequestLocalizationOptions tem três provedores de cultura de solicitação padrão: QueryStringRequestCultureProvider, CookieRequestCultureProvider e AcceptLanguageHeaderRequestCultureProvider. Use a propriedade RequestLocalizationOptions.RequestCultureProviders para mudar a ordem desses provedores, conforme mostrado abaixo:

    app.UseRequestLocalization(options =>
    {
        var questStringCultureProvider = options.RequestCultureProviders[0];    
        options.RequestCultureProviders.RemoveAt(0);
        options.RequestCultureProviders.Insert(1, questStringCultureProvider);
    });

No exemplo anterior, a ordem de QueryStringRequestCultureProvider e CookieRequestCultureProvider é alternada, portanto, o RequestLocalizationMiddleware procura as culturas dos cookies primeiro e, em seguida, a cadeia de caracteres de consulta.

Como mencionado anteriormente, adicione um provedor personalizado por meio do AddInitialRequestCultureProvider, que define a ordem para 0, para esse provedor tenha precedência sobre os outros.

Cultura de substituição do usuário

A propriedade RequestLocalizationOptions.CultureInfoUseUserOverride permite que o aplicativo decida se deve ou não usar configurações não padrão do Windows para as propriedades CultureInfo, DateTimeFormat e NumberFormat. Isso não afeta o Linux. Isso corresponde diretamente a UseUserOverride.

    app.UseRequestLocalization(options =>
    {
        options.CultureInfoUseUserOverride = false;
    });

Definir a cultura de forma programática

Este projeto de exemplo Localization.StarterWeb no GitHub contém a interface do usuário para definir a Culture. O arquivo Views/Shared/_SelectLanguagePartial.cshtml permite que você selecione a cultura na lista de culturas compatíveis:

@using Microsoft.AspNetCore.Builder
@using Microsoft.AspNetCore.Http.Features
@using Microsoft.AspNetCore.Localization
@using Microsoft.AspNetCore.Mvc.Localization
@using Microsoft.Extensions.Options

@inject IViewLocalizer Localizer
@inject IOptions<RequestLocalizationOptions> LocOptions

@{
    var requestCulture = Context.Features.Get<IRequestCultureFeature>();
    var cultureItems = LocOptions.Value.SupportedUICultures
        .Select(c => new SelectListItem { Value = c.Name, Text = c.DisplayName })
        .ToList();
    var returnUrl = string.IsNullOrEmpty(Context.Request.Path) ? "~/" : $"~{Context.Request.Path.Value}";
}

<div title="@Localizer["Request culture provider:"] @requestCulture?.Provider?.GetType().Name">
    <form id="selectLanguage" asp-controller="Home" 
          asp-action="SetLanguage" asp-route-returnUrl="@returnUrl" 
          method="post" class="form-horizontal" role="form">
        <label asp-for="@requestCulture.RequestCulture.UICulture.Name">@Localizer["Language:"]</label> <select name="culture"
          onchange="this.form.submit();"
          asp-for="@requestCulture.RequestCulture.UICulture.Name" asp-items="cultureItems">
        </select>
    </form>
</div>

O arquivo Views/Shared/_SelectLanguagePartial.cshtml é adicionado à seção footer do arquivo de layout para que ele fique disponível para todos os exibições:

<div class="container body-content" style="margin-top:60px">
    @RenderBody()
    <hr>
    <footer>
        <div class="row">
            <div class="col-md-6">
                <p>&copy; @System.DateTime.Now.Year - Localization</p>
            </div>
            <div class="col-md-6 text-right">
                @await Html.PartialAsync("_SelectLanguagePartial")
            </div>
        </div>
    </footer>
</div>

O método SetLanguage define o cookie de cultura.

[HttpPost]
public IActionResult SetLanguage(string culture, string returnUrl)
{
    Response.Cookies.Append(
        CookieRequestCultureProvider.DefaultCookieName,
        CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(culture)),
        new CookieOptions { Expires = DateTimeOffset.UtcNow.AddYears(1) }
    );

    return LocalRedirect(returnUrl);
}

Não é possível conectar o _SelectLanguagePartial.cshtml ao código de exemplo para este projeto. O projeto Localization.StarterWeb no GitHub contém o código para o fluxo do RequestLocalizationOptions para uma parcial do Razor por meio do contêiner de Injeção de Dependência.

Dados de rota de dados e cadeias de caracteres de consulta

Confira Comportamento de globalização de dados de rota e cadeias de caracteres de consulta de model binding.

Próximas etapas

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

• Torne o conteúdo do aplicativo localizável.
• Fornecer recursos localizados para as culturas e os idiomas aos quais o aplicativo dá suporte

Recursos adicionais

• Provedor de cultura de URL usando o middleware como filtros no ASP.NET Core
• Aplicando o CultureProvider do RouteDataRequest globalmente com middleware como filtros
• Globalização e localização no ASP.NET Core
• Tornar localizável o conteúdo de um aplicativo ASP.NET Core
• Fornecer recursos localizados para idiomas e culturas em um aplicativo ASP.NET Core
• Solucionar problemas de localização no ASP.NET Core
• Globalizando e localizando aplicativos do .NET
• O projeto Localization.StarterWeb usado no artigo.
• Recursos em arquivos .resx
• Kit de Ferramentas de Aplicativo Multilíngue da Microsoft
• Localização e genéricos