Saltar al contenido

Internacionalización con ASP.Net Core 6 y 7

Compartir en:

ASP.NET Core es un framework web muy flexible y potente que te permite crear aplicaciones web en diferentes idiomas y culturas, algo básico para abrir hoy en día tu negocio a internet. Para hacer esto, ASP.NET Core proporciona una forma de establecer y cambiar la cultura de una aplicación. La cultura se utiliza para formatear números, fechas y otros datos según las reglas del idioma seleccionado.

En este artículo nuevo, vamos a ver cómo podemos implementar el Middleware de localización en ASP.NET Core para establecer la cultura y cambiarla en función de ciertos criterios, como el valor de un parámetro en la cadena de consulta, el contenido de una cookie o el encabezado Accept-Language.

El middleware de localización está incluido en el paquete NuGet Microsoft.AspNetCore.Localization, que se incluye por defecto en los proyectos de ASP.NET Core.

Configurando el middleware de localización

Para agregar el Middleware de localización al pipeline de ASP.NET Core, primero debemos crear una instancia de RequestLocalizationOptions y configurarla con las opciones deseadas. Por ejemplo, podemos especificar qué culturas son compatibles y cuál es la cultura predeterminada:

var supportedCultures = new[]
{
    new CultureInfo("en-US"),
    new CultureInfo("es-ES")
};
var options = new RequestLocalizationOptions
{
    DefaultRequestCulture = new RequestCulture("en-US"),
    SupportedCultures = supportedCultures,
    SupportedUICultures = supportedCultures
};

He establecido la cultura predeterminada a «en-US» y que la aplicación admite las culturas «en-US» y «es-ES».

En este caso, he agregado un QueryStringRequestCultureProvider a la colección RequestCultureProviders. Este proveedor buscará los parámetros de la cadena de consulta «culture» y «ui-culture» para determinar la cultura de la solicitud.

También podemos agregar otros proveedores, como el CookieRequestCultureProvider o el AcceptLanguageHeaderRequestCultureProvider. En general, el middleware de localización buscará la cultura en diferentes proveedores en orden, y utilizará la primera cultura que encuentre. Si no se encuentra ninguna cultura válida, se empleará la cultura predeterminada.

Tenéis mucha más info en la docu de Microsoft, que en mi opinión, esta genial ENLACE.

Agregando el middleware al pipeline

Una vez que hemos configurado las opciones de localización, podemos agregar el middleware al pipeline de ASP.NET Core, tarea sencilla:

app.UseRequestLocalization(options);

Esto asegurará que el middleware de localización se ejecute en todas las solicitudes entrantes y que la cultura se establezca correctamente.

Cambiando la cultura de la solicitud

Cuando se usa el middleware RequestLocalizationMiddleware, la cultura de la solicitud se establece de forma automática usando los criterios definidos en el objeto RequestLocalizationOptions. Sin embargo, es posible que en algún punto de la ejecución de nuestra aplicación queramos cambiar la cultura de la solicitud de forma programática. Para ello, podemos emplear el objeto HttpContext (mi gran amigo) que se encuentra disponible en el contexto de la solicitud.

Por ejemplo, supongamos que en una acción de nuestro controlador queremos establecer la cultura de la solicitud a «es-ES». Podemos hacerlo de la siguiente forma:

public IActionResult MiAccion()
{
    HttpContext.Features.Set<IRequestCultureFeature>(new RequestCultureFeature(
        new RequestCulture("es-ES")));
    // Resto del código de la acción
}

Vemos que, estamos utilizando la propiedad Features del objeto HttpContext para establecer una instancia de IRequestCultureFeature, que nos permite establecer la cultura de la solicitud de modo programática.

Personalizando el comportamiento de RequestLocalizationMiddleware

Visto ya, el middleware RequestLocalizationMiddleware emplea por defecto una serie de proveedores de cultura para determinar la cultura de la solicitud. Sin embargo, es posible que queramos personalizar este comportamiento, por ejemplo, para usar otros criterios para determinar la cultura de la solicitud.

Para personalizar el comportamiento de RequestLocalizationMiddleware, podemos usar el objeto RequestLocalizationOptions, que nos permite definir los criterios de cultura que se emplearán. Por ejemplo, supongamos que queremos emplear una cookie para establecer la cultura de la solicitud. Podemos hacerlo de la siguiente forma:

var cookieProvider = new CookieRequestCultureProvider
{
    CookieName = "MyCultureCookie",
    Options = new RequestCultureOptions
    {
        // Lista de culturas soportadas
        SupportedCultures = new List<CultureInfo>
        {
            new CultureInfo("en-US"),
            new CultureInfo("es-ES")
        },
        // Lista de culturas de la interfaz de usuario soportadas
        SupportedUICultures = new List<CultureInfo>
        {
            new CultureInfo("en-US"),
            new CultureInfo("es-ES")
        }
    }
};
var options = new RequestLocalizationOptions
{
    DefaultRequestCulture = new RequestCulture("en-US"),
    RequestCultureProviders = new List<IRequestCultureProvider>
    {
        cookieProvider
    }
};
app.UseRequestLocalization(options);

