Dela via

ASP.NET Core Blazor globalisering och lokalisering

  • Artikel

Notis

Det här är inte den senaste versionen av den här artikeln. För den aktuella utgåvan, se .NET 9-versionen av den här artikeln.

Varning

Den här versionen av ASP.NET Core stöds inte längre. Mer information finns i .NET och .NET Core Support Policy. För den aktuella utgåvan, se .NET 9-versionen av den här artikeln.

Viktig

Den här informationen gäller en förhandsversionsprodukt som kan ändras avsevärt innan den släpps kommersiellt. Microsoft lämnar inga garantier, uttryckliga eller underförstådda, med avseende på den information som tillhandahålls här.

För den aktuella utgåvan, se .NET 9-versionen av den här artikeln.

Den här artikeln beskriver hur du återger globaliserat och lokaliserat innehåll till användare i olika kulturer och språk.

Globalisering och lokalisering

För globaliseringtillhandahåller Blazor tal- och datumformatering. För lokaliseringrenderar Blazor innehåll med hjälp av .NET-resurssystem.

En begränsad uppsättning ASP.NET Cores lokaliseringsfunktioner stöds:

✔️ IStringLocalizer och IStringLocalizer<T> stöds i Blazor appar.

IHtmlLocalizer, IViewLocalizeroch Data Annotations-lokalisering är ASP.NET Core MVC-funktioner och stöds inte i Blazor appar.

Den här artikeln beskriver hur du använder Blazorglobaliserings- och lokaliseringsfunktioner baserat på:

  • Accept-Language-huvudet, som anges av webbläsaren baserat på användarens språkinställningar i webbläsarinställningarna.
  • En kultur som är inställd av appen, inte baserad på värdet för rubriken Accept-Language. Inställningen kan vara statisk för alla användare eller dynamisk baserat på applogik. När inställningen baseras på användarens inställningar sparas vanligtvis inställningen för att läsas in igen vid framtida besök.

Mer allmän information finns i följande resurser:

Ofta används termerna språk och kultur omväxlande vid hantering av globaliserings- och lokaliseringsbegrepp.

I den här artikeln refererar språk till val som gjorts av en användare i webbläsarens inställningar. Användarens språkval skickas i webbläsarbegäranden i Accept-Language-rubriken. Webbläsarinställningar använder vanligtvis ordet "språk" i användargränssnittet.

Culture avser medlemmar i .NET och Blazor API. En användares begäran kan till exempel innehålla Accept-Language rubrik ange ett språk från användarens perspektiv, men appen anger slutligen egenskapen CurrentCulture ("kultur") från det språk som användaren begärde. API använder vanligtvis ordet "kultur" i sina medlemsnamn.

Vägledningen i den här artikeln beskriver inte hur du ställer in sidans HTML-språkattribut (<html lang="...">), som accessiblity-verktyg använder. Du kan ange värdet statiskt genom att tilldela ett språk till lang-attributet för taggen <html> eller till document.documentElement.lang i JavaScript. Du kan dynamiskt ange värdet för document.documentElement.lang med JS interop.

Notis

Kodexemplen i den här artikeln använder nullbara referenstyper (NRT) och .NET-kompilatorn null-state static analysis, som stöds i ASP.NET Core i .NET 6 eller senare. När du riktar in dig på ASP.NET Core 5.0 eller tidigare tar du bort null-typbeteckningen (?) från artikelns exempel.

Globalisering

@bind-attributdirektivet tillämpar format och parsar värden för visning baserat på användarens första föredragna språk som appen stöder. @bind stöder parametern @bind:culture för att tillhandahålla en System.Globalization.CultureInfo för parsning och formatering av ett värde.

Den aktuella kulturinställningen kan nås via egenskapen System.Globalization.CultureInfo.CurrentCulture.

CultureInfo.InvariantCulture används för följande fälttyper (<input type="{TYPE}" />, där platshållaren {TYPE} är typen):

  • date
  • number

De föregående fälttyperna:

  • Visas med hjälp av lämpliga webbläsarbaserade formateringsregler.
  • Kan inte innehålla fri text.
  • Ange egenskaper för användarinteraktion baserat på webbläsarens implementering.

Blazor ger inbyggt stöd för att återge värden i den aktuella kulturen. Därför rekommenderas inte att du anger en kultur med @bind:culture när du använder fälttyperna date och number.

Följande fälttyper har specifika formateringskrav och stöds inte av alla större webbläsare, så de stöds inte av Blazor:

  • datetime-local
  • month
  • week

Aktuellt webbläsarstöd för de föregående typerna finns i Kan jag använda.

Stöd för .NET-globalisering och internationella komponenter för Unicode (ICU) (Blazor WebAssembly)

Blazor WebAssembly använder ett reducerat globaliserings-API och en uppsättning inbyggda International Components for Unicode (ICU) -lokaler. För mer information, se .NET-globalisering och ICU: ICU på WebAssembly.

Information om hur du läser in en anpassad ICU-datafil för att styra appens nationella inställningar finns i WASM Globalization Icu. För närvarande krävs manuellt skapande av den anpassade ICU-datafilen. .NET-verktyg för att underlätta processen med att skapa filen planeras för .NET 10 i november 2025.

Blazor WebAssembly använder ett reducerat globaliserings-API och en uppsättning inbyggda International Components for Unicode (ICU) -lokaler. För mer information, se .NET-globalisering och ICU: ICU på WebAssembly.

Inläsning av en anpassad delmängd av nationella inställningar i en Blazor WebAssembly app stöds i .NET 8 eller senare. För mer information, gå till det här avsnittet för version 8.0 av den här artikeln eller senare.

Invariant globalisering

Det här avsnittet gäller endast för scenarier på klientsidan Blazor.

Om appen inte kräver lokalisering konfigurerar du appen så att den stöder den invarianta kulturen, som vanligtvis baseras på engelska i USA (en-US). Om du använder invariant globalisering minskar appens nedladdningsstorlek och resulterar i snabbare appstart. Ange egenskapen InvariantGlobalization till true i appens projektfil (.csproj):

<PropertyGroup>
  <InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>

Du kan också konfigurera invariant globalisering med följande metoder:

  • I runtimeconfig.json:

    {
  "runtimeOptions": {
    "configProperties": {
      "System.Globalization.Invariant": true
    }
  }
}

  • Med en miljövariabel:

    • Nyckel: DOTNET_SYSTEM_GLOBALIZATION_INVARIANT
    • Värde: true eller 1

Mer information finns i Körningskonfigurationsalternativ för globalisering (.NET-dokumentation).

Tidszonsinformation

Det här avsnittet gäller endast för scenarier på klientsidan Blazor.

Att införa invariant globalisering resulterar bara i att icke-lokaliserade tidszonsnamn används. Om du vill trimma tidszonskod och data, vilket minskar appens nedladdningsstorlek och resulterar i snabbare appstart, använder du egenskapen <InvariantTimezone> MSBuild med värdet true i appens projektfil:

<PropertyGroup>
  <InvariantTimezone>true</InvariantTimezone>
</PropertyGroup>

Notis

<BlazorEnableTimeZoneSupport> åsidosätter en tidigare <InvariantTimezone> inställning. Vi rekommenderar att du tar bort inställningen <BlazorEnableTimeZoneSupport>.

En datafil ingår för att göra tidszonsinformationen korrekt. Om appen inte kräver den här funktionen kan du inaktivera den genom att ange egenskapen <BlazorEnableTimeZoneSupport> MSBuild till false i appens projektfil:

<PropertyGroup>
  <BlazorEnableTimeZoneSupport>false</BlazorEnableTimeZoneSupport>
