Implementar uma estratégia para selecionar o idioma/cultura para 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 que o aplicativo retorna.

Configurar middleware de localização

A cultura atual em uma solicitação é definida no Middleware de localização. O middleware de localização está habilitado em Program.cs. O middleware de localização deve 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 RequestLocalizationOptions objeto. Em cada solicitação, a lista de RequestCultureProvider no RequestLocalizationOptions é enumerada, e o primeiro provedor que pode determinar com êxito a cultura da solicitação é utilizado. Os provedores padrão vêm da RequestLocalizationOptions classe:

1. QueryStringRequestCultureProvider
2. CookieRequestCultureProvider
3. AcceptLanguageHeaderRequestCultureProvider

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

QueryStringRequestCultureProvider

Alguns aplicativos usarão uma cadeia de caracteres de consulta para definir o CultureInfo. Para aplicativos que usam a cookie abordagem de cabeçalho ou Accept-Language, adicionar uma cadeia de caracteres de consulta à URL é útil para depurar e testar código. Por padrão, o QueryStringRequestCultureProvider é registrado como o primeiro provedor de localização na RequestCultureProvider lista. Você passa os parâmetros culture da cadeia de caracteres de consulta e ui-culture. O exemplo a seguir 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 da cadeia de consulta definirá ambos os valores usando o valor recebido. Por exemplo, definir apenas a cultura definirá o Culture e o UICulture:

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

CookieRequestCultureProvider (Provedor de Cultura Solicitada por Cookie)

Os aplicativos de produção geralmente fornecem um mecanismo para definir a cultura com a cultura ASP.NET Core cookie. Use o MakeCookieValue método para criar um cookie.

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

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

c=en-UK|uic=en-US

Se apenas uma das culturas é fornecida e a outra está vazia, a cultura fornecida é usada tanto para a cultura quanto para a cultura da interface do usuário.

O cabeçalho HTTP Accept-Language

O cabeçalhoAccept-Language é configurável na maioria dos navegadores e foi originalmente destinado a especificar o idioma do usuário. Essa configuração indica o que o navegador foi configurado 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 detetar o idioma preferido do usuário (consulte Definindo preferências de idioma em um navegador). Um aplicativo de produção deve incluir uma maneira de um usuário personalizar sua escolha de cultura.

Definir o cabeçalho HTTP Accept-Language no Edge

1. Procure Configurações por 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 de linguagem de conteúdo

O cabeçalho da entidade Content-Language :

• É utilizado para descrever a(s) língua(s) destinada(s) ao público.
• Permite que um usuário se diferencie de acordo com o idioma preferido do usuário.

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

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

Adicionando o Content-Language cabeçalho:

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

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

Aplicar o RouteDataRequest CultureProvider

O RouteDataRequestCultureProvider define a cultura com base no valor da rota culture. Consulte Provedor de cultura de URL usando middleware como filtros para obter informações sobre:

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

Consulte Aplicando o RouteDataRequest CultureProvider globalmente com middleware como filtros para obter informações sobre como aplicar o RouteDataRequestCultureProvider globalmente.

Usar um provedor personalizado

Suponha que você queira permitir que seus clientes armazenem seu idioma e cultura em seus bancos de dados. Você pode escrever um provedor para procurar esses valores para o usuário. O código a seguir 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 no pedido

RequestLocalizationOptions tem três provedores de cultura de solicitação padrão: QueryStringRequestCultureProvider, CookieRequestCultureProvidere AcceptLanguageHeaderRequestCultureProvider. Use RequestLocalizationOptions.RequestCultureProviders a propriedade para alterar 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, de modo que RequestLocalizationMiddleware procura primeiro as culturas nos cookies e, em seguida, na string de consulta.

Como mencionado anteriormente, adicione um provedor personalizado através de AddInitialRequestCultureProvider, que define a ordem para 0, de modo que este provedor tenha precedência sobre os outros.

Cultura de prevalência do utilizador

A propriedade RequestLocalizationOptions.CultureInfoUseUserOverride permite que o aplicativo decida se deseja ou não usar configurações não padrão do Windows para as CultureInfoDateTimeFormat propriedades e NumberFormat . Isso não tem impacto no Linux. Isso corresponde diretamente a UseUserOverride.

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

Defina a cultura programaticamente

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

@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 Views/Shared/_SelectLanguagePartial.cshtml arquivo é adicionado à footer seção do arquivo de layout para que esteja disponível para todas as visualizaçõ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 SetLanguage método define a cultura cookie.

