Proporcionar recursos localizados para idiomas y referencias culturales en una aplicación de ASP.NET Core

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

Una de las tareas para localizar una aplicación es proporcionar cadenas localizadas en los archivos de recursos. Este artículo trata sobre cómo trabajar con archivos de recursos.

SupportedCultures y SupportedUICultures

ASP.NET Core tiene dos colecciones de valores de referencia cultural: SupportedCultures y SupportedUICultures. El objeto CultureInfo para SupportedCultures determina los resultados de funciones dependientes de la referencia cultural, como el formato de fecha, hora, número y moneda. SupportedCultures también determina el criterio de ordenación del texto, las convenciones sobre el uso de mayúsculas y minúsculas, y las comparaciones de cadenas. Consulte StringComparer.CurrentCulture para obtener más información sobre la forma en que el servidor obtiene la referencia cultural. SupportedUICultures determina qué cadenas traducidas buscará ResourceManager (en archivos.resx). ResourceManager simplemente busca cadenas específicas de referencias culturales determinadas por CurrentUICulture. Todos los subprocesos de .NET tienen objetos CurrentCulture y CurrentUICulture. ASP.NET Core inspecciona estos valores al representar funciones dependientes de la referencia cultural. Por ejemplo, si la referencia cultural del subproceso actual está establecida en "en-US" (inglés (Estados Unidos)), DateTime.Now.ToLongDateString() mostrará "Thursday, February 18, 2016". En cambio, si CurrentCulture está establecido en "es-ES" (español (España)), la salida será "jueves, 18 de febrero de 2016".

Archivos de recursos

NOTA:ResX Viewer y Editor proporcionan un mecanismo alternativo para trabajar con archivos de recursos mediante Visual Studio Code.

Un archivo de recursos es un mecanismo útil para separar del código las cadenas localizables. Las cadenas traducidas para el idioma no predeterminado están aisladas en archivos de recursos .resx. Por ejemplo, puede que quiera crear un archivo de recursos de español denominado Welcome.es.resx que contenga cadenas traducidas. "es" es el código de idioma para español. Para crear este archivo de recursos en Visual Studio:

1. En el Explorador de soluciones, haga clic con el botón derecho en la carpeta que contendrá el archivo de recursos y, a continuación, seleccione Agregar>Nuevo elemento.

   

2. En el cuadro para buscar plantillas instaladas, escriba "recurso" y asigne un nombre al archivo.

   

3. Escriba el valor de clave (cadena nativa) en la columna Nombre y la cadena traducida en la columna Valor.

   

   El archivo Welcome.es.resx aparece en Visual Studio.

   

Nomenclatura de los archivos de recursos

El nombre de los recursos es el nombre del tipo completo de su clase menos el nombre del ensamblado. Por ejemplo, un recurso francés de un proyecto cuyo ensamblado principal sea LocalizationWebsite.Web.dll para la clase LocalizationWebsite.Web.Startup se denominará Startup.fr.resx. Un recurso para la clase LocalizationWebsite.Web.Controllers.HomeController se denominará Controllers.HomeController.fr.resx. Si el espacio de nombres de la clase de destino no es igual que el nombre del ensamblado, necesitará el nombre de tipo completo. Por ejemplo, en el proyecto de ejemplo, un recurso para el tipo ExtraNamespace.Tools se denominará ExtraNamespace.Tools.fr.resx.

En el proyecto de ejemplo, el método ConfigureServices establece ResourcesPath en "Resources", por lo que la ruta de acceso relativa del proyecto para el archivo de recursos en francés del controlador de inicio es Resources/Controllers.HomeController.fr.resx. También puede usar carpetas para organizar los archivos de recursos. Para el controlador de inicio, la ruta de acceso sería Resources/Controllers/HomeController.fr.resx. Si no usa la opción ResourcesPath, el archivo .resx estará en el directorio base del proyecto. El archivo de recursos para HomeController se denominará Controllers.HomeController.fr.resx. La opción de usar la convención de nomenclatura de punto o ruta de acceso depende de la manera en que quiera organizar los archivos de recursos.

Nombre del recurso	Nomenclatura de punto o ruta de acceso
Resources/Controllers.HomeController.fr.resx	Punto
Resources/Controllers/HomeController.fr.resx	Ruta de acceso

