Skip to content

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

1
2
3
4
5
6
@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]:

1
2
3
4
5
6
7
@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:

Image

Image

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
1
2
3
4
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:

Image

Image

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.