5. Internacionalização
Uma aplicação internacionalizada exibe seus textos no idioma do usuário. O estudo de caso está em francês e inglês. O princípio é simples: as views não contêm mais texto, mas chaves ([MENU.HOME]), e um dicionário para cada idioma associa um texto a cada chave. O idioma selecionado é armazenado em um cookie.
[ASP.NET Core] tem seu próprio sistema de tradução (a interface [IStringLocalizer] e os arquivos de recursos [.resx]). Em vez dele, usaremos dicionários JSON, lidos por uma pequena classe escrita para esse fim: são os mesmos arquivos da versão [NestJS] do estudo de caso, e seu formato pode ser lido e escrito sem nenhuma ferramenta especial. Em contrapartida, deixaremos que o [ASP.NET Core] cuide da seleção do idioma a cada requisição: esse é o papel de seu middleware de localização.
5.1. Exemplo 22: uma aplicação bilíngue
| 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. Dicionários
O arquivo [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."
}
}
|
O arquivo [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."
}
}
|
- Um dicionário é um arquivo JSON, organizado por página ou por tema: a chave [HOME.HELLO] refere-se ao texto [HELLO] da seção [HOME];
- Linha 8: um texto pode conter parâmetros, delimitados por chaves, que são substituídos durante a tradução. A ordem das palavras varia de um idioma para outro: por isso um texto não é criado simplesmente concatenando segmentos traduzidos.
5.1.2. O serviço de tradução
O arquivo [Translation/Translator.cs]:
| using System.Globalization;
using System.Text.Json;
using System.Text.RegularExpressions;
namespace Example22.Translation;
// os dicionários, lidos UMA vez na inicialização: o serviço é um singleton
public partial class Translator
{
public static readonly string[] Languages = ["fr", "en"];
public const string DefaultLanguage = "en";
// idioma -> (chave 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;
}
}
// o idioma da requisição atual, definido pelo middleware de localização
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 "";
// uma chave ausente exibe a própria chave: um esquecimento aparece na tela
var text = dictionaries[CurrentLanguage()].GetValueOrDefault(key) ?? key;
if (parameters is null) return text;
// cada {name} é substituído pelo valor do parâmetro de mesmo nome
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() ?? "";
}
}
}
// a expressão regular {name}, compilada pelo compilador C#
[GeneratedRegex(@"\{(\w+)\}")]
private static partial Regex Parameter();
}
|
Vamos comentar este código:
- linha 8: a palavra-chave [partial] é exigida pela expressão regular no final do arquivo (veja adiante);
- linhas 10–11: os idiomas suportados e o idioma padrão;
- linha 14: para cada idioma, um dicionário [C#] que associa cada chave completa ([HOME.HELLO]) ao seu texto;
- linhas 16–24: o construtor lê os arquivos JSON. O serviço [IWebHostEnvironment], fornecido pelo [ASP.NET Core], retorna a pasta do projeto ([ContentRootPath]). [JsonDocument.Parse] analisa o texto JSON; [using var] libera o objeto ao final do bloco. O serviço será um singleton (veja [Program.cs]): os arquivos são lidos apenas uma vez;
- linhas 29–32: o idioma da requisição atual. Veremos que o middleware de localização o armazena em [CultureInfo.CurrentUICulture]. [TwoLetterISOLanguageName] retorna seu código de duas letras ([fr], [en]);
- Linhas 36–43: a tradução. A chave é procurada no dicionário do idioma atual; se não for encontrada, a própria chave é exibida: uma omissão fica imediatamente visível na tela. A expressão regular encontra cada parâmetro [{name}] no texto e o substitui por seu valor; um parâmetro sem valor é mantido como está;
- Linhas 47–58: a função “achata” o JSON: o objeto ["HOME": { "HELLO": "..." }] produz a chave [HOME.HELLO]. Ela chama a si mesma (função recursiva) para percorrer objetos aninhados;
- linhas 64–65: a expressão regular [\{(\w+)\}] (uma chave de abertura, um ou mais caracteres de palavra, capturados, uma chave de fechamento). O atributo [[GeneratedRegex]] instrui o compilador a gerar o código de análise uma vez por todas durante a compilação. O método é declarado como [partial]: seu corpo é gerado pelo compilador.
5.1.3. Implementação nas views
Uma view poderia obter o serviço com a diretiva [@inject Translator Translator] e depois escrever [@Translator.Translate("MENU.HOME")]. Isso é trabalhoso e teria de ser repetido em todas as views. Adotamos outra abordagem: cada view [Razor] é compilada em uma classe [C#], que por padrão deriva da classe [RazorPage<TModel>] do framework. Podemos inserir nossa própria classe, que fornece a todas as views os métodos de que precisam. O arquivo [Translation/ViewPage.cs]:
| using System.Globalization;
using Microsoft.AspNetCore.Mvc.Razor;
using Microsoft.AspNetCore.Mvc.Razor.Internal;
namespace Example22.Translation;
// a classe base de todas as views (veja Views/_ViewImports.cshtml: @inherits)
public abstract class ViewPage<TModel> : RazorPage<TModel>
{
// preenchido por injeção de dependência, como o @inject faria em uma view
[RazorInject]
public Translator Translator { get; set; } = null!;
// @T("HOME.HELLO", ("name", "Marie")): os parâmetros são pares (nome, valor)
public string T(string? key, params (string Name, object? Value)[] parameters) =>
Translator.Translate(key, parameters.ToDictionary(p => p.Name, p => p.Value?.ToString() ?? ""));
// "fr" ou "en"
public string Language => Translator.CurrentLanguage();
// uma data por extenso, no idioma atual
public string LongDate(DateOnly date) => date.ToString("D", CultureInfo.CurrentCulture);
// um valor em euros, no formato do idioma atual
public string Money(decimal amount)
{
var format = (NumberFormatInfo)CultureInfo.CurrentCulture.NumberFormat.Clone();
format.CurrencySymbol = "€";
return amount.ToString("C", format);
}
}
|
Vamos comentar este código:
- linha 8: uma classe genérica — [TModel] é o tipo do modelo da view, diferente para cada view. A classe é abstrata: apenas as views herdam dela;
- linhas 11–12: o atributo [[RazorInject]] instrui o [Razor] a preencher a propriedade por injeção de dependência: é o equivalente de [@inject] para uma classe;
- linhas 15–16: o método [T] traduz uma chave. Seus parâmetros são [(name, value)] tuplas: uma sintaxe compacta para escrever pares de valores, [("name", "Marie")]. A palavra-chave [params] permite passar quantos se quiser, separados por vírgulas. O método os organiza em um dicionário para o serviço. O texto produzido é uma string: o [Razor] a escapará, como faz com qualquer expressão [@];
- linha 19: o idioma atual, [fr] ou [en];
- linhas 22–29: datas e valores monetários são formatados de acordo com a cultura atual, que também é definida pelo middleware de localização (veja o Exemplo 16).
O arquivo [Views/_ViewImports.cshtml]:
| @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using Example22.Controllers
@using Example22.Translation
@* todas as views derivam de ViewPage: elas têm T(...), Language...;
TModel designa o tipo do modelo de cada view (@model ...) *@
@inherits ViewPage<TModel>
|
- linha 6: a diretiva [@inherits] especifica a classe pai das views. Colocada em [_ViewImports.cshtml], ela se aplica a todas elas. Cada view agora pode escrever [@T("MENU.HOME")].
5.1.4. Seleção do idioma
O arquivo [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));
// os dicionários: uma única instância, criada quando necessária pela primeira 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",
});
// o idioma de cada requisição: o do cookie, inglês caso contrário
var cultures = Translator.Languages.Select(l => new CultureInfo(l)).ToList();
var localization = new RequestLocalizationOptions
{
DefaultRequestCulture = new RequestCulture(Translator.DefaultLanguage),
SupportedCultures = cultures, // os idiomas dos formatos (datas, números)
SupportedUICultures = cultures, // os idiomas dos textos
};
// somente o cookie decide (nem o idioma do navegador, nem um parâmetro de URL)
localization.RequestCultureProviders = [new CookieRequestCultureProvider()];
app.UseRequestLocalization(localization);
app.MapControllers();
app.Run();
|
Vamos detalhar este código:
- linha 12: o serviço de tradução, com uma única instância;
- linhas 24–29: a configuração do middleware de localização. O [.NET] distingue dois conceitos: a cultura ([CurrentCulture]), que define o formato de datas e números, e a cultura de interface ([CurrentUICulture]), que define o idioma dos textos. Ambas recebem aqui a mesma lista de idiomas; um idioma que não esteja na lista é rejeitado;
- linha 32: onde procurar o idioma da requisição. Por padrão, o middleware verifica, em ordem, um parâmetro da URL ([?culture=en]), um cookie e depois o cabeçalho [Accept-Language] enviado pelo navegador (seu idioma). Apenas o cookie é mantido: o usuário faz a seleção com os botões FR / EN;
- Linha 33: o middleware é adicionado ao pipeline. A cada requisição, ele lê o cookie e define [CultureInfo.CurrentCulture] e [CultureInfo.CurrentUICulture] durante a requisição. Se não houver cookie, o idioma padrão é o inglês.
O arquivo [Controllers/LanguageController.cs]:
| using Example22.Translation;
using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;
namespace Example22.Controllers;
public class LanguageController : Controller
{
// GET /language/fr: armazena a escolha em um cookie e depois volta à página anterior
[HttpGet("language/{language}")]
public IActionResult Change(string language)
{
if (!Translator.Languages.Contains(language))
{
return NotFound();
}
Response.Cookies.Append(
CookieRequestCultureProvider.DefaultCookieName, // o nome do cookie
CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(language)), // "c=fr|uic=fr"
new CookieOptions { MaxAge = TimeSpan.FromDays(365), SameSite = SameSiteMode.Lax, HttpOnly = true });
return Redirect(OriginPage());
}
// a página de onde viemos (cabeçalho Referer), da qual mantemos apenas o caminho:
// redirecionar para um endereço completo tirado da requisição permitiria
// enviar o usuário a outro site (vulnerabilidade 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;
}
}
|
Vamos detalhar este código:
- linhas 10–21: [GET /language/en] armazena a seleção em um cookie válido por um ano e depois redireciona para a página de onde o usuário veio. Um idioma desconhecido resulta em um erro 404;
- linhas 17–20: [Response.Cookies.Append(name, value, options)] define um cookie: o navegador o reenviará a cada requisição seguinte. O nome e o formato de seu valor são os esperados pelo middleware de localização: nós os obtemos da classe [CookieRequestCultureProvider], sem precisar escrevê-los nós mesmos. Opções: [MaxAge] (tempo de vida), [HttpOnly] (o [JavaScript] da página não pode lê-lo), [SameSite = Lax] (ele não é enviado em requisições POST vindas de outros sites);
- linhas 27–34: a página de origem é indicada pelo cabeçalho [Referer], que o navegador adiciona quando um link é clicado. Mantemos apenas o caminho e os parâmetros ([PathAndQuery]): redirecionar para uma URL completa vinda da requisição permitiria que um site malicioso criasse um link que, depois de passar pelo nosso site, enviasse o usuário ao site malicioso (uma vulnerabilidade conhecida como [open redirect]).
5.1.5. As views
O arquivo [Views/Shared/_Layout.cshtml]:
| <!doctype html>
<html lang="@Language">
<head>
<meta charset="utf-8">
@* o título é uma CHAVE, definida pela view, traduzida pelo 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>
|
- linha 2: o atributo [lang] da página reflete o idioma selecionado (útil para leitores de tela e corretores ortográficos);
- linha 6: o título da página é uma chave, armazenada pela view em [ViewData] e traduzida pelo template. [as string] converte o valor (do tipo [object]) em string ou em [null] se ele não for uma.
O arquivo [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>
@* o idioma atual é destacado *@
<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>
|
- Linhas 8–9: dois links (mudar o idioma não modifica nenhum dado da aplicação: um GET basta), com o idioma atual destacado.
O arquivo [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>
|
- linha 6: um parâmetro, passado como tupla;
- linha 7: a data é primeiro formatada por [LongDate] e depois passada como parâmetro [date] para [T].
O arquivo [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>
|
- linha 11: o valor monetário, formatado de acordo com o idioma;
- linha 15: um parâmetro numérico; [T] o converte em string.
O arquivo [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);
}
}
|
As actions não dependem de idioma: elas fornecem dados, e as views os traduzem e formatam.
5.1.6. Execução
Em inglês (ainda sem cookie), nas URLs http://localhost:5000/ e http://localhost:5000/products:


Um clique em FR, simulado com [curl] (a opção [-H] adiciona o cabeçalho [Referer] que o navegador teria enviado):
| 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
|
O servidor define o cookie [.AspNetCore.Culture], cujo valor codificado é [c=fr|uic=fr] (a cultura e a cultura de interface), e redireciona para a página original, agora em francês:


Um idioma não suportado:
| curl -i http://localhost:5000/language/de
|
| HTTP/1.1 404 Not Found
Content-Length: 0
|
O estudo de caso procede exatamente dessa maneira, usando dicionários mais completos ([i18n/fr.json] e [i18n/en.json]): o mesmo serviço ([Translator]), a mesma classe pai das views (com algumas propriedades adicionais), o mesmo controller ([/language/{language}]) e o mesmo cookie. Há apenas uma diferença: as mensagens de erro geradas pelas camadas de negócio e web também são chaves, traduzidas no último momento pela view.