Implementar una estrategia para seleccionar el idioma o la referencia cultural de cada solicitud en una aplicación de ASP.NET Core localizada

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

Una de las tareas para localizar una aplicación es implementar una estrategia destinada a seleccionar la referencia cultural adecuada para cada respuesta que devuelve la aplicación.

Configuración del middleware de localización

La referencia cultural actual de una solicitud se establece en el software intermedio de localización. El middleware de localización se habilita en Program.cs. El middleware de localización debe configurarse antes que cualquier software intermedio que pueda comprobar la referencia cultural de la solicitud (por ejemplo, app.UseMvcWithDefaultRoute()).

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

UseRequestLocalization inicializa un objeto RequestLocalizationOptions. En todas las solicitudes, se enumera la lista de RequestCultureProvider en RequestLocalizationOptions y se usa el primer proveedor que puede determinar correctamente la referencia cultural de la solicitud. Los proveedores predeterminados proceden de la clase RequestLocalizationOptions:

1. QueryStringRequestCultureProvider
2. CookieRequestCultureProvider
3. AcceptLanguageHeaderRequestCultureProvider

La lista predeterminada va de más específico a menos específico. Más adelante en el artículo verá cómo puede cambiar el orden e incluso agregar un proveedor de referencia cultural personalizado. Si ninguno de los proveedores puede determinar la referencia cultural de la solicitud, se usa DefaultRequestCulture.

QueryStringRequestCultureProvider

Algunas aplicaciones usarán una cadena de consulta para establecer CultureInfo. Para las aplicaciones que usan el método de cookie o de encabezado Accept-Language, es útil agregar una cadena de consulta a la dirección URL para depurar y probar el código. De forma predeterminada, QueryStringRequestCultureProvider está registrado como primer proveedor de localización en la lista RequestCultureProvider. Debe pasar los parámetros de cadena de consulta culture y ui-culture. En el ejemplo siguiente, la referencia cultural específica (idioma y región) se establece en español (México):

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

Si solo se pasa culture o ui-culture, el proveedor de cadenas de consulta establece ambos valores mediante el pasado. Por ejemplo, si solo establece la referencia cultural, se establecerán Culture y UICulture:

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

CookieRequestCultureProvider

Las aplicaciones de producción suelen proporcionar un mecanismo para establecer la referencia cultural con la cookie de la referencia cultural de ASP.NET Core. Use el método MakeCookieValue para crear una cookie.

CookieRequestCultureProviderDefaultCookieName devuelve el nombre de cookie predeterminado usado para realizar un seguimiento de la información de la referencia cultural preferida del usuario. El nombre de cookie predeterminado es .AspNetCore.Culture.

El formato de la cookie es c=%LANGCODE%|uic=%LANGCODE%, donde c es Culture y uic es UICulture, por ejemplo:

c=en-UK|uic=en-US

Si solo se proporciona una de las referencias culturales o referencias culturales de la interfaz de usuario, la referencia proporcionada se usa tanto para la información de referencia cultural como para la de la interfaz de usuario.

Encabezado HTTP Accept-Language

El encabezado Accept-Language se puede establecer en la mayoría de los exploradores y está diseñado inicialmente para especificar el idioma del usuario. Este valor indica qué debe enviar el explorador o qué ha heredado del sistema operativo subyacente. El encabezado HTTP Accept-Language de una solicitud del explorador no es un método infalible para detectar el idioma preferido del usuario (vea Setting language preferences in a browser [Establecer las preferencias de idioma en un explorador]). Una aplicación de producción debe ofrecer al usuario una manera de personalizar su opción de referencia cultural.

Establecer el encabezado HTTP Accept-Language en Edge

1. Busque Configuración para Idiomas preferidos.

2. Los idiomas preferidos aparecen en el cuadro Idiomas preferidos.

3. Seleccione Agregar idiomas para agregar a la lista.

4. Seleccione Más acciones... junto a un idioma para cambiar el orden de preferencia.

El encabezado HTTP Content-Language

El encabezado de entidad Content-Language:

• Se usa para describir los lenguajes destinados a la audiencia.
• Permite a un usuario diferenciar según el propio idioma preferido de los usuarios.

Los encabezados de entidad se usan en las solicitudes y respuestas HTTP.

Se puede agregar el encabezado Content-Language mediante el establecimiento de la propiedad ApplyCurrentCultureToResponseHeaders.