</PropertyGroup>

Demonstrationskomponent

Följande CultureExample1 komponent kan användas för att demonstrera Blazor globaliserings- och lokaliseringsbegrepp som beskrivs i den här artikeln.

CultureExample1.razor:

@page "/culture-example-1"
@using System.Globalization

<h1>Culture Example 1</h1>

<ul>
    <li><b>CurrentCulture</b>: @CultureInfo.CurrentCulture</li>
    <li><b>CurrentUICulture</b>: @CultureInfo.CurrentUICulture</li>
</ul>

<h2>Rendered values</h2>

<ul>
    <li><b>Date</b>: @dt</li>
    <li><b>Number</b>: @number.ToString("N2")</li>
</ul>

<h2><code>&lt;input&gt;</code> elements that don't set a <code>type</code></h2>

<p>
    The following <code>&lt;input&gt;</code> elements use
    <code>CultureInfo.CurrentCulture</code>.
</p>

<ul>
    <li><label><b>Date:</b> <input @bind="dt" /></label></li>
    <li><label><b>Number:</b> <input @bind="number" /></label></li>
</ul>

<h2><code>&lt;input&gt;</code> elements that set a <code>type</code></h2>

<p>
    The following <code>&lt;input&gt;</code> elements use
    <code>CultureInfo.InvariantCulture</code>.
</p>

<ul>
    <li><label><b>Date:</b> <input type="date" @bind="dt" /></label></li>
    <li><label><b>Number:</b> <input type="number" @bind="number" /></label></li>
</ul>

@code {
    private DateTime dt = DateTime.Now;
    private double number = 1999.69;
}

Talsträngsformatet (N2) i föregående exempel (.ToString("N2")) är ett standardformatsspecificerare för .NET-format. Formatet N2 stöds för alla numeriska typer, innehåller en gruppavgränsare och återger upp till två decimaler.

Du kan också lägga till ett menyalternativ i navigeringen i komponenten NavMenu (NavMenu.razor) för komponenten CultureExample1.

Ange kulturen dynamiskt från Accept-Language-huvudet

Lägg till Microsoft.Extensions.Localization-paketet i appen.

Accept-Language-huvudet anges av webbläsaren och styrs av användarens språkinställningar i webbläsarinställningarna. I webbläsarinställningar anger en användare ett eller flera önskade språk i prioritetsordning. Prioritetsordningen används av webbläsaren för att ange kvalitetsvärden (q, 0–1) för varje språk i rubriken. I följande exempel anges amerikansk engelska, engelska och costaricansk spanska med en preferens för amerikansk engelska eller engelska.

Accept-Language: en-US,en; q=0.9,es-CR; q=0,8

Appens kultur anges genom att matcha det första begärda språket som matchar en kultur som stöds av appen.

I utveckling på klientsidananger du egenskapen BlazorWebAssemblyLoadAllGlobalizationData till true i klientappens projektfil (.csproj):

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

I utveckling på klientsidanstöds inte den dynamiska inställningen av kulturen från Accept-Language header.

Notis

Om appens specifikation kräver att de kulturer som stöds begränsas till en explicit lista, se Dynamiskt ange klientsidans kultur enligt användarens inställning avsnittet i den här artikeln.

Appar lokaliseras med Localization Middleware. Lägg till lokaliseringstjänster i appen med AddLocalization.

Lägg till följande rad i filen Program där tjänster är registrerade:

builder.Services.AddLocalization();

I utveckling på serversidanbör appens stödda kulturer anges före eventuell middleware som kan kontrollera begärandekulturen. Placera i allmänhet Mellanprogram för lokalisering av begäran omedelbart innan du anropar MapRazorComponents. I följande exempel konfigureras kulturer som stöds för engelska och costaricanska spanska i USA:

I utveckling på serversidananger du appens kulturer som stöds omedelbart efter att Routing Middleware (UseRouting) har lagts till i bearbetningspipelinen. I följande exempel konfigureras kulturer som stöds för engelska och costaricanska spanska i USA:

app.UseRequestLocalization(new RequestLocalizationOptions()
    .AddSupportedCultures(new[] { "en-US", "es-CR" })
    .AddSupportedUICultures(new[] { "en-US", "es-CR" }));

Information om hur du beställer lokaliseringsmiddleware i middleware-pipelinen för Program-filen finns i ASP.NET Core Middleware.

Använd komponenten CultureExample1 som visas i avsnittet Demonstration för att studera hur globaliseringen fungerar. Utfärda en begäran med engelska i USA (en-US). Växla till spanska på Costa Rica (es-CR) i webbläsarens språkinställningar. Begär webbsidan igen.

När kulturen är amerikansk engelska (en-US) använder den renderade komponenten datumformatering månad/dag (6/7), 12-timmars tid (AM/PM) och kommaavgränsare i tal med en punkt för decimalvärdet (1,999.69):

  • datum: 2021-06-07 06:45:22
  • Nummer: 1 999,69

När kulturen är spanska på Costa Rica (es-CR) använder den renderade komponenten datumformatering dag/månad (7/6), 24-timmars tid och periodavgränsare i tal med kommatecken för decimalvärdet (1.999,69):

  • Datum: 2021-07-06 06:49:38
  • Nummer: 1 999,69

Ange kulturen på klientsidan statiskt

Ange egenskapen BlazorWebAssemblyLoadAllGlobalizationData till true i appens projektfil (.csproj):

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

Konfigurationen för Intermediate Language (IL)-linkern vid rendering på klientsidan tar bort information om internationalisering, förutom för de språk som uttryckligen begärts. Mer information finns i Konfigurera Linker för ASP.NET Core Blazor.

Appens kultur kan anges i JavaScript när Blazor börjar med startalternativet applicationCultureBlazor. I följande exempel konfigureras appen så att den startar med hjälp av kulturen Engelska (en-US) i USA.

Förhindra Blazor automatisk start genom att lägga till autostart="false" i Blazor<script> tagg:

<script src="{BLAZOR SCRIPT}" autostart="false"></script>

I det föregående exemplet representerar platshållaren {BLAZOR SCRIPT} skriptsökvägen och filnamnet för Blazor. Platsen för skriptet finns i ASP.NET Core Blazor projektstruktur.

Lägg till följande <script> efter Blazor<script> tagg och före den avslutande </body> taggen:

Blazor Web App:

<script>
  Blazor.start({
    webAssembly: {
      applicationCulture: 'en-US'
    }
  });
</script>

Fristående Blazor WebAssembly:

<script>
  Blazor.start({
    applicationCulture: 'en-US'
  });
</script>

Värdet för applicationCulture måste överensstämma med BCP-47-språktaggformatet. Mer information om Blazor-uppstart finns i ASP.NET Core Blazor-uppstart.

Ett alternativ till att ange kulturens Blazorstartalternativ är att ange kulturen i C#-koden. Ange CultureInfo.DefaultThreadCurrentCulture och CultureInfo.DefaultThreadCurrentUICulture i filen Program till samma kultur.

Lägg till System.Globalization-namnområdet i filen Program:

using System.Globalization;

Lägg till kulturinställningarna före raden som bygger och kör WebAssemblyHostBuilder (await builder.Build().RunAsync();):

CultureInfo.DefaultThreadCurrentCulture = new CultureInfo("en-US");
CultureInfo.DefaultThreadCurrentUICulture = new CultureInfo("en-US");

Notis