Los archivos de recursos que usan @inject IViewLocalizer en las vistas de Razor siguen un patrón similar. Para asignar un nombre al archivo de recursos de una vista, se puede usar la nomenclatura de punto o de ruta de acceso. Los archivos de recursos de una vista de Razor imitan la ruta de acceso de su archivo de vista asociado. Supongamos que establecemos ResourcesPath en "Resources". En ese caso, el archivo de recursos de francés asociado a la vista Views/Home/About.cshtml podría ser uno de los siguientes:

• Resources/Views/Home/About.fr.resx

• Resources/Views.Home.About.fr.resx

Si no usa la opción ResourcesPath, el archivo .resx de una vista se ubicará en la misma carpeta que la vista.

RootNamespaceAttribute

El atributo RootNamespaceAttribute proporciona el espacio de nombres raíz de un ensamblado cuando el espacio de nombres raíz del ensamblado es diferente del nombre de ensamblado.

Advertencia

Esto puede ocurrir cuando el nombre de un proyecto no es un identificador de .NET válido. Por ejemplo my-project-name.csproj usará el espacio de nombres raíz my_project_name y el nombre de ensamblado my-project-name, lo que lleva a este error.

Si el espacio de nombres raíz de un ensamblado es diferente del nombre de ensamblado:

• La localización no funciona de forma predeterminada.
• Se produce un error en la localización debido a la manera en que se buscan los recursos dentro del ensamblado. RootNamespace es un valor en tiempo de compilación que no está disponible para el proceso en ejecución.

Si RootNamespace es diferente de AssemblyName, incluya lo siguiente en AssemblyInfo.cs (con los valores de parámetro reemplazados por los valores reales):

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

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

El código anterior permite la resolución correcta de los archivos resx.

Comportamiento de reserva de la referencia cultural

Cuando se busca un recurso, la localización entra en un proceso conocido como "reserva de la referencia cultural". Partiendo de la referencia cultural solicitada, si esta no se encuentra, se revierte a su referencia cultural principal correspondiente. Como inciso, decir que la propiedad CultureInfo.Parent representa la referencia cultural principal. Eso suele conllevar (aunque no siempre) la eliminación del significante nacional del código de idioma y referencia cultural. Así, por ejemplo, el dialecto de español hablado en México es "es-MX". Contiene el elemento principal "es", que corresponde a español no específico de ningún país en concreto.

Imagine que su sitio recibe una solicitud sobre un recurso "Welcome" donde se emplea la referencia cultural "fr-CA". El sistema de localización busca los recursos siguientes (en orden) y selecciona la primera coincidencia:

• Welcome.fr-CA.resx
• Welcome.fr.resx
• Welcome.resx (si NeutralResourcesLanguage es "fr-CA")

Consideremos, por ejemplo, que quita el designador de referencia cultural ".fr" y la referencia cultural está establecida en francés. En ese caso, se lee el archivo de recursos predeterminado y se localizan las cadenas. El Administrador de recursos designa un recurso predeterminado o de reserva para los casos en que nada coincida con la referencia cultural solicitada. Si quiere simplemente devolver la clave cuando falte un recurso para la referencia cultural solicitada, no debe tener un archivo de recursos predeterminado.

Generar archivos de recursos con Visual Studio

Si crea un archivo de recursos en Visual Studio sin una referencia cultural en el nombre de archivo (por ejemplo, Welcome.resx), Visual Studio creará una clase de C# con una propiedad para cada cadena. Normalmente esto no interesa con ASP.NET Core; por lo general, no tendrá un archivo de recursos .resx predeterminado (un archivo .resx sin el nombre de la referencia cultural). Se recomienda que cree el archivo .resx con un nombre de referencia cultural (por ejemplo, Welcome.fr.resx). Cuando cree un archivo .resx con un nombre de referencia cultural, Visual Studio no generará el archivo de clase.

Agregar otras referencias culturales

Cada combinación de idioma y referencia cultural (que no sea el idioma predeterminado) requiere un archivo de recursos único. Para crear archivos de recursos para otras referencias culturales y configuraciones regionales, debe crear archivos de recursos en los que los códigos de idioma formen parte del nombre de archivo (por ejemplo, en-us, fr-ca y en-gb). Estos códigos se colocan entre el nombre de archivo y la extensión de archivo .resx, como en Welcome.es-MX.resx (español [México]).

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
• Implementar una estrategia para seleccionar el idioma o la referencia cultural de cada solicitud

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
• Estrategias para seleccionar el idioma y la referencia cultural en una aplicación de ASP.NET Core localizada
• 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