i18n e ASP.NET Core Web API

i18n é uma abreviação para internacionalização, um processo que visa tornar um software adaptável a diferentes idiomas e culturas, sem a necessidade de grandes reestruturações. Em outras palavras, é preparar um software para ser utilizado em qualquer parte do mundo. A i18n envolve a separação do texto do código, a formatação de datas, números e moedas de acordo com cada cultura, e o suporte a diferentes conjuntos de caracteres. Ao internacionalizar um software, você amplia seu alcance, melhora a experiência do usuário e aumenta sua competitividade no mercado global.

Neste post irei te ensinar como iniciar o processo de internacionalização em um projeto webapi .net 8. Tenho aqui um projeto recém iniciado que usarei como exemplo e deixarei o link do github caso queira conferir o código.

A primeira coisa que devemos fazer é adicionar o serviço de localização na aplicação:

builder.Services.AddLocalization();

.

.

.

//Declaramos um array de culturas suportadas

var supportedCultures = new [] {"en-US", "pt-BR"};





// Especificamos as opções para o RequestLocalizationMiddleware

var localizationOptions = new RequestLocalizationOptions()

    .SetDefaultCulture("pt-BR")

    .AddSupportedCultures(supportedCultures)

    .AddSupportedUICultures(supportedCultures);





// Adiciona o RequestLocalizationMiddleware para definir automaticamente as 

// informações de cultura para solicitações com base nas informações 

//fornecidas pelo cliente.

app.UseRequestLocalization(localizationOptions);

(**Um detalhe importante que é ressaltado na documentação é que: "O middleware de localização precisa ser configurado antes de qualquer middleware que possa verificar a cultura de solicitação (por exemplo, app.UseMvcWithDefaultRoute())." Então preste atenção na ordem que vc está configurando os componentes do middleware.)

Agora iremos adicionar os recursos necessários para fazer as traduções. Irei criar um projeto classlib chamado Common, adicioná-lo na solução e referenciá-lo no projeto da api (estou usando dotnet cli, mas fique à vontade para utilizar uma ide se preferir):

dotnet new classlib -n Common

dotnet sln add Common/

dotnet add Api/Api.csproj reference Common/Common.csproj

Dentro do projeto Common criamos um diretório chamado "Resources" e nele criaremos dois arquivos de recurso. A estrutura fica assim:

Podemos começar a criar nosso primeiro texto para ser traduzido:

O item (1) é chave (2) e (3) são os valores que serão utilizados conforme o idioma requisitado.

Mas antes clique em propriedades do recurso, adicione Public nesse campo (custom tool):

E também altere a classe Resource para ter seu modificador de acesso para Public

public class Resource {...}

Na controller iremo injetar o IStringLocalizer que vem de Microsoft.Extensions.Localization. E o Resource é o que criamos então faça também o using de Common.Resources;

using Microsoft.AspNetCore.Mvc;

using Microsoft.Extensions.Localization;

using Common.Resources;



namespace Api.Controllers;



[ApiController]

[Route("[controller]")]

public class WeatherForecastController : ControllerBase

{

    private readonly IStringLocalizer<Resource> _localizer;



    public WeatherForecastController(IStringLocalizer<Resource> localizer)

    {

        _localizer = localizer;

    }



    [HttpGet(Name = "GetWeatherForecast")]

    public IActionResult Get()

    {

        return Ok($"Sucesso na traducao: {_localizer["msg_sucesso"]}");

    }

}

O uso do _localizer fica assim: _localizer["chave"].

Para testar nossa aplicação utilizaremos o postman:

E em inglês temos:

E quando não colocamos nada, permanece aquele que configuramos como padrão:

E isso é tudo, pessoal! Fiquem à vontade para comentar qualquer equívoco ou sugestão. Espero que tenha te ajudado!