Localização de validação em Minimal APIs no .NET 11

O que é a localização de validação no .NET 11

A localização de validação é a capacidade de traduzir mensagens de erro e nomes de campos de acordo com a cultura da requisição. No .NET 11, essa funcionalidade passou a fazer parte do pacote Microsoft.Extensions.Validation.

Esse pacote é a camada de validação que Minimal APIs e Blazor compartilham. Por isso, as mesmas regras de tradução valem nos dois cenários, tanto em um endpoint quanto em um formulário.

Na prática, bastam duas chamadas no Program.cs para ativar tudo:

builder.Services.AddLocalization(options => options.ResourcesPath = "Resources");
builder.Services.AddValidation();

O método AddValidation liga a validação automática dos parâmetros antes que o handler execute. Já o AddLocalization registra um IStringLocalizerFactory, e justamente essa presença ativa a localização de validação dentro do pipeline.

Quando um erro surge, o pacote procura a mensagem e o nome de exibição do membro nos seus recursos. Para isso, ele usa a CurrentUICulture da requisição atual.

Não existe pacote separado nem chamada extra de opt in. Em outras palavras, se a fábrica de localizadores está no container, a tradução acontece automaticamente.

Como era a validação antes do .NET 11

Durante muitos anos, mensagens de validação traduzidas eram exclusividade do ASP.NET Core MVC. O MVC usa adaptadores de atributos e IStringLocalizer, mas esse mecanismo depende diretamente do model binding dele.

Como consequência, Minimal APIs e Blazor nunca aproveitaram essa infraestrutura. Quem precisava de mensagens traduzidas em um endpoint mínimo tinha basicamente dois caminhos:

• Escrever um IEndpointFilter próprio que validasse a entrada e traduzisse as mensagens manualmente.
• Adotar o FluentValidation junto com um binder customizado para os modelos.

As duas abordagens funcionam, mas em ambas você assume um trabalho que deveria pertencer ao framework. Além disso, cada time acabava criando a própria convenção de chaves e arquivos.

O .NET 10 já havia trazido a validação nativa com Data Annotations para Minimal APIs, porém sem suporte a tradução. Com o .NET 11, a localização de validação finalmente entra na caixa.

Assim, o mesmo modelo anotado gera mensagens em português, inglês ou japonês sem código adicional. Essa é a principal mudança que o pacote traz para quem desenvolve APIs.

Configurando a localização de validação na Minimal API

Para demonstrar o recurso, vamos montar uma API com um único endpoint que recebe um cliente. O exemplo tem como alvo o .NET 11 e segue a estrutura do artigo original de Khalid Abuhakmeh, com o acréscimo da cultura pt-BR.

using System.Globalization;
using Microsoft.AspNetCore.Localization;
using MinimalApiLocalization;

var builder = WebApplication.CreateBuilder(args);

// Registra a localização e a validação
builder.Services.AddLocalization(options => options.ResourcesPath = "Resources");
builder.Services.AddValidation();

// Culturas aceitas pela API
var supportedCultures = new[] { "en-US", "pt-BR", "de-DE", "fr-FR", "ja-JP" };
builder.Services.Configure<RequestLocalizationOptions>(options =>
{
    options.SetDefaultCulture("en-US");
    options.AddSupportedCultures(supportedCultures);
    options.AddSupportedUICultures(supportedCultures);
});

var app = builder.Build();

// Define a cultura de cada requisição
app.UseRequestLocalization();

app.MapPost("/customers", (Customer customer) => Results.Ok(customer));

app.Run();

// Expõe a classe Program para os testes de integração
public partial class Program;

using System.ComponentModel.DataAnnotations;
using Microsoft.Extensions.Validation;

namespace MinimalApiLocalization;

[ValidatableType]
public class Customer
{
    // "CustomerName" é a chave do nome de exibição
    [Display(Name = "CustomerName")]
    // "NameRequired" e "NameLength" são chaves de recurso, não textos
    [Required(ErrorMessage = "NameRequired")]
    [StringLength(50, MinimumLength = 2, ErrorMessage = "NameLength")]
    public string? Name { get; set; }

    // Sem ErrorMessage: usa as chaves por convenção
    [Required]
    [EmailAddress]
    public string? Email { get; set; }

    [Range(18, 120)]
    public int Age { get; set; }
}

Como a localização de validação resolve as chaves

Entender a resolução das chaves é o ponto central para usar bem a localização de validação. Quando ErrorMessage está preenchido, o valor dele vira a chave de busca e tem prioridade sobre qualquer convenção.

Por outro lado, quando o atributo não define ErrorMessage, o pacote tenta chaves convencionais da mais específica para a mais genérica. A primeira que existir no recurso vence.

Escolhendo a cultura de cada requisição

O AddLocalization registra os serviços, mas não escolhe a cultura. Quem faz isso, requisição por requisição, é o middleware UseRequestLocalization.

Esse detalhe importa porque a busca nos recursos usa a CurrentUICulture, e não a CurrentCulture. O middleware traz três provedores, verificados nesta ordem:

