5. Internacionalización
Una aplicación internacionalizada muestra sus textos en el idioma del usuario. El caso de estudio está en francés y en inglés. El principio es simple: las vistas ya no contienen texto, sino claves ([MENU.HOME]), y un diccionario por idioma asocia un texto a cada clave. El idioma seleccionado se almacena en una cookie.
[ASP.NET Core] tiene su propio sistema de traducción (la interfaz [IStringLocalizer] y los archivos de recursos [.resx]). En su lugar, usaremos diccionarios JSON, leídos por una pequeña clase escrita para este fin: son los mismos archivos que los de la versión [NestJS] del caso de estudio, y su formato se puede leer y escribir sin herramientas especiales. Sin embargo, dejaremos que [ASP.NET Core] se encargue de seleccionar el idioma de cada solicitud: ese es el papel de su middleware de localización.
5.1. Ejemplo 22: una aplicación bilingüe
| 22-i18n/
├── Controllers/
│ ├── LanguageController.cs
│ └── PagesController.cs
├── i18n/
│ ├── en.json
│ └── fr.json
├── Translation/
│ ├── Translator.cs
│ └── ViewPage.cs
├── Views/
│ ├── Pages/
│ │ ├── Home.cshtml
│ │ └── Products.cshtml
│ ├── Shared/
│ │ ├── _Layout.cshtml
│ │ └── _Navbar.cshtml
│ ├── _ViewImports.cshtml
│ └── _ViewStart.cshtml
├── wwwroot/
│ └── css/
│ └── styles.css
├── appsettings.json
├── Example22.csproj
└── Program.cs
|
5.1.1. Diccionarios
El archivo [i18n/fr.json]:
| {
"MENU": {
"HOME": "Accueil",
"PRODUCTS": "Produits"
},
"HOME": {
"TITLE": "Bienvenue",
"HELLO": "Bonjour {name} !",
"DATE": "Nous sommes le {date}."
},
"PRODUCTS": {
"TITLE": "Nos produits",
"NAME": "Produit",
"PRICE": "Prix",
"COUNT": "{n} produit(s) au catalogue."
}
}
|
El archivo [i18n/en.json]:
| {
"MENU": {
"HOME": "Home",
"PRODUCTS": "Products"
},
"HOME": {
"TITLE": "Welcome",
"HELLO": "Hello {name}!",
"DATE": "Today is {date}."
},
"PRODUCTS": {
"TITLE": "Our products",
"NAME": "Product",
"PRICE": "Price",
"COUNT": "{n} product(s) in the catalogue."
}
}
|
- Un diccionario es un archivo JSON, organizado por página o por tema: la clave [HOME.HELLO] designa el texto [HELLO] de la sección [HOME];
- Línea 8: un texto puede contener parámetros, encerrados entre llaves, que se reemplazan durante la traducción. El orden de las palabras varía de un idioma a otro: por eso un texto no se crea simplemente concatenando segmentos traducidos.
5.1.2. El servicio de traducción
El archivo [Translation/Translator.cs]:
| using System.Globalization;
using System.Text.Json;
using System.Text.RegularExpressions;
namespace Example22.Translation;
// los diccionarios, leídos UNA sola vez al inicio: el servicio es un singleton
public partial class Translator
{
public static readonly string[] Languages = ["fr", "en"];
public const string DefaultLanguage = "en";
// idioma -> (clave completa "HOME.HELLO" -> texto)
private readonly Dictionary<string, Dictionary<string, string>> dictionaries = [];
public Translator(IWebHostEnvironment environment)
{
foreach (var language in Languages)
{
var path = Path.Combine(environment.ContentRootPath, "i18n", $"{language}.json");
using var document = JsonDocument.Parse(File.ReadAllText(path));
var dictionary = new Dictionary<string, string>();
Flatten(document.RootElement, "", dictionary);
dictionaries[language] = dictionary;
}
}
// el idioma de la solicitud actual, definido por el middleware de localización
public static string CurrentLanguage()
{
var language = CultureInfo.CurrentUICulture.TwoLetterISOLanguageName;
return Languages.Contains(language) ? language : DefaultLanguage;
}
// Translate("HOME.HELLO", { ["name"] = "Marie" }) -> "Hello Marie!"
public string Translate(string? key, IReadOnlyDictionary<string, string>? parameters = null)
{
if (string.IsNullOrEmpty(key)) return "";
// una clave faltante muestra la propia clave: un descuido se nota en pantalla
var text = dictionaries[CurrentLanguage()].GetValueOrDefault(key) ?? key;
if (parameters is null) return text;
// cada {name} se reemplaza por el valor del parámetro del mismo nombre
return Parameter().Replace(text, m => parameters.TryGetValue(m.Groups[1].Value, out var value) ? value : m.Value);
}
// { "MENU": { "HOME": "Home" } } -> { "MENU.HOME": "Home" }
private static void Flatten(JsonElement node, string prefix, Dictionary<string, string> result)
{
foreach (var property in node.EnumerateObject())
{
var key = prefix == "" ? property.Name : $"{prefix}.{property.Name}";
if (property.Value.ValueKind == JsonValueKind.Object)
{
Flatten(property.Value, key, result);
}
else
{
result[key] = property.Value.GetString() ?? "";
}
}
}
// la expresión regular {name}, compilada por el compilador de C#
[GeneratedRegex(@"\{(\w+)\}")]
private static partial Regex Parameter();
}
|
Comentemos este código:
- línea 8: la palabra clave [partial] la exige la expresión regular del final del archivo (véase más abajo);
- líneas 10–11: los idiomas admitidos y el idioma predeterminado;
- línea 14: para cada idioma, un diccionario [C#] que asocia cada clave completa ([HOME.HELLO]) con su texto;
- líneas 16–24: el constructor lee los archivos JSON. El servicio [IWebHostEnvironment], proporcionado por [ASP.NET Core], devuelve la carpeta del proyecto ([ContentRootPath]). [JsonDocument.Parse] analiza el texto JSON; [using var] libera el objeto al final del bloque. El servicio será un singleton (véase [Program.cs]): los archivos se leen una sola vez;
- líneas 29–32: el idioma de la solicitud actual. Veremos que el middleware de localización lo almacena en [CultureInfo.CurrentUICulture]. [TwoLetterISOLanguageName] devuelve su código de dos letras ([fr], [en]);
- Líneas 36–43: la traducción. La clave se busca en el diccionario del idioma actual; si no se encuentra, se muestra la propia clave: una omisión es inmediatamente visible en pantalla. La expresión regular encuentra cada parámetro [{name}] en el texto y lo reemplaza por su valor; un parámetro sin valor se deja tal cual;
- Líneas 47–58: la función “aplana” el JSON: el objeto ["HOME": { "HELLO": "..." }] produce la clave [HOME.HELLO]. Se llama a sí misma (función recursiva) para recorrer los objetos anidados;
- líneas 64–65: la expresión regular [\{(\w+)\}] (una llave de apertura, uno o más caracteres de palabra, capturados, una llave de cierre). El atributo [[GeneratedRegex]] indica al compilador que genere su código de análisis de una vez por todas durante la compilación. El método se declara como [partial]: su cuerpo lo genera el compilador.
5.1.3. Implementación en las vistas
Una vista podría obtener el servicio mediante la directiva [@inject Translator Translator] y luego escribir [@Translator.Translate("MENU.HOME")]. Esto es tedioso y habría que repetirlo en cada vista. Adoptamos otro enfoque: cada vista [Razor] se compila en una clase [C#] que, de forma predeterminada, deriva de la clase [RazorPage<TModel>] del framework. Podemos insertar nuestra propia clase, que proporciona a todas las vistas los métodos que necesitan. El archivo [Translation/ViewPage.cs]:
| using System.Globalization;
using Microsoft.AspNetCore.Mvc.Razor;
using Microsoft.AspNetCore.Mvc.Razor.Internal;
namespace Example22.Translation;
// la clase base de todas las vistas (ver Views/_ViewImports.cshtml: @inherits)
public abstract class ViewPage<TModel> : RazorPage<TModel>
{
// se llena por inyección de dependencias, como lo haría @inject en una vista
[RazorInject]
public Translator Translator { get; set; } = null!;
// @T("HOME.HELLO", ("name", "Marie")): los parámetros son pares (name, value)
public string T(string? key, params (string Name, object? Value)[] parameters) =>
Translator.Translate(key, parameters.ToDictionary(p => p.Name, p => p.Value?.ToString() ?? ""));
// "fr" o "en"
public string Language => Translator.CurrentLanguage();
// una fecha en palabras completas, en el idioma actual
public string LongDate(DateOnly date) => date.ToString("D", CultureInfo.CurrentCulture);
// un monto en euros, en el formato del idioma actual
public string Money(decimal amount)
{
var format = (NumberFormatInfo)CultureInfo.CurrentCulture.NumberFormat.Clone();
format.CurrencySymbol = "€";
return amount.ToString("C", format);
}
}
|
Comentemos este código:
- línea 8: una clase genérica: [TModel] es el tipo del modelo de la vista, que es distinto para cada vista. La clase es abstracta: solo las vistas heredan de ella;
- líneas 11–12: el atributo [[RazorInject]] indica a [Razor] que rellene la propiedad mediante inyección de dependencias: es el equivalente de [@inject] para una clase;
- líneas 15–16: el método [T] traduce una clave. Sus parámetros son [(name, value)] tuplas: una sintaxis compacta para escribir pares de valores, [("name", "Marie")]. La palabra clave [params] permite pasar tantos como se quiera, separados por comas. El método los organiza en un diccionario para el servicio. El texto producido es una cadena: [Razor] la escapará, como a cualquier expresión [@];
- línea 19: el idioma actual, [fr] o [en];
- líneas 22–29: las fechas y los montos se formatean según la cultura actual, que también establece el middleware de localización (véase el ejemplo 16).
El archivo [Views/_ViewImports.cshtml]:
| @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using Example22.Controllers
@using Example22.Translation
@* todas las vistas derivan de ViewPage: tienen T(...), Language...;
TModel designa el tipo del modelo de cada vista (@model ...) *@
@inherits ViewPage<TModel>
|
- línea 6: la directiva [@inherits] especifica la clase padre de las vistas. Colocada en [_ViewImports.cshtml], se aplica a todas ellas. Cada vista puede ahora escribir [@T("MENU.HOME")].
5.1.4. Selección del idioma
El archivo [Program.cs]:
| using System.Globalization;
using System.Text.Encodings.Web;
using System.Text.Unicode;
using Example22.Translation;
using Microsoft.AspNetCore.Localization;
using Microsoft.Extensions.FileProviders;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllersWithViews();
builder.Services.AddSingleton(HtmlEncoder.Create(UnicodeRanges.All));
// los diccionarios: una única instancia, creada cuando se necesita por primera vez
builder.Services.AddSingleton<Translator>();
var app = builder.Build();
app.UseStaticFiles();
app.UseStaticFiles(new StaticFileOptions
{
FileProvider = new PhysicalFileProvider(Path.GetFullPath(Path.Combine(builder.Environment.ContentRootPath, "..", "common", "bootstrap"))),
RequestPath = "/bootstrap",
});
// el idioma de cada solicitud: el de la cookie, inglés en su defecto
var cultures = Translator.Languages.Select(l => new CultureInfo(l)).ToList();
var localization = new RequestLocalizationOptions
{
DefaultRequestCulture = new RequestCulture(Translator.DefaultLanguage),
SupportedCultures = cultures, // los idiomas de los formatos (fechas, números)
SupportedUICultures = cultures, // los idiomas de los textos
};
// solo decide la cookie (ni el idioma del navegador, ni un parámetro de URL)
localization.RequestCultureProviders = [new CookieRequestCultureProvider()];
app.UseRequestLocalization(localization);
app.MapControllers();
app.Run();
|
Analicemos este código:
- línea 12: el servicio de traducción, con una única instancia;
- líneas 24–29: la configuración del middleware de localización. [.NET] distingue dos conceptos: la cultura ([CurrentCulture]), que define el formato de las fechas y los números, y la cultura de interfaz ([CurrentUICulture]), que define el idioma de los textos. A ambas se les asigna aquí la misma lista de idiomas; un idioma que no esté en la lista se rechaza;
- línea 32: dónde buscar el idioma de la solicitud. De forma predeterminada, el middleware revisa, en orden, un parámetro de la URL ([?culture=en]), una cookie y luego el encabezado [Accept-Language] enviado por el navegador (su idioma). Solo se conserva la cookie: el usuario realiza la selección mediante los botones FR / EN;
- Línea 33: el middleware se agrega a la canalización. En cada solicitud, lee la cookie y establece [CultureInfo.CurrentCulture] y [CultureInfo.CurrentUICulture] durante el tiempo que dure la solicitud. Si no hay cookie, el idioma predeterminado es el inglés.
El archivo [Controllers/LanguageController.cs]:
| using Example22.Translation;
using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;
namespace Example22.Controllers;
public class LanguageController : Controller
{
// GET /language/fr: guarda la elección en una cookie y luego vuelve a la página anterior
[HttpGet("language/{language}")]
public IActionResult Change(string language)
{
if (!Translator.Languages.Contains(language))
{
return NotFound();
}
Response.Cookies.Append(
CookieRequestCultureProvider.DefaultCookieName, // el nombre de la cookie
CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(language)), // "c=fr|uic=fr"
new CookieOptions { MaxAge = TimeSpan.FromDays(365), SameSite = SameSiteMode.Lax, HttpOnly = true });
return Redirect(OriginPage());
}
// la página de la que venimos (encabezado Referer), de la que solo conservamos la ruta:
// redirigir a una dirección completa tomada de la solicitud permitiría
// enviar al usuario a otro sitio (vulnerabilidad de "open redirect")
private string OriginPage()
{
var referer = Request.Headers.Referer.ToString();
if (!Uri.TryCreate(referer, UriKind.Absolute, out var url))
{
return "/";
}
return url.PathAndQuery;
}
}
|
Analicemos este código:
- líneas 10–21: [GET /language/en] almacena la selección en una cookie válida durante un año y luego redirige a la página de la que provenía el usuario. Un idioma desconocido produce un error 404;
- líneas 17–20: [Response.Cookies.Append(name, value, options)] establece una cookie: el navegador la reenviará con cada solicitud posterior. El nombre y el formato de su valor son los que espera el middleware de localización: los obtenemos de la clase [CookieRequestCultureProvider], sin tener que escribirlos nosotros mismos. Opciones: [MaxAge] (tiempo de vida), [HttpOnly] (el [JavaScript] de la página no puede leerla), [SameSite = Lax] (no se envía en las solicitudes POST provenientes de otros sitios);
- líneas 27–34: la página de origen la indica el encabezado [Referer], que el navegador agrega cuando se hace clic en un enlace. Solo conservamos la ruta y los parámetros ([PathAndQuery]): redirigir a una URL completa tomada de la solicitud permitiría que un sitio malicioso creara un enlace que, tras pasar por nuestro sitio, envíe al usuario al sitio malicioso (una vulnerabilidad conocida como [open redirect]).
5.1.5. Las vistas
El archivo [Views/Shared/_Layout.cshtml]:
| <!doctype html>
<html lang="@Language">
<head>
<meta charset="utf-8">
@* el título es una CLAVE, asignada por la vista y traducida por el layout *@
<title>@T(ViewData["Title"] as string)</title>
<link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
<link rel="stylesheet" href="/css/styles.css">
</head>
<body>
<div class="container py-3">
<partial name="_Navbar" />
@RenderBody()
</div>
</body>
</html>
|
- línea 2: el atributo [lang] de la página refleja el idioma seleccionado (útil para los lectores de pantalla y los correctores ortográficos);
- línea 6: el título de la página es una clave, almacenada por la vista en [ViewData] y traducida por la plantilla. [as string] convierte el valor (de tipo [object]) en una cadena, o en [null] si no lo es.
El archivo [Views/Shared/_Navbar.cshtml]:
| <nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
<div class="navbar-nav me-auto">
<a class="nav-link" href="/">@T("MENU.HOME")</a>
<a class="nav-link" href="/products">@T("MENU.PRODUCTS")</a>
</div>
@* se resalta el idioma actual *@
<div class="btn-group btn-group-sm">
<a class="btn @(Language == "fr" ? "btn-primary" : "btn-outline-primary")" href="/language/fr">FR</a>
<a class="btn @(Language == "en" ? "btn-primary" : "btn-outline-primary")" href="/language/en">EN</a>
</div>
</nav>
|
- Líneas 8–9: dos enlaces (cambiar el idioma no modifica ningún dato de la aplicación: basta con un GET), con el idioma actual resaltado.
El archivo [Views/Pages/Home.cshtml]:
| @model HomeModel
@{
ViewData["Title"] = "HOME.TITLE";
}
<h1>@T("HOME.TITLE")</h1>
<p>@T("HOME.HELLO", ("name", Model.Name))</p>
<p>@T("HOME.DATE", ("date", LongDate(Model.Today)))</p>
|
- línea 6: un parámetro, pasado como tupla;
- línea 7: la fecha se formatea primero con [LongDate] y luego se pasa como parámetro [date] a [T].
El archivo [Views/Pages/Products.cshtml]:
| @model List<Product>
@{
ViewData["Title"] = "PRODUCTS.TITLE";
}
<h1>@T("PRODUCTS.TITLE")</h1>
<table class="table table-sm w-auto">
<thead><tr><th>@T("PRODUCTS.NAME")</th><th class="text-end">@T("PRODUCTS.PRICE")</th></tr></thead>
<tbody>
@foreach (var product in Model)
{
<tr><td>@product.Name</td><td class="text-end">@Money(product.Price)</td></tr>
}
</tbody>
</table>
<p>@T("PRODUCTS.COUNT", ("n", Model.Count))</p>
|
- línea 11: el monto, formateado según el idioma;
- línea 15: un parámetro numérico; [T] lo convierte en cadena.
El archivo [Controllers/PagesController.cs]:
| using Microsoft.AspNetCore.Mvc;
namespace Example22.Controllers;
public record Product(string Name, decimal Price);
public record HomeModel(string Name, DateOnly Today);
public class PagesController : Controller
{
[HttpGet("/")]
public IActionResult Home()
{
return View(new HomeModel("Marie", new DateOnly(2026, 9, 23)));
}
[HttpGet("products")]
public IActionResult Products()
{
List<Product> products =
[
new Product("Keyboard", 25m),
new Product("Mouse", 12.5m),
new Product("Screen", 1149m),
];
return View(products);
}
}
|
Las acciones son independientes del idioma: proporcionan los datos, y las vistas los traducen y les dan formato.
5.1.6. Ejecución
En inglés (todavía sin cookie), en las URL http://localhost:5000/ y http://localhost:5000/products:


Un clic en FR, simulado con [curl] (la opción [-H] agrega el encabezado [Referer] que habría enviado el navegador):
| curl -i -H "Referer: http://localhost:5000/products" http://localhost:5000/language/fr
|
| HTTP/1.1 302 Found
Content-Length: 0
Location: /products
Set-Cookie: .AspNetCore.Culture=c%3Dfr%7Cuic%3Dfr; max-age=31536000; path=/; samesite=lax; httponly
|
El servidor establece la cookie [.AspNetCore.Culture], cuyo valor codificado es [c=fr|uic=fr] (la cultura y la cultura de interfaz), y redirige a la página de origen, ahora en francés:


Un idioma no admitido:
| curl -i http://localhost:5000/language/de
|
| HTTP/1.1 404 Not Found
Content-Length: 0
|
El caso de estudio procede exactamente de esta manera, con diccionarios más completos ([i18n/fr.json] y [i18n/en.json]): el mismo servicio ([Translator]), la misma clase padre de las vistas (con algunas propiedades adicionales), el mismo controlador ([/language/{language}]) y la misma cookie. Solo hay una diferencia: los mensajes de error generados por las capas de negocio y web también son claves, traducidas en el último momento por la vista.