[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 ligar o _SelectLanguagePartial.cshtml no código de exemplo para este projeto. O projeto Localization.StarterWeb no GitHub tem código para transferir RequestLocalizationOptions para um Razor parcial através do contentor de Injeção de Dependências.

Dados de rota de vinculação de modelo e cadeias de caracteres de consulta

Consulte Comportamento de globalização de dados de rota de vinculação de modelo e cadeias de caracteres de consulta.

Próximos passos

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

• Torne o conteúdo do aplicativo localizável.
• Fornecer recursos localizados para os idiomas e culturas suportados pelo aplicativo

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
• Fornecer recursos localizados para idiomas e culturas em um aplicativo ASP.NET Core
• 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

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 que o aplicativo retorna.

Configurar middleware de localização

A cultura atual em uma solicitação é definida no Middleware de localização. O middleware de localização está habilitado em Program.cs. O middleware de localização deve 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 RequestLocalizationOptions objeto. Em cada solicitação, a lista de RequestCultureProvider no RequestLocalizationOptions é enumerada, e o primeiro provedor que pode determinar com êxito a cultura da solicitação é utilizado. Os provedores padrão vêm da RequestLocalizationOptions classe:

1. QueryStringRequestCultureProvider
2. CookieRequestCultureProvider
3. AcceptLanguageHeaderRequestCultureProvider

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

QueryStringRequestCultureProvider

Alguns aplicativos usarão uma cadeia de caracteres de consulta para definir o CultureInfo. Para aplicativos que usam a cookie abordagem de cabeçalho ou Accept-Language, adicionar uma cadeia de caracteres de consulta à URL é útil para depurar e testar código. Por padrão, o QueryStringRequestCultureProvider é registrado como o primeiro provedor de localização na RequestCultureProvider lista. Você passa os parâmetros culture da cadeia de caracteres de consulta e ui-culture. O exemplo a seguir 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 da cadeia de consulta definirá ambos os valores usando o valor recebido. Por exemplo, definir apenas a cultura definirá o Culture e o UICulture:

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

CookieRequestCultureProvider (Provedor de Cultura Solicitada por Cookie)

Os aplicativos de produção geralmente fornecem um mecanismo para definir a cultura com a cultura ASP.NET Core cookie. Use o MakeCookieValue método para criar um cookie.

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

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

c=en-UK|uic=en-US

Se apenas uma das informações culturais ou cultura da interface do usuário for fornecida, a cultura fornecida será usada para ambas as informações culturais e cultura da interface do usuário.

O cabeçalho HTTP Accept-Language

O cabeçalhoAccept-Language é configurável na maioria dos navegadores e foi originalmente destinado a especificar o idioma do usuário. Essa configuração indica o que o navegador foi configurado 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 detetar o idioma preferido do usuário (consulte Definindo preferências de idioma em um navegador). Um aplicativo de produção deve incluir uma maneira de um usuário personalizar sua escolha de cultura.

Definir o cabeçalho HTTP Accept-Language no Edge

1. Procure Configurações por 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 de linguagem de conteúdo

O cabeçalho da entidade Content-Language :

• É utilizado para descrever a(s) língua(s) destinada(s) ao público.
• Permite que um usuário se diferencie de acordo com o idioma preferido do usuário.

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

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

Adicionando o Content-Language cabeçalho:

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

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

Usar um provedor personalizado

Suponha que você queira permitir que seus clientes armazenem seu idioma e cultura em seus bancos de dados. Você pode escrever um provedor para procurar esses valores para o usuário. O código a seguir 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 no pedido

RequestLocalizationOptions tem três provedores de cultura de solicitação padrão: QueryStringRequestCultureProvider, CookieRequestCultureProvidere AcceptLanguageHeaderRequestCultureProvider. Use RequestLocalizationOptions.RequestCultureProviders a propriedade para alterar 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, de modo que RequestLocalizationMiddleware procura primeiro as culturas nos cookies e, em seguida, na string de consulta.

Como mencionado anteriormente, adicione um provedor personalizado através de AddInitialRequestCultureProvider, que define a ordem para 0, de modo que este provedor tenha precedência sobre os outros.

Defina a cultura programaticamente

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

@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 Views/Shared/_SelectLanguagePartial.cshtml arquivo é adicionado à footer seção do arquivo de layout para que esteja disponível para todas as visualizaçõ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 SetLanguage método define a cultura cookie.

[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 ligar o _SelectLanguagePartial.cshtml no código de exemplo para este projeto. O projeto Localization.StarterWeb no GitHub tem código para transferir RequestLocalizationOptions para um Razor parcial através do contentor de Injeção de Dependências.

Dados de rota de vinculação de modelo e cadeias de caracteres de consulta

Consulte Comportamento de globalização de dados de rota de vinculação de modelo e cadeias de caracteres de consulta.

Próximos passos

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

• Torne o conteúdo do aplicativo localizável.
• Fornecer recursos localizados para os idiomas e culturas suportados pelo aplicativo

Recursos adicionais

• Globalização e localização no ASP.NET Core
• Tornar o conteúdo de um aplicativo ASP.NET Core localizável
• Fornecer recursos localizados para idiomas e culturas em um aplicativo ASP.NET Core
• 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

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

Uma tarefa para localizar um aplicativo é implementar uma estratégia para selecionar a cultura apropriada para cada resposta que o aplicativo retorna.

Configurar middleware de localização

A cultura atual em uma solicitação é definida no Middleware de localização. O middleware de localização é ativado no método Startup.Configure. O middleware de localização deve ser configurado antes de qualquer middleware que possa verificar a cultura de solicitação (por exemplo, app.UseMvcWithDefaultRoute()).

var supportedCultures = new[] { "en-US", "fr" };
var localizationOptions = new RequestLocalizationOptions().SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

UseRequestLocalization Inicializa um RequestLocalizationOptions objeto. Em cada solicitação, a lista de RequestCultureProvider no RequestLocalizationOptions é enumerada, e o primeiro provedor que pode determinar com êxito a cultura da solicitação é utilizado. Os provedores padrão vêm da RequestLocalizationOptions classe:

1. QueryStringRequestCultureProvider
2. CookieRequestCultureProvider
3. AcceptLanguageHeaderRequestCultureProvider

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

QueryStringRequestCultureProvider

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

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

Se você passar apenas um dos dois (culture ou ui-culture), o provedor de cadeia de caracteres de consulta definirá ambos os valores usando o que você passou. Por exemplo, definir apenas a cultura definirá o Culture e o UICulture:

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

CookieRequestCultureProvider (Provedor de Cultura Solicitada por Cookie)

Os aplicativos de produção geralmente fornecem um mecanismo para definir a cultura com a cultura ASP.NET Core cookie. Use o MakeCookieValue método para criar um cookie.

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

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

c=en-UK|uic=en-US

Se você especificar apenas uma das informações de cultura e a cultura da interface do usuário, a cultura especificada será usada para as informações de cultura e a cultura da interface do usuário.

O cabeçalho HTTP Accept-Language

O cabeçalhoAccept-Language é configurável na maioria dos navegadores e foi originalmente destinado a especificar o idioma do usuário. Essa configuração indica o que o navegador foi configurado 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 detetar o idioma preferido do usuário (consulte Definindo preferências de idioma em um navegador). Um aplicativo de produção deve incluir uma maneira de um usuário personalizar sua escolha de cultura.

Definir o cabeçalho HTTP Accept-Language no Edge

1. Procure Configurações por 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 de linguagem de conteúdo

O cabeçalho da entidade Content-Language :

• É utilizado para descrever a(s) língua(s) destinada(s) ao público.
• Permite que um usuário se diferencie de acordo com o idioma preferido do usuário.

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

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

Adicionando o Content-Language cabeçalho:

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

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

Usar um provedor personalizado

Suponha que você queira permitir que seus clientes armazenem seu idioma e cultura em seus bancos de dados. Você pode escrever um provedor para procurar esses valores para o usuário. O código a seguir 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 no pedido

RequestLocalizationOptions tem três provedores de cultura de solicitação padrão: QueryStringRequestCultureProvider, CookieRequestCultureProvidere AcceptLanguageHeaderRequestCultureProvider. Use RequestLocalizationOptions.RequestCultureProviders a propriedade para alterar 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, de modo que RequestLocalizationMiddleware procura primeiro as culturas nos cookies e, em seguida, na string de consulta.

Como mencionado anteriormente, adicione um provedor personalizado através de AddInitialRequestCultureProvider, que define a ordem para 0, de modo que este provedor tenha precedência sobre os outros.

Defina a cultura programaticamente

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

@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 Views/Shared/_SelectLanguagePartial.cshtml arquivo é adicionado à footer seção do arquivo de layout para que esteja disponível para todas as visualizaçõ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 SetLanguage método define a cultura cookie.

[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 ligar o _SelectLanguagePartial.cshtml no código de exemplo para este projeto. O projeto Localization.StarterWeb no GitHub tem código para transferir RequestLocalizationOptions para um Razor parcial através do contentor de Injeção de Dependências.

Dados de rota de vinculação de modelo e cadeias de caracteres de consulta

Consulte Comportamento de globalização de dados de rota de vinculação de modelo e cadeias de caracteres de consulta.

Próximos passos

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

• Torne o conteúdo do aplicativo localizável.
• Fornecer recursos localizados para os idiomas e culturas suportados pelo aplicativo

Recursos adicionais

• Globalização e localização no ASP.NET Core
• Tornar o conteúdo de um aplicativo ASP.NET Core localizável
• Fornecer recursos localizados para idiomas e culturas em um aplicativo ASP.NET Core
• 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