La adición del encabezado Content-Language:

• Permite que el RequestLocalizationMiddleware establezca el encabezado Content-Language con el CurrentUICulture.
• Elimina la necesidad de establecer el encabezado de respuesta Content-Language explícitamente.

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

Aplicar RouteDataRequest CultureProvider

RouteDataRequestCultureProvider establece la referencia cultural basada en el valor de la ruta culture. Consulte Proveedor de referencia cultural de direcciones URL mediante middleware como filtros para obtener información sobre:

• Usar el middleware como característica de filtros de ASP.NET Core.
• Cómo usar RouteDataRequestCultureProvider para establecer la referencia cultural de una aplicación desde la dirección URL.

Consulte Aplicación global de RouteDataRequest CultureProvider con middleware como filtros para obtener información sobre cómo aplicar globalmente RouteDataRequestCultureProvider.

Usar un proveedor personalizado

Imagine que quiere permitir que los clientes almacenen su idioma y su referencia cultural en las bases de datos. Puede escribir un proveedor para que busque estos valores para el usuario. En el código siguiente se muestra cómo agregar un proveedor 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 agregar o quitar proveedores de localización.

Cambio del orden de los proveedores de referencia cultural de la solicitud

RequestLocalizationOptions tiene tres proveedores de referencia cultural para las solicitudes: QueryStringRequestCultureProvider, CookieRequestCultureProvider y AcceptLanguageHeaderRequestCultureProvider. Use la propiedad RequestLocalizationOptions.RequestCultureProviders para cambiar el orden de estos proveedores, como se muestra a continuación:

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

En el ejemplo anterior, el orden de QueryStringRequestCultureProvider y CookieRequestCultureProvider está intercambiado, por lo que RequestLocalizationMiddleware busca primero las referencias culturales de cookies y, después, la cadena de consulta.

Como se mencionó anteriormente, la adición de un proveedor personalizado a través de AddInitialRequestCultureProvider establece el orden en 0, por lo que este proveedor tiene prioridad sobre los demás.

Referencia cultural de invalidación de usuario

La propiedad RequestLocalizationOptions.CultureInfoUseUserOverride permite a la aplicación decidir si se debe usar o no la configuración no predeterminada de Windows para las propiedades CultureInfoDateTimeFormat y NumberFormat. Esto no afecta a Linux. Esto corresponde directamente a UseUserOverride.

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

Establecer la referencia cultural mediante programación

Este proyecto Localization.StarterWeb de ejemplo de GitHub contiene una interfaz de usuario para establecer el valor Culture. El archivo Views/Shared/_SelectLanguagePartial.cshtml le permite seleccionar la referencia cultural de la lista de referencias culturales admitidas:

@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>

El archivo Views/Shared/_SelectLanguagePartial.cshtml se agrega a la sección footer del archivo de diseño para que esté disponible para todas las vistas:

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

El método SetLanguage establece la cookie de la referencia cultural.

[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);
}

No se puede conectar el archivo _SelectLanguagePartial.cshtml con código de ejemplo para este proyecto. El proyecto Localization.StarterWeb de GitHub tiene código para enviar RequestLocalizationOptions a una vista parcial de Razor a través del contenedor de inserción de dependencias.

Datos de ruta y cadenas de consulta de enlace de modelos

Vea Comportamiento de globalización de los datos de ruta de enlace de modelos y las cadenas de consulta.

Pasos siguientes

La localización de una aplicación también implica las tareas siguientes:

• Hacer que el contenido de la aplicación sea localizable
• Proporcionar recursos localizados para los idiomas y las referencias culturales que admite la aplicación

Recursos adicionales

• Proveedor de referencia cultural de direcciones URL mediante middleware como filtros en ASP.NET Core
• Aplicación global de RouteDataRequest CultureProvider con middleware como filtros
• Globalización y localización en ASP.NET Core
• Hacer que el contenido de una aplicación de ASP.NET Core sea localizable
• Proporcionar recursos localizados para idiomas y referencias culturales en una aplicación de ASP.NET Core
• Solución de problemas de localización de ASP.NET Core
• Globalización y localización de aplicaciones .NET
• Proyecto Localization.StarterWeb usado en el artículo
• Recursos en archivos .resx
• Kit de herramientas de aplicaciones multilingüe de Microsoft
• Localización y genéricos