Quando a cultura informada não aparece na lista de suportadas, o middleware recorre à cultura padrão definida em SetDefaultCulture. Assim, uma requisição com es-ES recebe as mensagens em inglês no nosso exemplo.

Em APIs consumidas por aplicações web, o cabeçalho Accept-Language costuma ser a escolha mais natural. Afinal, o navegador já envia esse valor automaticamente em cada chamada.

Já em integrações entre sistemas, a query string facilita testes rápidos e depuração. Nesse caso, basta acrescentar ?culture=pt-BR à URL para ver a localização de validação em ação.

Testando a localização de validação com WebApplicationFactory

Confiar apenas em teste manual não basta para um recurso que depende de cultura. Por isso, vamos comprovar a localização de validação com WebApplicationFactory<Program> e uma teoria por cultura.

O teste a seguir controla a cultura de duas formas: pelo cabeçalho Accept-Language e pela query string ?culture=. Ele também verifica o retorno ao inglês quando a API não suporta a cultura recebida.

public class ValidationLocalizationTests(WebApplicationFactory<Program> factory)
    : IClassFixture<WebApplicationFactory<Program>>
{
    // Cliente inválido em todos os campos
    private static readonly object InvalidCustomer =
        new { name = "", email = "not-an-email", age = 5 };

    public static TheoryData<string, string> ExpectedRequiredMessages => new()
    {
        { "en-US", "The customer name field is required." },
        { "pt-BR", "O campo nome do cliente é obrigatório." },
        { "de-DE", "Das Feld Kundenname ist erforderlich." },
        { "fr-FR", "Le champ nom du client est obligatoire." },
        { "ja-JP", "顧客名 は必須です。" },
    };

    [Theory]
    [MemberData(nameof(ExpectedRequiredMessages))]
    public async Task Localizes_via_AcceptLanguage_header(string culture, string expected)
    {
        var client = factory.CreateClient();
        var request = new HttpRequestMessage(HttpMethod.Post, "/customers")
        {
            Content = JsonContent.Create(InvalidCustomer),
        };
        request.Headers.Add("Accept-Language", culture);

        var response = await client.SendAsync(request);

        Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);
        Assert.Contains(expected, await ReadErrorMessages(response, "Name"));
    }

    [Theory]
    [MemberData(nameof(ExpectedRequiredMessages))]
    public async Task Localizes_via_query_string(string culture, string expected)
    {
        var client = factory.CreateClient();
        var response = await client.PostAsJsonAsync($"/customers?culture={culture}", InvalidCustomer);

        Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);
        Assert.Contains(expected, await ReadErrorMessages(response, "Name"));
    }

    [Fact]
    public async Task Unsupported_culture_falls_back_to_default()
    {
        var client = factory.CreateClient();
        var response = await client.PostAsJsonAsync("/customers?culture=es-ES", InvalidCustomer);

        Assert.Equal(HttpStatusCode.BadRequest, response.StatusCode);
        Assert.Contains(
            "The customer name field is required.",
            await ReadErrorMessages(response, "Name"));
    }

    // Lê as mensagens de erro de um membro no ProblemDetails
    private static async Task<string[]> ReadErrorMessages(HttpResponseMessage response, string member)
    {
        var problem = await response.Content.ReadFromJsonAsync<JsonElement>();
        return problem.GetProperty("errors").GetProperty(member)
            .EnumerateArray().Select(e => e.GetString()!).ToArray();
    }
}

O método ReadErrorMessages lê o ProblemDetails da resposta e extrai as mensagens de um membro específico. Com isso, cada teste valida exatamente o texto esperado para o campo Name.

No artigo original, o autor executou a suíte com quatro culturas e todos os nove testes passaram. Ao adicionar pt-BR, você ganha dois casos extras sem alterar nada na estrutura dos testes.

Note também que a expectativa em inglês usa "customer name". Isso acontece porque o arquivo Customer.en-US.resx também traduz a chave CustomerName para um rótulo legível.

Como ficam as respostas localizadas

Ao enviar o mesmo cliente inválido com culturas diferentes, a API devolve um ValidationProblem padrão com mensagens traduzidas. Veja a resposta para pt-BR:

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Name": [
      "O campo nome do cliente é obrigatório."
    ],
    "Email": [
      "O campo Email deve ser um endereço de e-mail válido."
    ],
    "Age": [
      "O campo Age deve estar entre 18 e 120."
    ]
  }
}

Agora a mesma requisição em japonês, conforme o resultado publicado no artigo original:

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Name": [
      "顧客名 は必須です。"
    ],
    "Email": [
      "Email は有効なメールアドレスである必要があります。"
    ],
    "Age": [
      "Age は 18 から 120 の間でなければなりません。"
    ]
  }
}

Observe que Name traduz o rótulo do campo graças ao [Display]. Enquanto isso, Email e Age mantêm o nome da propriedade, exatamente como a regra de nome de exibição prevê.

Além disso, o campo title do ProblemDetails continua em inglês nos dois casos. A localização de validação atua sobre as mensagens de erro e os nomes de exibição, não sobre os demais campos do payload.

Recursos avançados da localização de validação

Além do cenário básico, o pacote oferece pontos de extensão para casos mais elaborados. Todos eles aparecem na documentação oficial de validação do ASP.NET Core no Microsoft Learn.

builder.Services.AddValidation(options =>
{
    // Todas as chaves vêm do recurso ValidationMessages
    options.LocalizerProvider = (_, factory) => factory.Create(typeof(ValidationMessages));
});

// A fábrica customizada tem precedência sobre a implementação com resx
builder.Services.AddSingleton<IStringLocalizerFactory, JsonStringLocalizerFactory>();
builder.Services.AddValidation();

using System.ComponentModel.DataAnnotations;
using System.Globalization;
using Microsoft.Extensions.Validation;

public sealed class DivisibleByAttribute : ValidationAttribute, IValidationMessageFormatter
{
    public int Divisor { get; init; }

    // {0} recebe o nome de exibição e {1} recebe o divisor
    public string FormatMessage(CultureInfo culture, string template, string displayName) =>
        string.Format(culture, template, displayName, Divisor);
}

Quando adotar a localização de validação

Nem toda API precisa de mensagens em vários idiomas. Por exemplo, uma API interna consumida apenas por outros serviços raramente exibe esses textos para pessoas.

Por outro lado, APIs públicas e back ends de aplicativos mobile se beneficiam bastante do recurso. Nesses casos, o front end pode exibir a mensagem recebida diretamente, sem manter um dicionário de traduções duplicado.

O mesmo vale para projetos que combinam Minimal APIs e Blazor. Como as regras são idênticas nos dois lados, a localização de validação garante que o formulário e o endpoint mostrem exatamente o mesmo texto.

Também faz sentido migrar quando você já mantém um filtro de endpoint customizado só para traduzir erros. Afinal, cada linha removida desse filtro reduz a manutenção e o risco de divergência entre telas.

Se as suas regras dependem de consultas ao banco, avalie também a validação assíncrona do .NET 11. Ela faz parte do mesmo pacote, então vale cobrir as mensagens dessas regras com a mesma suíte de testes.

Cuidados antes de ir para produção

A localização de validação é simples de ativar, mas alguns detalhes podem gerar surpresas. Antes de publicar, revise os pontos abaixo.

• O gerador de código vale para um único assembly. O pacote gera metadados apenas no assembly que chama AddValidation, então modelos em uma class library precisam do pacote e de um método de extensão próprio.
• Modelos precisam ficar em arquivos .cs. Um source generator não lê a saída de outro gerador, por isso tipos declarados em arquivos .razor ficam invisíveis.
• A busca usa CurrentUICulture. Garanta que o UseRequestLocalization execute e que algum provedor reconheça a requisição.
• O recurso atende apenas Minimal APIs e Blazor. MVC e Razor Pages continuam com o sistema de adaptadores baseado em IStringLocalizer.
• Os atributos deixaram de ser experimentais. No .NET 10, [ValidatableType] e [SkipValidation] geravam o diagnóstico ASP0029, mas no .NET 11 nenhuma supressão se faz necessária.

Vale lembrar também que metadados ausentes não geram exceção nem log em tempo de execução. Por isso, um teste de integração como o que criamos funciona como rede de segurança contra regressões silenciosas.

Por fim, mensagens traduzidas não substituem uma API bem protegida. Se você ainda está estruturando a segurança dos endpoints, o artigo sobre autenticação e autorização no ASP.NET Core é um bom ponto de partida.

Conclusão sobre a localização de validação

A localização de validação nativa no .NET 11 elimina uma lacuna antiga das Minimal APIs. Com duas chamadas de serviço, alguns arquivos .resx e um provedor de cultura, a API devolve erros no idioma de quem chama.

Em outras palavras, você não precisa mais de FluentValidation, filtros de endpoint customizados ou localizadores próprios apenas para traduzir mensagens. Se você resolveu isso do jeito difícil no passado, este é um ótimo momento para apagar código.

O próximo passo é aplicar o padrão em uma API real. Comece pelas convenções globais, como RequiredAttribute_Error, e depois refine as mensagens por tipo conforme a necessidade.

FAQ

Preciso instalar algum pacote para traduzir mensagens de validação no .NET 11?

Não, em projetos web o recurso já vem no Microsoft.Extensions.Validation. Basta chamar AddLocalization e AddValidation no Program.cs.

A localização de validação funciona em controllers MVC?

Não, o recurso atende apenas Minimal APIs e Blazor. MVC e Razor Pages continuam usando o sistema de adaptadores com IStringLocalizer.

O que acontece se uma chave não existir no arquivo resx?

O framework usa a mensagem padrão do atributo em inglês. Dessa forma, a chave crua nunca aparece para o usuário.

Como traduzir o nome de um campo na mensagem?

Adicione [Display(Name = "Chave")] na propriedade e crie essa chave no arquivo .resx. O valor traduzido substitui o marcador {0} na mensagem.

Posso guardar as traduções em um banco de dados?

Sim, registre um IStringLocalizerFactory próprio no container. Ele tem precedência sobre a implementação padrão baseada em arquivos .resx.