För närvarande läser Blazor WebAssembly appar bara in resurser baserat på DefaultThreadCurrentCulture. För mer information, se Blazor WASM förlitar sig endast på den aktuella kulturen (den aktuella användargränssnittskulturen respekteras inte) (dotnet/aspnetcore #56824).

Använd komponenten CultureExample1 som visas i avsnittet Demonstration för att studera hur globaliseringen fungerar. Utfärda en begäran med engelska i USA (en-US). Växla till spanska på Costa Rica (es-CR) i webbläsarens språkinställningar. Begär webbsidan igen. När det begärda språket är spanska i Costa Rica förblir appens kultur amerikansk engelska (en-US).

Ange kulturen på serversidan statiskt

Appar på serversidan lokaliseras med hjälp av Localization Middleware. Lägg till lokaliseringstjänster i appen med AddLocalization.

I filen Program:

builder.Services.AddLocalization();

Ange den statiska kulturen i filen Program före något mellanlager som kan undersöka begäranens kultur. Placera i allmänhet Mellanprogram för lokalisering av begäran omedelbart före MapRazorComponents. I följande exempel konfigureras engelska i USA:

Ange statisk kultur i filen Program omedelbart efter att Routing Middleware (UseRouting) har lagts till i bearbetningspipelinen. I följande exempel konfigureras engelska i USA:

app.UseRequestLocalization("en-US");

Kulturvärdet för UseRequestLocalization måste överensstämma med BCP-47-språktaggformatet.

Information om hur du beställer lokaliseringsmiddleware i middleware-pipelinen för Program-filen finns i ASP.NET Core Middleware.

Appar på serversidan lokaliseras med hjälp av Localization Middleware. Lägg till lokaliseringstjänster i appen med AddLocalization.

I Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

Ange den statiska kulturen i Startup.Configure (Startup.cs) direkt efter att routningsmellanprogram har lagts till i bearbetningspipelinen. I följande exempel konfigureras engelska i USA:

app.UseRequestLocalization("en-US");

Kulturvärdet för UseRequestLocalization måste överensstämma med BCP-47-språktaggformatet.

För information om att beställa Mellanprogram för lokalisering i mellanprogramspipelinen i Startup.Configure, se ASP.NET Core Middleware.

Använd komponenten CultureExample1 som visas i avsnittet Demonstration för att studera hur globaliseringen fungerar. Utfärda en begäran med engelska i USA (en-US). Växla till spanska på Costa Rica (es-CR) i webbläsarens språkinställningar. Begär webbsidan igen. När det begärda språket är spanska i Costa Rica förblir appens kultur amerikansk engelska (en-US).

Ange kulturen på klientsidan dynamiskt efter användarinställningar

Exempel på platser där en app kan lagra en användares inställningar är i webbläsarlokal lagring (vanligt för scenarier på klientsidan), i en lokalisering cookie eller databas (vanlig för scenarier på serversidan) eller i en extern tjänst som är kopplad till en extern databas och som används av en webb-API. I följande exempel visas hur du använder webbläsarens lokala lagring.

Lägg till Microsoft.Extensions.Localization-paketet i appen.

Notis

Mer information om hur du lägger till paket i .NET-appar finns i artiklarna under Installera och hantera paket på Arbetsflöde för paketförbrukning (NuGet-dokumentation). Bekräfta rätt paketversioner på NuGet.org.

Ange egenskapen BlazorWebAssemblyLoadAllGlobalizationData till true i projektfilen:

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

Appens kultur för återgivning på klientsidan anges med hjälp av api:et för Blazor framework. En användares kulturval kan sparas i webbläsarens lokala lagring.

Ange JS funktioner efter Blazor<script> tagg för att hämta och ange användarens kulturval med lokal webbläsarlagring:

<script>
  window.blazorCulture = {
    get: () => window.localStorage['BlazorCulture'],
    set: (value) => window.localStorage['BlazorCulture'] = value
  };
</script>

Notis

Föregående exempel förorenar klienten med globala funktioner. En bättre metod i produktionsappar finns i JavaScript-isolering i JavaScript-moduler.

Lägg till namnrymderna för System.Globalization och Microsoft.JSInterop överst i filen Program:

using System.Globalization;
using Microsoft.JSInterop;

Ta bort följande rad:

- await builder.Build().RunAsync();

Ersätt föregående rad med följande kod. Koden lägger till Blazorlokaliseringstjänst i appens tjänstsamling med AddLocalization och använder JS interop för att anropa JS och hämta användarens kulturval från lokal lagring. Om lokal lagring inte innehåller en kultur för användaren anger koden standardvärdet Engelska (en-US).

builder.Services.AddLocalization();

var host = builder.Build();

const string defaultCulture = "en-US";

var js = host.Services.GetRequiredService<IJSRuntime>();
var result = await js.InvokeAsync<string>("blazorCulture.get");
var culture = CultureInfo.GetCultureInfo(result ?? defaultCulture);

if (result == null)
{
    await js.InvokeVoidAsync("blazorCulture.set", defaultCulture);
}

CultureInfo.DefaultThreadCurrentCulture = culture;
CultureInfo.DefaultThreadCurrentUICulture = culture;

await host.RunAsync();

Notis

För närvarande läser Blazor WebAssembly appar bara in resurser baserat på DefaultThreadCurrentCulture. För mer information, se Blazor WASM förlitar sig endast på den aktuella kulturen (den aktuella användargränssnittskulturen respekteras inte) (dotnet/aspnetcore #56824).

Följande CultureSelector-komponent visar hur du utför följande åtgärder:

  • Ange användarens kulturval i webbläsarens lokala lagring via JS interop.
  • Ladda om komponenten som de begärde (forceLoad: true), som använder den uppdaterade kulturinställningen.

CultureSelector.razor:

@using System.Globalization
@inject IJSRuntime JS
@inject NavigationManager Navigation

<p>
    <label>
        Select your locale:
        <select @bind="selectedCulture" @bind:after="ApplySelectedCultureAsync">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@culture.DisplayName</option>
            }
        </select>
    </label>
</p>

@code
{
    private CultureInfo[] supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("es-CR"),
    };

    private CultureInfo? selectedCulture;

    protected override void OnInitialized()
    {
        selectedCulture = CultureInfo.CurrentCulture;
    }

    private async Task ApplySelectedCultureAsync()
    {
        if (CultureInfo.CurrentCulture != selectedCulture)
        {
            await JS.InvokeVoidAsync("blazorCulture.set", selectedCulture!.Name);

            Navigation.NavigateTo(Navigation.Uri, forceLoad: true);
        }
    }
}

@using System.Globalization
@inject IJSRuntime JS
@inject NavigationManager Navigation

<p>
    <label>
        Select your locale:
        <select value="@selectedCulture" @onchange="HandleSelectedCultureChanged">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@culture.DisplayName</option>
            }
        </select>
    </label>
</p>

@code
{
    private CultureInfo[] supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("es-CR"),
    };

    private CultureInfo? selectedCulture;

    protected override void OnInitialized()
    {
        selectedCulture = CultureInfo.CurrentCulture;
    }

    private async Task HandleSelectedCultureChanged(ChangeEventArgs args)
    {
        selectedCulture = CultureInfo.GetCultureInfo((string)args.Value!);

        if (CultureInfo.CurrentCulture != selectedCulture)
        {
            await JS.InvokeVoidAsync("blazorCulture.set", selectedCulture!.Name);

            Navigation.NavigateTo(Navigation.Uri, forceLoad: true);
        }
    }
}

Notis

Mer information om IJSInProcessRuntimefinns i Anropa JavaScript-funktioner från .NET-metoder i ASP.NET Core Blazor.

Lägg till </main>-komponenten i den avslutande taggen för MainLayout-elementet i MainLayout.razor -komponenten (CultureSelector).