En el ejemplo, estamos creando una instancia de CookieRequestCultureProvider, que usa una cookie para establecer la cultura de la solicitud. Además, estamos estableciendo la lista de culturas soportadas y la lista de culturas de la interfaz de usuario soportadas en la propiedad Options del proveedor.

Seguido, estamos generando una instancia de RequestLocalizationOptions y estableciendo el proveedor de cultura en la propiedad RequestCultureProviders. En este caso, estamos utilizando el proveedor que acabamos de crear para usar una cookie para establecer la cultura de la solicitud.

Localización de Textos

Bien, ya tenemos nuestras peticiones en el idioma correcto ¿y ahora qué?. Pues necesitamos un sistema para poder determinar (mediante clave-valor) los textos en diferentes idiomas.

El paquete NuGet Microsoft.Extensions.Localization, incluido en Microsoft.AspNetCore.App, ofrece herramientas útiles para facilitar la localización de aplicaciones. En este apartado, veremos cómo acceder a los recursos localizados empleando instancias de IStringLocalizer<T>.

Para acceder a los recursos localizados, primero debemos configurar los servicios del paquete NuGet en la clase Startup. En el método ConfigureServices, agregamos el siguiente código:

services.AddLocalization(options => options.ResourcesPath = "Resources");

En este código, estamos estableciendo la ruta de los recursos en la carpeta /resources del proyecto (la clave valor que he comentado antes).

Los archivos .resx que contienen los recursos localizados deben seguir una convención de nombres. Si estamos implementando recursos localizados para la clase MyClass, el archivo de recursos debe denominarse MyClass.{culture}.resx, por ejemplo MyClass.es-ES.resx.

Si nuestro proyecto se llama MyApp y la clase MyClass se encuentra en un espacio de nombres como MyApp.One, el archivo de recursos debería llamarse One.MyClass.esES.resx.

La cultura puede indicarse con el par cultura-región (como en “es-ES”) o solo cultura (como en “es”). La selección del archivo de recursos seguirá una secuencia en cascada.

Por ejemplo, si la cultura actual es “es-ES”, primero se intentará buscar un archivo específico como /Resources/MyClass.es-ES.resx; si no existe, se intentará con /Resources/MyClass.es.resx, y si tampoco hay éxito, /Resources/MyClass.resx.

Una vez que hemos creado y configurado los archivos .resx, podemos acceder a los recursos localizados utilizando una instancia de IStringLocalizer<T> como un diccionario en el que indicamos la clave del recurso. El siguiente código muestra cómo se accede a un recurso localizado en la clase HelloWorldMiddleware:

namespace LocalizationDemo.Middlewares
{
    public class HelloWorldMiddleware
    {
        private readonly IStringLocalizer<HelloWorldMiddleware> _loc;
        public HelloWorldMiddleware(RequestDelegate next, IStringLocalizer<HelloWorldMiddleware> loc)
        {
            _loc = loc;
        }
        public async Task Invoke(HttpContext context)
        {
            var culture = CultureInfo.CurrentCulture.Name;
            var text = _loc["Message", culture];
            await context.Response.WriteAsync(text);
        }
    }
}

En este código, la instancia de IStringLocalizer<HelloWorldMiddleware> se emplea para acceder al recurso localizado con la clave «Message». La variable culture se utiliza para especificar la cultura del hilo que procesa la petición.

Cuando la clave indicada no existe en los recursos localizados de la aplicación, el sistema devuelve la misma clave. Este aspecto podría ser aprovechado para producir textos en el idioma por defecto en lugar de tener que crear archivos .resx adicionales (una bendición, ya os lo digo yo).

Conclusión

La implementación de la internacionalización en una aplicación web es fundamental para llegar a una audiencia más amplia y para proporcionar una mejor experiencia de usuario a los usuarios que hablan diferentes idiomas. ASP.NET Core proporciona diversas herramientas para implementar la internacionalización, incluyendo la posibilidad de cambiar la cultura de la solicitud, la localización de las vistas y la inclusión de recursos de texto localizados.

Además, existen diversas opciones para la determinación de la cultura de la solicitud, como el uso de cookies, la consulta de la cadena de consulta o la detección de la configuración de idioma del navegador. La implementación de estas herramientas es sencilla y puede hacerse de forma escalable y mantenible.

Si bien la internacionalización es fundamental para proporcionar una experiencia de usuario de alta calidad, también es importante tener en cuenta que la localización es un proceso continuo. Es necesario hacer pruebas y recibir comentarios de los usuarios para detectar problemas y mejorar la experiencia de usuario en cada idioma. Al utilizar las herramientas de ASP.NET Core para la internacionalización, podemos estar seguros de que estamos proporcionando una base sólida para la localización futura de nuestra aplicación web. Me resulta increíble como los Framework hacen esta «magia» que nos facilita tanto la vida. Ha! y otro consejo (y ya me callo), si deseáis aplicar la internacionalización, hacerlo desde el principio, os evitaréis muchos dolores de cabeza.


Juan Ibero

Inmerso en la Evolución Tecnológica. Ingeniero Informático especializado en la gestión segura de entornos TI e industriales, con un profundo énfasis en seguridad, arquitectura y programación. Siempre aprendiendo, siempre explorando.

Compartir en:

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *