Skip to main content

Guia completa de localització d'ASP.NET Core

Des d'IStringLocalizer fins a producció: configuri la localització basada en recursos a ASP.NET Core i automatitzi les traduccions amb IA.

1

Activar els serveis de localització

Registri els serveis de localització a Program.cs amb AddLocalization(), configuri les cultures admeses i afegeixi el programari intermedi de localització de sol·licituds. Això connecta tot el procés de localització de la seva aplicació ASP.NET Core.

AddLocalization() registra IStringLocalizer i IStringLocalizerFactory al contenidor d'injecció de dependències. ResourcesPath indica al sistema on ha de cercar els fitxers .resx. AddViewLocalization() activa IViewLocalizer a les vistes Razor i AddDataAnnotationsLocalization() activa els missatges de validació localitzats.
Program.cs
using Microsoft.AspNetCore.Localization;
using System.Globalization;

var builder = WebApplication.CreateBuilder(args);

// 1. Register localization services
builder.Services.AddLocalization(o => o.ResourcesPath = "Resources");

// 2. Add MVC with view/data-annotation localization
builder.Services.AddControllersWithViews()
    .AddViewLocalization()
    .AddDataAnnotationsLocalization();

var app = builder.Build();

// 3. Configure supported cultures
var supportedCultures = new[] { "en", "de", "ja", "es", "pt-BR" }
    .Select(c => new CultureInfo(c)).ToArray();

app.UseRequestLocalization(new RequestLocalizationOptions
{
    DefaultRequestCulture = new RequestCulture("en"),
    SupportedCultures = supportedCultures,
    SupportedUICultures = supportedCultures,
});

app.UseStaticFiles();
app.UseRouting();
app.MapControllers();
app.Run();
2

Crear fitxers de recursos RESX

ASP.NET Core utilitza fitxers RESX (recursos XML) per a les traduccions. Creï un fitxer per cultura i classe: HomeController.en.resx, HomeController.de.resx, etc. El sistema resol el fitxer correcte segons la cultura de la sol·licitud actual.

Resources/Controllers/HomeController.{culture}.resx
<!-- Resources/Controllers/HomeController.en.resx -->
<?xml version="1.0" encoding="utf-8"?>
<root>
  <data name="Welcome" xml:space="preserve">
    <value>Welcome to our application</value>
  </data>
  <data name="Greeting" xml:space="preserve">
    <value>Hello, {0}!</value>
  </data>
</root>

<!-- Resources/Controllers/HomeController.de.resx -->
<?xml version="1.0" encoding="utf-8"?>
<root>
  <data name="Welcome" xml:space="preserve">
    <value>Willkommen in unserer Anwendung</value>
  </data>
  <data name="Greeting" xml:space="preserve">
    <value>Hallo, {0}!</value>
  </data>
</root>
Utilitzi una classe SharedResource amb fitxers RESX propis per a les cadenes compartides entre controladors i vistes, com ara etiquetes de botons, elements de navegació i missatges de validació comuns. Així eviti duplicar claus en desenes de fitxers RESX específics de cada controlador.
Shared resources for cross-cutting strings
<!-- Resources/SharedResource.en.resx — shared across controllers -->
<?xml version="1.0" encoding="utf-8"?>
<root>
  <data name="AppName" xml:space="preserve">
    <value>My Application</value>
  </data>
  <data name="Save" xml:space="preserve"><value>Save</value></data>
  <data name="Cancel" xml:space="preserve"><value>Cancel</value></data>
</root>

// Marker class (empty — only used for type lookup)
namespace MyApp;
public class SharedResource { }
3

Utilitzar IStringLocalizer en controladors i serveis

Injecti IStringLocalizer&lt;T&gt; en qualsevol controlador, servei o programari intermedi mitjançant la injecció de dependències. El paràmetre de tipus genèric T determina quin fitxer RESX s'ha de carregar. Utilitzi la sintaxi de claudàtors localizer["Key"] per recuperar les cadenes traduïdes, amb paràmetres de format opcionals.

Controllers/HomeController.cs
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Localization;

public class HomeController(
    IStringLocalizer<HomeController> localizer,
    IStringLocalizer<SharedResource> shared) : Controller
{
    public IActionResult Index()
    {
        ViewData["Welcome"] = localizer["Welcome"];
        ViewData["AppName"] = shared["AppName"];

        // String interpolation with format parameters
        var greeting = localizer["Greeting", User.Identity?.Name ?? "Guest"];
        return View(new HomeViewModel { Greeting = greeting });
    }
}
Si IStringLocalizer retorna el nom de la clau en lloc del valor traduït, comprovi tres coses: (1) que el nom del fitxer RESX coincideixi amb l'espai de noms de la classe, (2) que ResourcesPath a AddLocalization() apunti a la carpeta correcta i (3) que l'opció Build Action del fitxer RESX estigui definida com a Embedded Resource a Visual Studio.
4

Configurar el programari intermedi de cultura de la sol·licitud

ASP.NET Core determina la cultura de la sol·licitud mitjançant una cadena de proveïdors: cadena de consulta, galeta i capçalera Accept-Language, en aquest ordre. Pot afegir-hi proveïdors personalitzats; per exemple, un que llegeixi la cultura d'un segment de la ruta URL com /de/home.

Custom RouteDataRequestCultureProvider
// Culture resolved in order: QueryString, Cookie, Accept-Language
// Custom provider: read culture from URL route segment /de/home
public class RouteDataRequestCultureProvider : RequestCultureProvider
{
    public override Task<ProviderCultureResult?> DetermineProviderCultureResult(
        HttpContext httpContext)
    {
        var culture = httpContext.GetRouteValue("culture")?.ToString();
        if (string.IsNullOrEmpty(culture))
            return NullProviderCultureResult;
        return Task.FromResult<ProviderCultureResult?>(
            new ProviderCultureResult(culture));
    }
}

// Register in Program.cs (route provider first = highest priority):
app.UseRequestLocalization(new RequestLocalizationOptions
{
    DefaultRequestCulture = new RequestCulture("en"),
    SupportedCultures = supportedCultures,
    SupportedUICultures = supportedCultures,
    RequestCultureProviders = new List<IRequestCultureProvider>
    {
        new RouteDataRequestCultureProvider(),
        new QueryStringRequestCultureProvider(),
        new CookieRequestCultureProvider(),
        new AcceptLanguageHeaderRequestCultureProvider(),
    }
});
Language Switcher Action
// Language switcher: persist choice in cookie
[HttpPost]
public IActionResult SetLanguage(string culture, string returnUrl)
{
    Response.Cookies.Append(
        CookieRequestCultureProvider.DefaultCookieName,
        CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(culture)),
        new CookieOptions { Expires = DateTimeOffset.UtcNow.AddYears(1) });
    return LocalRedirect(returnUrl);
}
L'ordre del programari intermedi és important. Cal cridar UseRequestLocalization() després de UseRouting(), però abans de UseEndpoints() o MapControllers(). Si es col·loca massa tard, la cultura no estarà definida quan s'executin els controladors.
5

Localitzar les anotacions de dades

Els atributs de validació com [Required], [StringLength] i [Display] es poden localitzar definint-ne les propietats ErrorMessage o Name amb noms de claus RESX. Cridi AddDataAnnotationsLocalization() a Program.cs per activar-ho.

ViewModels/RegisterViewModel.cs
using System.ComponentModel.DataAnnotations;

public class RegisterViewModel
{
    [Required(ErrorMessage = "NameRequired")]
    [Display(Name = "FullName")]
    [StringLength(100, ErrorMessage = "NameLength", MinimumLength = 2)]
    public string Name { get; set; } = string.Empty;

    [Required(ErrorMessage = "EmailRequired")]
    [EmailAddress(ErrorMessage = "EmailInvalid")]
    [Display(Name = "EmailAddress")]
    public string Email { get; set; } = string.Empty;

    [Required(ErrorMessage = "PasswordRequired")]
    [StringLength(100, ErrorMessage = "PasswordLength", MinimumLength = 8)]
    [Display(Name = "Password")]
    public string Password { get; set; } = string.Empty;
}
// RESX keys map to ErrorMessage/Name values:
// RegisterViewModel.de.resx: NameRequired = "Name ist erforderlich"
// RegisterViewModel.de.resx: FullName = "Vollständiger Name"
La localització de les anotacions de dades utilitza el nom de la classe ViewModel, no el del controlador, per trobar els fitxers RESX. Per a RegisterViewModel, el sistema cerca Resources/ViewModels/RegisterViewModel.de.resx. Si els fitxers RESX tenen el nom del controlador, els missatges de validació no es localitzaran.
6

Gestionar plurals i missatges d’ICU

.NET no incorpora compatibilitat amb regles de plural com les d’ICU. Per als casos senzills, utilitzi claus RESX separades (ItemCount_One, ItemCount_Other) i una selecció al codi. Per gaudir de compatibilitat completa amb ICU MessageFormat en totes les categories de plural CLDR, utilitzi la biblioteca MessageFormat.NET.

Plural handling strategies
// Option 1: Separate RESX keys with code switch
// HomeController.en.resx: ItemCount_One = "You have {0} item"
// HomeController.en.resx: ItemCount_Other = "You have {0} items"
public string GetItemCount(int count)
{
    var key = count == 1 ? "ItemCount_One" : "ItemCount_Other";
    return _localizer[key, count];
}

// Option 2: ICU MessageFormat (dotnet add package MessageFormat.NET)
using Jeffijoe.MessageFormat;
var formatter = new MessageFormatter();

var pattern = "{count, plural, one {# item} other {# items}} in your cart";
var result = formatter.FormatMessage(pattern,
    new Dictionary<string, object> { { "count", 5 } });
// => "5 items in your cart"

// Arabic: 6 plural forms (zero, one, two, few, many, other)
var arPattern = @"{count, plural,
    zero {لا عناصر} one {عنصر واحد} two {عنصران}
    few {# عناصر} many {# عنصرًا} other {# عنصر}}";
No utilitzi mai count == 1 per detectar formes singulars. En francès, el 0 es tracta com a singular. El rus té formes diferents per a 'few' i 'many'. L’àrab té sis categories de plural. Utilitzi regles de plural compatibles amb CLDR o una biblioteca com MessageFormat.NET que ho gestioni correctament.
7

Localitzar les vistes Razor

Utilitzi IViewLocalizer a les vistes Razor mitjançant @inject. Resol els fitxers RESX segons el camí del fitxer de la vista. Per a cadenes amb marcatge que siguin segures per a HTML, utilitzi IHtmlLocalizer. Els Tag Helpers com asp-for i asp-validation-for utilitzen automàticament els atributs Display i ErrorMessage localitzats.

Views/Home/Index.cshtml
@using Microsoft.AspNetCore.Mvc.Localization
@inject IViewLocalizer Localizer
@inject IHtmlLocalizer<SharedResource> SharedHtml

<h1>@Localizer["Welcome"]</h1>
<p>@Localizer["Greeting", User.Identity?.Name]</p>

@* IHtmlLocalizer: does NOT escape — use for RESX values with HTML *@
<p>@SharedHtml["TermsNotice"]</p>

@* Tag Helpers auto-localize Display/ErrorMessage attributes *@
<form asp-action="Register">
    <label asp-for="Name"></label>
    <input asp-for="Name" />
    <span asp-validation-for="Name"></span>
    <button type="submit">@Localizer["Submit"]</button>
</form>
IViewLocalizer resol els fitxers RESX segons el camí de la vista: Views/Home/Index.cshtml cerca Resources/Views/Home/Index.de.resx. Si vol compartir cadenes entre vistes, injecti IStringLocalizer&lt;SharedResource&gt; per separat.
8

Automatitzar les traduccions RESX

Un cop completada la configuració de localització, tradueixi els fitxers RESX amb IA. Demani a l'assistent d'IA de l'IDE que tradueixi el RESX d'origen o utilitzi la CLI d’i18n Agent a la canalització de CI/CD per mantenir les traduccions sincronitzades.

Terminal
# In your IDE, ask your AI assistant:
> Translate Resources/Controllers/HomeController.en.resx to German, Japanese, Spanish

# HomeController.de.resx created (1.2s)
# HomeController.ja.resx created (1.5s)
# HomeController.es.resx created (1.1s)

# Or use the CLI in CI/CD:
npx i18n-agent translate Resources/Controllers/HomeController.en.resx --lang de,ja,es
Tradueixi de manera incremental: quan afegeixi claus noves al fitxer RESX d'origen, tradueixi només les diferències en lloc de tornar a generar tots els fitxers. Això conserva les traduccions revisades per persones i redueix els canvis innecessaris.

Automatitzar la qualitat de la traducció

Detecti les claus que falten i els marcadors de posició malmesos abans de publicar-los amb i18n-validate. Provi la interfície amb pseudotraduccions mitjançant i18n-pseudo abans que arribin les traduccions reals.

Corregir la reserva de configuració regional amb LocaleChain.NET

La jerarquia CultureInfo.Parent integrada a .NET només utilitza el truncament BCP 47: pt-BR recorre a pt i després a InvariantCulture i omet pt-PT. LocaleChain.NET proporciona cadenes de reserva configurables per configuració regional per a tot l'ecosistema .NET.

Sense LocaleChain.NET, un usuari de pt-BR veu el text en anglès quan falta una cadena en portuguès, encara que disposi d'una traducció completa a pt-PT. El mateix problema afecta es-MX (omet es-419), zh-Hant (omet zh-Hans) i desenes d'altres variants regionals.
Terminal
dotnet add package I18nAgent.LocaleChain
Program.cs
using I18nAgent.LocaleChain;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddLocalization(o => o.ResourcesPath = "Resources");

// Zero-config: built-in chains (pt-BR -> pt-PT -> pt -> en, etc.)
LocaleChain.Configure();

// Or customize specific chains:
LocaleChain.Configure(new Dictionary<string, string[]>
{
    ["pt-BR"] = new[] { "pt-PT", "pt", "en" },
    ["es-MX"] = new[] { "es-419", "es", "en" },
});

// Register the chain-aware string localizer
builder.Services.AddSingleton(
    typeof(IStringLocalizer<>),
    typeof(LocaleChainStringLocalizer<>));

Errors habituals

La cultura no està definida a la sol·licitud

Les traduccions sempre es mostren en la llengua per defecte. Comprovi que es cridi UseRequestLocalization() a la canalització de programari intermedi i que els proveïdors de cultura estiguin configurats. Verifiqui que el navegador enviï capçaleres Accept-Language. Faci una prova amb ?culture=de a la cadena de consulta per confirmar que el programari intermedi funciona.

No s'ha trobat el fitxer RESX

IStringLocalizer retorna el nom de la clau en lloc del valor traduït. La causa més habitual és que el nom d'un fitxer RESX no coincideixi amb el camí complet de l'espai de noms de la classe en relació amb ResourcesPath. Activi el registre de depuració de Microsoft.Extensions.Localization per veure quins camins cerca el sistema.

L'ordre del programari intermedi és incorrecte

UseRequestLocalization() ha d'aparèixer abans de UseEndpoints() i MapControllers(). Si es col·loca després, la cultura de la sol·licitud no està definida quan s'executen els controladors. En l'allotjament mínim de .NET 6+, cridi’l abans de app.MapControllers().

El fil en segon pla utilitza una cultura incorrecta

CultureInfo.CurrentCulture i CurrentUICulture són específiques de cada fil. Les tasques en segon pla (Task.Run, serveis allotjats) hereten la cultura del grup de fils, no la de la sol·licitud. Capturi i defineixi explícitament la cultura quan distribueixi feina en segon pla.

Estructura de projecte recomanada

Project Structure
MyAspNetApp/
├── Controllers/
│   └── HomeController.cs
├── ViewModels/
│   └── RegisterViewModel.cs
├── Views/
│   └── Home/
│       └── Index.cshtml
├── Resources/
│   ├── Controllers/
│   │   ├── HomeController.en.resx     # English (source)
│   │   ├── HomeController.de.resx     # German
│   │   └── HomeController.ja.resx     # Japanese
│   ├── ViewModels/
│   │   ├── RegisterViewModel.en.resx
│   │   └── RegisterViewModel.de.resx
│   ├── Views/Home/
│   │   ├── Index.en.resx
│   │   └── Index.de.resx
│   └── SharedResource.en.resx
├── SharedResource.cs                  # Marker class
├── Program.cs
└── MyAspNetApp.csproj

Provar i18n Agent ara

Arrossegar aquí el fitxer de traducció

JSON, YAML, PO, XML, CSV, Markdown, Properties

o fer clic per explorar

Idiomes de destinació

No cal registrePressupost instantani

Reserva de configuració regional amb I18nAgent.LocaleChain

Quan falta una clau de traducció en una configuració regional com pt-BR, .NET passa directament a la cultura invariant en lloc de comprovar primer la configuració regional pare (pt).

Terminal
dotnet add package I18nAgent.LocaleChain
Configuration
using I18nAgent.LocaleChain;

LocaleChain.Configure(new Dictionary<string, string[]>
{
    ["pt-BR"] = new[] {"pt", "en"},
    ["zh-Hant-HK"] = new[] {"zh-Hant", "zh", "en"},
});

Consulti la nostra guia de reserva de configuració regional per veure la llista completa de entorns de treball compatibles i les 75 cadenes integrades. Learn more →

Preguntes freqüents