<article class="bottom-row px-4">
    <CultureSelector />
</article>

Använd komponenten CultureExample1 som visas i avsnittet Demonstration för att studera hur föregående exempel fungerar.

Ange kulturen på serversidan dynamiskt efter användarinställningar

Exempel på platser där en app kan lagra en användares inställningar är i webbläsarlokal lagring (vanligt för scenarier på klientsidan), i en lokalisering cookie eller databas (vanlig för scenarier på serversidan) eller i en extern tjänst som är kopplad till en extern databas och som används av en webb-API. I följande exempel visas hur du använder en lokalisering cookie.

Notis

I följande exempel förutsätts att appen använder global interaktivitet genom att ange interaktiv återgivning på serversidan (interaktiv SSR) på komponenten Routes i komponenten App (Components/App.razor):

<Routes @rendermode="InteractiveServer" />

Om appen använder per sida/komponent interaktivitet, se kommentarerna i slutet av det här avsnittet för att ändra återgivningslägena för exemplets komponenter.

Lägg till Microsoft.Extensions.Localization-paketet i appen.

Notis

Mer information om hur du lägger till paket i .NET-appar finns i artiklarna under Installera och hantera paket på Arbetsflöde för paketförbrukning (NuGet-dokumentation). Bekräfta rätt paketversioner på NuGet.org.

Appar på serversidan lokaliseras med hjälp av Localization Middleware. Lägg till lokaliseringstjänster i appen med AddLocalization.

I filen Program:

builder.Services.AddLocalization();

Ange appens standardkulturer och kulturer som stöds med RequestLocalizationOptions.

Innan anropet till MapRazorComponents i pipelinen för bearbetning av begäran placerar du följande kod:

När routningsmellanprogram (UseRouting) har lagts till i begärans bearbetningspipeline, placera följande kod:

var supportedCultures = new[] { "en-US", "es-CR" };
var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

Information om hur du beställer Mellanprogram för lokalisering i pipelinen för mellanprogram finns i ASP.NET Core Middleware.

I följande exempel visas hur du anger den aktuella kulturen i en cookie som kan läsas av lokaliseringsmellanprogrammet.

Följande namnområden krävs för komponenten App:

Lägg till följande längst upp i App komponentfilen (Components/App.razor):

@using System.Globalization
@using Microsoft.AspNetCore.Localization

Lägg till följande @code block längst ned i App komponentfilen:

@code {
    [CascadingParameter]
    public HttpContext? HttpContext { get; set; }

    protected override void OnInitialized()
    {
        HttpContext?.Response.Cookies.Append(
            CookieRequestCultureProvider.DefaultCookieName,
            CookieRequestCultureProvider.MakeCookieValue(
                new RequestCulture(
                    CultureInfo.CurrentCulture,
                    CultureInfo.CurrentUICulture)));
    }
}

Ändringar av Pages/_Host.cshtml-filen kräver följande namnområden:

Lägg till följande i filen:

@using System.Globalization
@using Microsoft.AspNetCore.Localization
@{
    this.HttpContext.Response.Cookies.Append(
        CookieRequestCultureProvider.DefaultCookieName,
        CookieRequestCultureProvider.MakeCookieValue(
            new RequestCulture(
                CultureInfo.CurrentCulture,
                CultureInfo.CurrentUICulture)));
}

Information om hur du beställer Mellanprogram för lokalisering i pipelinen för mellanprogram finns i ASP.NET Core Middleware.

Om appen inte är konfigurerad för att bearbeta kontrollantåtgärder:

  • Lägg till MVC-tjänster genom att anropa AddControllers på tjänstsamlingen i filen Program:

    builder.Services.AddControllers();

  • Lägg till kontrollantens slutpunktsroutning i Program-filen genom att anropa MapControllers på IEndpointRouteBuilder (app):

    app.MapControllers();

Använd en omdirigeringsbaserad metod med en lokalisering cookieom du vill ange användargränssnittet så att en användare kan välja en kultur. Appen bevarar användarens valda kultur via en omdirigering till en kontrollant. Kontrollanten anger användarens valda kultur till en cookie och omdirigerar användaren tillbaka till den ursprungliga URI:n. Processen liknar vad som händer i en webbapp när en användare försöker komma åt en säker resurs, där användaren omdirigeras till en inloggningssida och sedan omdirigeras tillbaka till den ursprungliga resursen.

Controllers/CultureController.cs:

using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;

[Route("[controller]/[action]")]
public class CultureController : Controller
{
    public IActionResult Set(string culture, string redirectUri)
    {
        if (culture != null)
        {
            HttpContext.Response.Cookies.Append(
                CookieRequestCultureProvider.DefaultCookieName,
                CookieRequestCultureProvider.MakeCookieValue(
                    new RequestCulture(culture, culture)));
        }

        return LocalRedirect(redirectUri);
    }
}

Varning

Använd LocalRedirect åtgärdsresultatet, som du ser i föregående exempel, för att förhindra öppna omdirigeringsattacker. Mer information finns i Förhindra öppna omdirigeringsattacker i ASP.NET Core.

Följande CultureSelector-komponent visar hur du anropar Set-metoden för CultureController med den nya kulturen. Komponenten placeras i mappen Shared för användning i hela appen.

CultureSelector.razor:

@using System.Globalization
@inject IJSRuntime JS
@inject NavigationManager Navigation

<p>
    <label>
        Select your locale:
        <select @bind="selectedCulture" @bind:after="ApplySelectedCultureAsync">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@culture.DisplayName</option>
            }
        </select>
    </label>
</p>

@code
{
    private CultureInfo[] supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("es-CR"),
    };

    private CultureInfo? selectedCulture;

    protected override void OnInitialized()
    {
        selectedCulture = CultureInfo.CurrentCulture;
    }

    private async Task ApplySelectedCultureAsync()
    {
        if (CultureInfo.CurrentCulture != selectedCulture)
        {
            var uri = new Uri(Navigation.Uri)
                .GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
            var cultureEscaped = Uri.EscapeDataString(selectedCulture.Name);
            var uriEscaped = Uri.EscapeDataString(uri);

            Navigation.NavigateTo(
                $"Culture/Set?culture={cultureEscaped}&redirectUri={uriEscaped}",
                forceLoad: true);
        }
    }
}

@using System.Globalization
@inject IJSRuntime JS
@inject NavigationManager Navigation

<p>
    <label>
        Select your locale:
        <select value="@selectedCulture" @onchange="HandleSelectedCultureChanged">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@culture.DisplayName</option>
            }
        </select>
    </label>
</p>

@code
{
    private CultureInfo[] supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("es-CR"),
    };

    private CultureInfo? selectedCulture;

    protected override void OnInitialized()
    {
        selectedCulture = CultureInfo.CurrentCulture;
    }

    private async Task HandleSelectedCultureChanged(ChangeEventArgs args)
    {
        selectedCulture = CultureInfo.GetCultureInfo((string)args.Value!);

        if (CultureInfo.CurrentCulture != selectedCulture)
        {
            var uri = new Uri(Navigation.Uri)
                .GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
            var cultureEscaped = Uri.EscapeDataString(selectedCulture.Name);
            var uriEscaped = Uri.EscapeDataString(uri);

            Navigation.NavigateTo(
                $"Culture/Set?culture={cultureEscaped}&redirectUri={uriEscaped}",
                forceLoad: true);
        }
    }
}

Lägg till komponenten CultureSelector i komponenten MainLayout. Placera följande markering i den avslutande </main>-taggen i Components/Layout/MainLayout.razor-filen:

Lägg till komponenten CultureSelector i komponenten MainLayout. Placera följande markering i den avslutande </main>-taggen i Shared/MainLayout.razor-filen:

<article class="bottom-row px-4">
    <CultureSelector />
</article>

Använd komponenten CultureExample1 som visas i avsnittet Demonstration för att studera hur föregående exempel fungerar.

I föregående exempel förutsätts att appen använder global interaktivitet genom att ange det interaktiva server-återgivningsläget på Routes-komponenten i komponenten App (Components/App.razor):

<Routes @rendermode="InteractiveServer" />

Om appen antar per sida/komponent interaktivitet gör du följande ändringar:

  • Lägg till det interaktiva serverläget högst upp i komponentfilen CultureExample1 (Components/Pages/CultureExample1.razor):

    @rendermode InteractiveServer

  • I appens huvudlayout (Components/Layout/MainLayout.razor) tillämpar du återgivningsläget interaktiv server på CultureSelector komponenten:

    <CultureSelector @rendermode="InteractiveServer" />

Ställ in kulturen dynamiskt i en Blazor Web App enligt användarens preferenser

Det här avsnittet gäller för Blazor Web Appsom använder autointeraktivitet (Server och WebAssembly).

Exempel på platser där en app kan lagra en användares inställningar är i webbläsarlokal lagring (vanligt för scenarier på klientsidan), i en lokalisering cookie eller databas (vanlig för scenarier på serversidan), både lokal lagring och lokalisering cookie (Blazor Web Appmed server- och WebAssembly-komponenter) eller i en extern tjänst som är kopplad till en extern databas och som nås av en webb-API. I följande exempel visas hur du använder webbläsarens lokala lagring för renderade komponenter på klientsidan (CSR) och en lokalisering cookie för SSR-komponenter (serversidan).

Uppdateringar av .Client-projektet

Lägg till Microsoft.Extensions.Localization-paketet i projektet .Client.

Notis

Mer information om hur du lägger till paket i .NET-appar finns i artiklarna under Installera och hantera paket på Arbetsflöde för paketförbrukning (NuGet-dokumentation). Bekräfta rätt paketversioner på NuGet.org.

Ange egenskapen BlazorWebAssemblyLoadAllGlobalizationData till true i .Client-projektfilen:

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

Lägg till namnrymderna för System.Globalization och Microsoft.JSInterop överst i .Client-projektets Program-fil:

using System.Globalization;
using Microsoft.JSInterop;

Ta bort följande rad:

- await builder.Build().RunAsync();

Ersätt föregående rad med följande kod. Koden lägger till Blazorlokaliseringstjänst i appens tjänstsamling med AddLocalization och använder JS interop för att anropa JS och hämta användarens kulturval från lokal lagring. Om lokal lagring inte innehåller en kultur för användaren anger koden standardvärdet Engelska (en-US).

builder.Services.AddLocalization();

var host = builder.Build();

const string defaultCulture = "en-US";

var js = host.Services.GetRequiredService<IJSRuntime>();
var result = await js.InvokeAsync<string>("blazorCulture.get");
var culture = CultureInfo.GetCultureInfo(result ?? defaultCulture);

if (result == null)
{
    await js.InvokeVoidAsync("blazorCulture.set", defaultCulture);
}

CultureInfo.DefaultThreadCurrentCulture = culture;
CultureInfo.DefaultThreadCurrentUICulture = culture;

await host.RunAsync();

Notis

För närvarande läser Blazor WebAssembly appar bara in resurser baserat på DefaultThreadCurrentCulture. För mer information, se Blazor WASM förlitar sig endast på den aktuella kulturen (den aktuella användargränssnittskulturen respekteras inte) (dotnet/aspnetcore #56824).

Lägg till följande CultureSelector komponent i .Client-projektet.

Komponenten använder följande metoder för att arbeta för antingen SSR- eller CSR-komponenter:

  • Visningsnamnet för varje tillgänglig kultur i listrutan tillhandahålls av en ordlista eftersom globaliseringsdata på klientsidan innehåller lokaliserad text med kulturvisningsnamn som globaliseringsdata på serversidan tillhandahåller. Lokalisering på serversidan visar till exempel English (United States) när en-US är kulturen och Ingles () när en annan kultur används. Eftersom lokalisering av kulturernas visningsnamn inte är tillgängligt med Blazor WebAssembly-globalisering, blir visningsnamnet för amerikansk engelska på klienten för alla inlästa kulturer bara en-US. Om du använder en anpassad ordlista kan komponenten åtminstone visa fullständiga engelska kulturnamn.
  • När användaren ändrar kulturen JS interop anger kulturen i lokal webbläsarlagring och en kontrollantåtgärd uppdaterar lokaliseringen cookie med kulturen. Kontrollanten läggs till i appen senare i avsnittet Server-projektuppdateringar.

Pages/CultureSelector.razor:

@using System.Globalization
@inject IJSRuntime JS
@inject NavigationManager Navigation

<p>
    <label>
        Select your locale:
        <select @bind="@selectedCulture" @bind:after="ApplySelectedCultureAsync">
            @foreach (var culture in supportedCultures)
            {
                <option value="@culture">@cultureDict[culture.Name]</option>
            }
        </select>
    </label>
</p>

@code
{
    private Dictionary<string, string> cultureDict = 
        new()
        {
            { "en-US", "English (United States)" },
            { "es-CR", "Spanish (Costa Rica)" }
        };

    private CultureInfo[] supportedCultures = new[]
    {
        new CultureInfo("en-US"),
        new CultureInfo("es-CR"),
    };

    private CultureInfo? selectedCulture;

    protected override void OnInitialized()
    {
        selectedCulture = CultureInfo.CurrentCulture;
    }

    private async Task ApplySelectedCultureAsync()
    {
        if (CultureInfo.CurrentCulture != selectedCulture)
        {
            await JS.InvokeVoidAsync("blazorCulture.set", selectedCulture!.Name);

            var uri = new Uri(Navigation.Uri)
                .GetComponents(UriComponents.PathAndQuery, UriFormat.Unescaped);
            var cultureEscaped = Uri.EscapeDataString(selectedCulture.Name);
            var uriEscaped = Uri.EscapeDataString(uri);

            Navigation.NavigateTo(
                $"Culture/Set?culture={cultureEscaped}&redirectUri={uriEscaped}",
                forceLoad: true);
        }
    }
}

I .Client-projektets _Imports-fil (_Imports.razor) lägger du till namnområdet för komponenterna i mappen Pages och uppdaterar namnområdet så att det matchar namnet på ditt .Client projekts namnområde:

@using BlazorSample.Client.Pages

Notis

Mer information om IJSInProcessRuntimefinns i Anropa JavaScript-funktioner från .NET-metoder i ASP.NET Core Blazor.

I .Client-projektet lägger du till komponenten CultureSelector i komponenten MainLayout. Placera följande markering i den avslutande </main>-taggen i Layout/MainLayout.razor-filen:

<article class="bottom-row px-4">
    <CultureSelector @rendermode="InteractiveAuto" />
</article>

I det .Client projektet placerar du följande CultureClient komponent för att studera hur globalisering fungerar för CSR-komponenter.

Pages/CultureClient.razor:

@page "/culture-client"
@rendermode InteractiveWebAssembly
@using System.Globalization

<PageTitle>Culture Client</PageTitle>

<h1>Culture Client</h1>

<ul>
    <li><b>CurrentCulture</b>: @CultureInfo.CurrentCulture</li>
    <li><b>CurrentUICulture</b>: @CultureInfo.CurrentUICulture</li>
</ul>

<h2>Rendered values</h2>

<ul>
    <li><b>Date</b>: @dt</li>
    <li><b>Number</b>: @number.ToString("N2")</li>
</ul>

<h2><code>&lt;input&gt;</code> elements that don't set a <code>type</code></h2>

<p>
    The following <code>&lt;input&gt;</code> elements use
    <code>CultureInfo.CurrentCulture</code>.
</p>

<ul>
    <li><label><b>Date:</b> <input @bind="dt" /></label></li>
    <li><label><b>Number:</b> <input @bind="number" /></label></li>
</ul>

<h2><code>&lt;input&gt;</code> elements that set a <code>type</code></h2>

<p>
    The following <code>&lt;input&gt;</code> elements use
    <code>CultureInfo.InvariantCulture</code>.
</p>

<ul>
    <li><label><b>Date:</b> <input type="date" @bind="dt" /></label></li>
    <li><label><b>Number:</b> <input type="number" @bind="number" /></label></li>
</ul>

@code {
    private DateTime dt = DateTime.Now;
    private double number = 1999.69;
}

I det .Client projektet placerar du följande CultureServer komponent för att studera hur globalisering fungerar för SSR-komponenter.

Pages/CultureServer.razor:

@page "/culture-server"
@rendermode InteractiveServer
@using System.Globalization

<PageTitle>Culture Server</PageTitle>

<h1>Culture Server</h1>

<ul>
    <li><b>CurrentCulture</b>: @CultureInfo.CurrentCulture</li>
    <li><b>CurrentUICulture</b>: @CultureInfo.CurrentUICulture</li>
</ul>

<h2>Rendered values</h2>

<ul>
    <li><b>Date</b>: @dt</li>
    <li><b>Number</b>: @number.ToString("N2")</li>
</ul>

<h2><code>&lt;input&gt;</code> elements that don't set a <code>type</code></h2>

<p>
    The following <code>&lt;input&gt;</code> elements use
    <code>CultureInfo.CurrentCulture</code>.
</p>

<ul>
    <li><label><b>Date:</b> <input @bind="dt" /></label></li>
    <li><label><b>Number:</b> <input @bind="number" /></label></li>
</ul>

<h2><code>&lt;input&gt;</code> elements that set a <code>type</code></h2>

<p>
    The following <code>&lt;input&gt;</code> elements use
    <code>CultureInfo.InvariantCulture</code>.
</p>

<ul>
    <li><label><b>Date:</b> <input type="date" @bind="dt" /></label></li>
    <li><label><b>Number:</b> <input type="number" @bind="number" /></label></li>
</ul>

@code {
    private DateTime dt = DateTime.Now;
    private double number = 1999.69;
}

Använd komponenten CultureExample1 som visas i avsnittet Demonstration-komponenten för att studera hur globalisering fungerar för en komponent som ärver det globala läget för automatisk återgivning. Lägg till komponenten CultureExample1 i .Client-projektets Pages mapp.

Lägg till komponenterna CultureClient, CultureServeroch CultureExample1 i sidofältets navigering i Layout/NavMenu.razor:

<div class="nav-item px-3">
    <NavLink class="nav-link" href="culture-server">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> Culture (Server)
    </NavLink>
</div>
<div class="nav-item px-3">
    <NavLink class="nav-link" href="culture-client">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> Culture (Client)
    </NavLink>
</div>
<div class="nav-item px-3">
    <NavLink class="nav-link" href="culture-example-1">
        <span class="bi bi-list-nested-nav-menu" aria-hidden="true"></span> Culture (Auto)
    </NavLink>
</div>

Uppdateringar av serverprojekt

Lägg till Microsoft.Extensions.Localization-paketet i serverprojektet.

Notis

Mer information om hur du lägger till paket i .NET-appar finns i artiklarna under Installera och hantera paket på Arbetsflöde för paketförbrukning (NuGet-dokumentation). Bekräfta rätt paketversioner på NuGet.org.

Appar på serversidan lokaliseras med hjälp av Localization Middleware. Lägg till lokaliseringstjänster i appen med AddLocalization.

I serverprojektets Program fil där tjänster är registrerade:

builder.Services.AddLocalization();

Ange appens standardkulturer och kulturer som stöds med RequestLocalizationOptions.

Innan anropet till MapRazorComponents i pipelinen för bearbetning av begäran placerar du följande kod:

var supportedCultures = new[] { "en-US", "es-CR" };
var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

I följande exempel visas hur du anger den aktuella kulturen i en cookie som kan läsas av lokaliseringsmellanprogrammet.

Följande namnområden krävs för komponenten App:

Lägg till följande längst upp i App komponentfilen (Components/App.razor):

@using System.Globalization
@using Microsoft.AspNetCore.Localization

Appens kultur för återgivning på klientsidan anges med hjälp av api:et för Blazor framework. En användares kulturval kan sparas i webbläsarens lokala lagring för CSR-komponenter.

Efter Blazor:s <script>-tag, ge JS funktioner för att hämta och ange användarens kulturval med webbläsarens lokala lagring.

<script>
  window.blazorCulture = {
    get: () => window.localStorage['BlazorCulture'],
    set: (value) => window.localStorage['BlazorCulture'] = value
  };
</script>

Notis

Föregående exempel förorenar klienten med globala funktioner. En bättre metod i produktionsappar finns i JavaScript-isolering i JavaScript-moduler.

Lägg till följande @code block längst ned i App komponentfilen:

@code {
    [CascadingParameter]
    public HttpContext? HttpContext { get; set; }

    protected override void OnInitialized()
    {
        HttpContext?.Response.Cookies.Append(
            CookieRequestCultureProvider.DefaultCookieName,
            CookieRequestCultureProvider.MakeCookieValue(
                new RequestCulture(
                    CultureInfo.CurrentCulture,
                    CultureInfo.CurrentUICulture)));
    }
}

Om serverprojektet inte är konfigurerat för att bearbeta kontrollantåtgärder:

  • Lägg till MVC-tjänster genom att anropa AddControllers på tjänstsamlingen i filen Program:

    builder.Services.AddControllers();

  • Lägg till kontrollantens slutpunktsroutning i Program-filen genom att anropa MapControllers på IEndpointRouteBuilder (app):

    app.MapControllers();

Om du vill tillåta att en användare väljer en kultur för SSR-komponenter använder du en omdirigeringsbaserad metod med en lokalisering cookie. Appen bevarar användarens valda kultur via en omdirigering till en kontrollant. Kontrollanten anger användarens valda kultur till en cookie och omdirigerar användaren tillbaka till den ursprungliga URI:n. Processen liknar vad som händer i en webbapp när en användare försöker komma åt en säker resurs, där användaren omdirigeras till en inloggningssida och sedan omdirigeras tillbaka till den ursprungliga resursen.

Controllers/CultureController.cs:

using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;

[Route("[controller]/[action]")]
public class CultureController : Controller
{
    public IActionResult Set(string culture, string redirectUri)
    {
        if (culture != null)
        {
            HttpContext.Response.Cookies.Append(
                CookieRequestCultureProvider.DefaultCookieName,
                CookieRequestCultureProvider.MakeCookieValue(
                    new RequestCulture(culture, culture)));
        }

        return LocalRedirect(redirectUri);
    }
}

Varning

Använd LocalRedirect åtgärdsresultatet, som du ser i föregående exempel, för att förhindra öppna omdirigeringsattacker. Mer information finns i Förhindra öppna omdirigeringsattacker i ASP.NET Core.

Interaktiva automatiska komponenter

Vägledningen i det här avsnittet fungerar även för komponenter i appar som implementerar återgivning per sida/komponent och anger läget Interaktiv automatisk återgivning:

@rendermode InteractiveAuto

Lokalisering

Om appen inte redan stöder dynamiskt kulturval lägger du till Microsoft.Extensions.Localization-paketet i appen.

Notis

Mer information om hur du lägger till paket i .NET-appar finns i artiklarna under Installera och hantera paket på Arbetsflöde för paketförbrukning (NuGet-dokumentation). Bekräfta rätt paketversioner på NuGet.org.

Lokalisering på klientsidan

Ange egenskapen BlazorWebAssemblyLoadAllGlobalizationData till true i appens projektfil (.csproj):

<PropertyGroup>
  <BlazorWebAssemblyLoadAllGlobalizationData>true</BlazorWebAssemblyLoadAllGlobalizationData>
</PropertyGroup>

I filen Program, lägger du till namnområdet för System.Globalization till längst upp i filen.

using System.Globalization;

Lägg till Blazorlokaliseringstjänst i appens tjänstsamling med AddLocalization:

builder.Services.AddLocalization();

Lokalisering på serversidan

Använd Localization Middleware för att ange appens kultur.

Om appen inte redan stöder dynamiskt kulturval:

  • Lägg till lokaliseringstjänster i appen med AddLocalization.
  • Ange appens standardkulturer och kulturer som stöds i filen Program. I följande exempel konfigureras kulturer som stöds för engelska och costaricanska spanska i USA.
builder.Services.AddLocalization();

Placera Mellanprogram för lokalisering av begäran före mellanprogram som kan kontrollera begärandekulturen. Placera vanligtvis mellanprogrammet omedelbart innan du anropar MapRazorComponents:

Omedelbart efter att Routing Middleware (UseRouting) har lagts till i bearbetningspipeline:

var supportedCultures = new[] { "en-US", "es-CR" };
var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

Information om hur du beställer Mellanprogram för lokalisering i pipelinen för mellanprogram finns i ASP.NET Core Middleware.

  • Lägg till lokaliseringstjänster i appen med AddLocalization.
  • Ange appens standardkulturer och kulturer som stöds i Startup.Configure (Startup.cs). I följande exempel konfigureras kulturer som stöds för engelska och costaricanska spanska i USA.

I Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

I Startup.Configure, omedelbart efter att Routing Middleware (UseRouting) har lagts till i bearbetningspipelinen:

var supportedCultures = new[] { "en-US", "es-CR" };
var localizationOptions = new RequestLocalizationOptions()
    .SetDefaultCulture(supportedCultures[0])
    .AddSupportedCultures(supportedCultures)
    .AddSupportedUICultures(supportedCultures);

app.UseRequestLocalization(localizationOptions);

För information om att beställa Mellanprogram för lokalisering i mellanprogramspipelinen i Startup.Configure, se ASP.NET Core Middleware.

Om appen ska lokalisera resurser baserat på lagring av en användares kulturinställning använder du en lokaliseringskultur cookie. Användning av en cookie säkerställer att WebSocket-anslutningen kan sprida kulturen korrekt. Om lokaliseringsscheman baseras på URL-sökvägen eller frågesträngen kanske schemat inte kan fungera med WebSocketsoch därmed misslyckas med att bevara kulturen. Därför är den rekommenderade metoden att använda en lokaliseringskultur cookie. Se avsnittet där serverkulturen dynamiskt anges efter användarens inställningar i avsnittet för att se ett exempeluttryck Razor som bevarar användarens språkval.

Exempel på lokaliserade resurser

Exemplet med lokaliserade resurser i det här avsnittet fungerar med föregående exempel i den här artikeln där appens kulturer som stöds är engelska (en) som standardspråk och spanska (es) som ett användarvalbart eller webbläsardefinierat alternativspråk.

Skapa en resursfil för varje språk. I följande exempel skapas resurser för en Greeting sträng på engelska och spanska:

  • Engelska (en): Hello, World!
  • Spanska (es): ¡Hola, Mundo!

Notis

Följande resursfil kan läggas till i Visual Studio genom att högerklicka på mappen Pages och välja Lägg till>nytt objekt>resursfil. Ge filen namnet CultureExample2.resx. När redigeraren visas anger du data för en ny post. Ange Name till Greeting och Value till Hello, World!. Spara filen.

Om du använder Visual Studio Code rekommenderar vi att du installerar Tim Heuer's ResX Viewer och Editor. Lägg till en tom CultureExample2.resx fil i mappen Pages. Tillägget tar automatiskt över hanteringen av filen i användargränssnittet. Välj knappen Lägg till ny resurs. Följ anvisningarna för att lägga till en post för Greeting (nyckel), Hello, World! (värde) och None (kommentar). Spara filen. Om du stänger och öppnar filen igen kan du se Greeting resursen.

Tim Heuer's ResX Viewer och Editor inte ägs eller underhålls av Microsoft och omfattas inte av något Microsoft-supportavtal eller någon licens.

Följande visar en typisk resursfil. Du kan placera resursfiler manuellt i appens Pages mapp om du föredrar att inte använda inbyggda verktyg med en integrerad utvecklingsmiljö (IDE), till exempel Visual Studio inbyggda resursfilredigerare eller Visual Studio Code med ett tillägg för att skapa och redigera resursfiler.

Pages/CultureExample2.resx:

<?xml version="1.0" encoding="utf-8"?>
<root>
  <xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
    <xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
    <xsd:element name="root" msdata:IsDataSet="true">
      <xsd:complexType>
        <xsd:choice maxOccurs="unbounded">
          <xsd:element name="metadata">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" />
              </xsd:sequence>
              <xsd:attribute name="name" use="required" type="xsd:string" />
              <xsd:attribute name="type" type="xsd:string" />
              <xsd:attribute name="mimetype" type="xsd:string" />
              <xsd:attribute ref="xml:space" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="assembly">
            <xsd:complexType>
              <xsd:attribute name="alias" type="xsd:string" />
              <xsd:attribute name="name" type="xsd:string" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="data">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
                <xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
              </xsd:sequence>
              <xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
              <xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
              <xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
              <xsd:attribute ref="xml:space" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="resheader">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
              </xsd:sequence>
              <xsd:attribute name="name" type="xsd:string" use="required" />
            </xsd:complexType>
          </xsd:element>
        </xsd:choice>
      </xsd:complexType>
    </xsd:element>
  </xsd:schema>
  <resheader name="resmimetype">
    <value>text/microsoft-resx</value>
  </resheader>
  <resheader name="version">
    <value>2.0</value>
  </resheader>
  <resheader name="reader">
    <value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
  </resheader>
  <resheader name="writer">
    <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
  </resheader>
  <data name="Greeting" xml:space="preserve">
    <value>Hello, World!</value>
  </data>
</root>

Notis

Följande resursfil kan läggas till i Visual Studio genom att högerklicka på mappen Pages och välja Lägg till>nytt objekt>resursfil. Ge filen namnet CultureExample2.es.resx. När redigeraren visas anger du data för en ny post. Ange Name till Greeting och Value till ¡Hola, Mundo!. Spara filen.

Om du använder Visual Studio Code rekommenderar vi att du installerar Tim Heuer's ResX Viewer och Editor. Lägg till en tom CultureExample2.resx fil i mappen Pages. Tillägget tar automatiskt över hanteringen av filen i användargränssnittet. Välj knappen Lägg till ny resurs. Följ anvisningarna för att lägga till en post för Greeting (nyckel), ¡Hola, Mundo! (värde) och None (kommentar). Spara filen. Om du stänger och öppnar filen igen kan du se Greeting resursen.

Följande visar en typisk resursfil. Du kan placera resursfiler manuellt i appens Pages mapp om du föredrar att inte använda inbyggda verktyg med en integrerad utvecklingsmiljö (IDE), till exempel Visual Studio inbyggda resursfilredigerare eller Visual Studio Code med ett tillägg för att skapa och redigera resursfiler.

Pages/CultureExample2.es.resx:

<?xml version="1.0" encoding="utf-8"?>
<root>
  <xsd:schema id="root" xmlns="" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:msdata="urn:schemas-microsoft-com:xml-msdata">
    <xsd:import namespace="http://www.w3.org/XML/1998/namespace" />
    <xsd:element name="root" msdata:IsDataSet="true">
      <xsd:complexType>
        <xsd:choice maxOccurs="unbounded">
          <xsd:element name="metadata">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" />
              </xsd:sequence>
              <xsd:attribute name="name" use="required" type="xsd:string" />
              <xsd:attribute name="type" type="xsd:string" />
              <xsd:attribute name="mimetype" type="xsd:string" />
              <xsd:attribute ref="xml:space" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="assembly">
            <xsd:complexType>
              <xsd:attribute name="alias" type="xsd:string" />
              <xsd:attribute name="name" type="xsd:string" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="data">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
                <xsd:element name="comment" type="xsd:string" minOccurs="0" msdata:Ordinal="2" />
              </xsd:sequence>
              <xsd:attribute name="name" type="xsd:string" use="required" msdata:Ordinal="1" />
              <xsd:attribute name="type" type="xsd:string" msdata:Ordinal="3" />
              <xsd:attribute name="mimetype" type="xsd:string" msdata:Ordinal="4" />
              <xsd:attribute ref="xml:space" />
            </xsd:complexType>
          </xsd:element>
          <xsd:element name="resheader">
            <xsd:complexType>
              <xsd:sequence>
                <xsd:element name="value" type="xsd:string" minOccurs="0" msdata:Ordinal="1" />
              </xsd:sequence>
              <xsd:attribute name="name" type="xsd:string" use="required" />
            </xsd:complexType>
          </xsd:element>
        </xsd:choice>
      </xsd:complexType>
    </xsd:element>
  </xsd:schema>
  <resheader name="resmimetype">
    <value>text/microsoft-resx</value>
  </resheader>
  <resheader name="version">
    <value>2.0</value>
  </resheader>
  <resheader name="reader">
    <value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
  </resheader>
  <resheader name="writer">
    <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
  </resheader>
  <data name="Greeting" xml:space="preserve">
    <value>¡Hola, Mundo!</value>
  </data>
</root>

Följande komponent visar användningen av den lokaliserade Greeting strängen med IStringLocalizer<T>. Razor-markering @Loc["Greeting"] i följande exempel lokaliserar strängen som är nyckelad till värdet Greeting, som anges i föregående resursfiler.

Lägg till namnområdet för Microsoft.Extensions.Localization i appens _Imports.razor-fil:

@using Microsoft.Extensions.Localization

CultureExample2.razor:

@page "/culture-example-2"
@using System.Globalization
@inject IStringLocalizer<CultureExample2> Loc

<h1>Culture Example 2</h1>

<ul>
    <li><b>CurrentCulture</b>: @CultureInfo.CurrentCulture</li>
    <li><b>CurrentUICulture</b>: @CultureInfo.CurrentUICulture</li>
</ul>

<h2>Greeting</h2>

<p>
    @Loc["Greeting"]
</p>

<p>
    @greeting
</p>

@code {
    private string? greeting;

    protected override void OnInitialized()
    {
        greeting = Loc["Greeting"];
    }
}

Du kan också lägga till ett menyalternativ för komponenten CultureExample2 i navigeringen i komponenten NavMenu (NavMenu.razor).

Referenskälla för WebAssembly-kulturprovider

Mer information om hur Blazor framework bearbetar lokalisering finns i WebAssemblyCultureProvider-klassen i referenskällan ASP.NET Core.

Notis

Dokumentationslänkar till .NET-referenskällan läser vanligtvis in lagringsplatsens standardgren, vilket representerar den aktuella utvecklingen för nästa version av .NET. Om du vill välja en tagg för en specifik version använder du listrutan Växla grenar eller taggar. Mer information finns i Så här väljer du en versionstagg för ASP.NET Core-källkod (dotnet/AspNetCore.Docs #26205).

Delade resurser

Använd följande metod för att skapa delade lokaliseringsresurser.

  • Bekräfta att Microsoft.Extensions.Localization-paketet refereras av projektet.

    Notis

    Mer information om hur du lägger till paket i .NET-appar finns i artiklarna under Installera och hantera paket på Arbetsflöde för paketförbrukning (NuGet-dokumentation). Bekräfta rätt paketversioner på NuGet.org.

  • Bekräfta att Microsoft.Extensions.Localization namnområdet är tillgängligt för projektets Razor komponenter via en post i projektets _Imports-fil:

    @using Microsoft.Extensions.Localization

  • Skapa en dummy-klass med ett godtyckligt klassnamn. I följande exempel:

    • Appen använder BlazorSample namnrymd och lokaliseringsresurser använder BlazorSample.Localization namnrymd.
    • Dummy-klassen heter SharedResource.
    • Klassfilen placeras i en Localization mapp i appens rot.

    Notis

    Använd inte en autogenererad designerfil (till exempel SharedResources.Designer.cs). Dummy-klassen är avsedd att fungera som den delade resursklassen. Förekomsten av en designerfil resulterar i en namnområdeskollision.

    Localization/SharedResource.cs:

    namespace BlazorSample.Localization;

public class SharedResource
{
}

  • Skapa delade resursfiler med en byggåtgärd av Embedded resource. I följande exempel:

    • Filerna placeras i mappen Localization med dummy-klassen SharedResource (Localization/SharedResource.cs).

    • Namnge resursfilerna så att de matchar namnet på dummy-klassen. Följande exempelfiler innehåller en standardlokaliseringsfil och en fil för lokalisering av spanska (es).

    • Localization/SharedResource.resx

    • Localization/SharedResource.es.resx

    Varning

    När du följer metoden i det här avsnittet kan du inte samtidigt ange LocalizationOptions.ResourcesPath och använda IStringLocalizerFactory.Create för att läsa in resurser.

  • Om du vill referera till dummy-klassen för en inmatad IStringLocalizer<T> i en Razor komponent, placerar du antingen ett @using-direktiv för lokaliseringsnamnområdet eller inkluderar lokaliseringsnamnområdet i referensen för dummyklassen. I följande exempel:

    • I det första exemplet anges Localization namnrymd för SharedResource dummy-klassen med ett @using-direktiv.
    • I det andra exemplet anges SharedResource dummyklassens namnområde explicit.

    I en Razor komponent använder du antingen av följande metoder:

    @using Localization
@inject IStringLocalizer<SharedResource> Loc

    @inject IStringLocalizer<Localization.SharedResource> Loc

Mer information finns i Globalisering och lokalisering i ASP.NET Core.

Åsidosättning av plats med hjälp av panelen "Sensorer" i utvecklarverktyg

När du använder platsåterställningen med hjälp av fönstret Sensorer i Google Chrome eller Microsoft Edge-utvecklarverktyg återställs återställningsspråket efter föråtergivningen. Undvik att ange språket med hjälp av fönstret Sensorer när du testar. Ange språket med webbläsarens språkinställningar.

Mer information finns i Blazor Localization inte fungerar med InteractiveServer (dotnet/aspnetcore #53707).

Ytterligare resurser