Sdílet prostřednictvím

Blazor ASP.NET základní globalizace a lokalizace

  • Článek

Poznámka:

Toto není nejnovější verze tohoto článku. Aktuální verzi najdete v tomto článku ve verzi .NET 9.

Upozorňující

Tato verze ASP.NET Core se už nepodporuje. Další informace najdete v tématu .NET a .NET Core Zásady podpory. Aktuální verzi najdete ve verzi .NET 8 tohoto článku.

Důležité

Tyto informace se týkají předběžného vydání produktu, který může být podstatně změněn před komerčním vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Aktuální verzi najdete v tomto článku ve verzi .NET 9.

Tento článek vysvětluje, jak vykreslit globalizovaný a lokalizovaný obsah uživatelům v různých jazykových verzích a jazycích.

Globalizace a lokalizace

Pro globalizaciBlazor poskytuje formátování čísel a kalendářních dat. Pro lokalizaciBlazor vykreslí obsah pomocí systému prostředků .NET.

Podporuje se omezená sada lokalizačních funkcí ASP.NET Core:

IStringLocalizer a IStringLocalizer<T> jsou podporovány v Blazor aplikacích.

IHtmlLocalizerIViewLocalizer, a lokalizace datových poznámek jsou ASP.NET základní funkce MVC a nejsou podporovány v Blazor aplikacích.

Tento článek popisuje, jak používat Blazorfunkce globalizace a lokalizace na základě:

  • HlavičkaAccept-Language, která je nastavena prohlížečem na základě jazykových předvoleb uživatele v nastavení prohlížeče.
  • Jazyková verze nastavená aplikací, která není založena na hodnotě hlavičkyAccept-Language. Nastavení může být statické pro všechny uživatele nebo dynamické na základě logiky aplikace. Když je nastavení založené na předvolbě uživatele, nastavení se obvykle uloží pro opětovné načtení při budoucích návštěvách.

Další obecné informace najdete v následujících zdrojích informací:

Termíny jazyk a kultura se často používají zaměnitelně při práci s koncepty globalizace a lokalizace.

V tomto článku jazyk odkazuje na výběry provedené uživatelem v nastavení prohlížeče. Výběry jazyka uživatele se odesílají v požadavcích prohlížeče v Accept-Language hlavičce. Nastavení prohlížeče obvykle používá slovo "jazyk" v uživatelském rozhraní.

Jazyková verze se týká členů rozhraní .NET a Blazor API. Požadavek uživatele může například obsahovat hlavičku Accept-Language určující jazyk z pohledu uživatele, ale aplikace nakonec nastaví CurrentCulture vlastnost ("culture") z jazyka, který uživatel požadoval. Rozhraní API obvykle používá ve svých názvech členů slovo "culture".

Pokyny v tomto článku se nezabývá nastavením atributu jazyka HTML stránky(<html lang="...">), který používají nástroje pro přístup. Hodnotu můžete nastavit staticky přiřazením jazyka k lang atributu <html> značky nebo javascriptu document.documentElement.lang . Můžete dynamicky nastavit hodnotu document.documentElement.lang s interoperabilitouJS.

Poznámka:

Příklady kódu v tomto článku přijímají referenční typy s možnou hodnotou null (NRT) a statickou analýzu stavu null-stav kompilátoru .NET, které jsou podporovány v ASP.NET Core v .NET 6 nebo novější. Při cílení na ASP.NET Core 5.0 nebo starší odeberte označení typu null (?) z příkladů článku.

Globalizace

Direktiva @bind atributu používá formáty a analyzuje hodnoty pro zobrazení na základě preferovaného jazyka uživatele, který aplikace podporuje. @bind podporuje parametr pro @bind:culture analýzu System.Globalization.CultureInfo a formátování hodnoty.

K aktuální jazykové verzi lze získat přístup z System.Globalization.CultureInfo.CurrentCulture vlastnosti.

CultureInfo.InvariantCulture se používá pro následující typy polí (<input type="{TYPE}" />kde {TYPE} zástupný symbol je typ):

  • date
  • number

Předchozí typy polí:

  • Zobrazují se pomocí příslušných pravidel formátování na základě prohlížeče.
  • Nelze obsahovat volný text.
  • Zadejte charakteristiky interakce uživatelů na základě implementace prohlížeče.

Blazor poskytuje integrovanou podporu vykreslování hodnot v aktuální jazykové verzi. Proto se při použití date typů polí number nedoporučuje zadat jazykovou verzi @bind:culture s jazykovou verzí.

Následující typy polí mají specifické požadavky na formátování a nejsou podporovány všemi hlavními prohlížeči, takže je nepodporují Blazor:

  • datetime-local
  • month
  • week

Aktuální podporu předchozích typů v prohlížeči najdete v tématu Můžu použít.

PodporaBlazor WebAssembly globalizace a mezinárodních komponent .NET pro kódování Unicode (ICU)

Blazor WebAssembly používá omezené rozhraní API globalizace a sadu integrovaných mezinárodních komponent pro národní prostředí Unicode (ICU). Další informace naleznete v tématu Globalizace a ICU .NET: ICU na WebAssembly.

Pokud chcete načíst vlastní datový soubor ICU pro řízení národních prostředí aplikace, přečtěte si téma WASM Globalization Icu. V současné době se vyžaduje ruční sestavení vlastního datového souboru ICU. Nástroje .NET pro usnadnění procesu vytváření souboru se plánují pro .NET 10 v listopadu 2025.

Blazor WebAssembly používá omezené rozhraní API globalizace a sadu integrovaných mezinárodních komponent pro národní prostředí Unicode (ICU). Další informace naleznete v tématu Globalizace a ICU .NET: ICU na WebAssembly.

Načtení vlastní podmnožině národních prostředí v aplikaci je podporováno v Blazor WebAssembly .NET 8 nebo novějším. Další informace najdete v této části pro verzi 8.0 nebo novější tohoto článku.

Invariantní globalizace

Tato část se vztahuje pouze na scénáře na straně Blazor klienta.

Pokud aplikace nevyžaduje lokalizaci, nakonfigurujte aplikaci tak, aby podporovala invariantní jazykovou verzi, která je obecně založená na USA angličtině (en-US). Použití invariantní globalizace snižuje velikost stahování aplikace a vede k rychlejšímu spuštění aplikace. InvariantGlobalization Nastavte vlastnost v true souboru projektu aplikace (.csproj):

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

Případně nakonfigurujte invariantní globalizaci pomocí následujících přístupů:

  • V runtimeconfig.json:

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

  • S proměnnou prostředí:

    • Klíč: DOTNET_SYSTEM_GLOBALIZATION_INVARIANT
    • Hodnota: true nebo 1

Další informace najdete v tématu Možnosti konfigurace modulu runtime pro globalizaci (dokumentace k .NET).

Informace o časovém pásmu

Tato část se vztahuje pouze na scénáře na straně Blazor klienta.

Přijetí invariantní globalizace vede pouze k použití nelokalizačních názvů časových pásem. Pokud chcete zkrátit kód a data časového pásma, což snižuje velikost stahování aplikace a vede k rychlejšímu spuštění aplikace, použijte <InvariantTimezone> vlastnost MSBuild s hodnotou true v souboru projektu aplikace:

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

Poznámka:

<BlazorEnableTimeZoneSupport> přepíše dřívější <InvariantTimezone> nastavení. Doporučujeme odebrat <BlazorEnableTimeZoneSupport> nastavení.

Součástí datového souboru je oprava informací o časovém pásmu. Pokud aplikace tuto funkci nevyžaduje, zvažte její zakázání nastavením <BlazorEnableTimeZoneSupport> vlastnosti MSBuild do false souboru projektu aplikace:

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

Ukázková komponenta

CultureExample1 Následující komponentu lze použít k předvedení Blazor konceptů globalizace a lokalizace, na které se vztahuje tento článek.

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;
}

Formát číselného řetězce () v předchozím příkladu (N2.ToString("N2")) je standardní specifikátor číselného formátu .NET. Formát N2 je podporovaný pro všechny číselné typy, obsahuje oddělovač skupin a vykreslí se až dvě desetinná místa.

Volitelně můžete do navigace v NavMenu komponentě () komponenty CultureExample1 přidatNavMenu.razor položku nabídky.

Dynamicky nastavte jazykovou verzi ze Accept-Language záhlaví.

Přidejte balíček Microsoft.Extensions.Localization do aplikace.

Záhlaví Accept-Language nastaví prohlížeč a řídí se jazykovými předvolbou uživatele v nastavení prohlížeče. V nastavení prohlížeče uživatel nastaví jeden nebo více upřednostňovaných jazyků v pořadí podle preference. Pořadí předvoleb používá prohlížeč k nastavení hodnot kvality (q0–1) pro každý jazyk v záhlaví. Následující příklad určuje USA angličtinu, angličtinu a kostarický španělština s předvolbou pro USA angličtinu nebo angličtinu:

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

Jazyková verze aplikace je nastavená tak, že odpovídá prvnímu požadovanému jazyku, který odpovídá podporované jazykové verzi aplikace.

Při vývoji na straně klienta nastavte BlazorWebAssemblyLoadAllGlobalizationData vlastnost na true soubor projektu aplikace na straně klienta (.csproj):

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

Při vývoji na straně klienta není dynamické nastavení jazykové verze z hlavičky Accept-Language podporované.

Poznámka:

Pokud specifikace aplikace vyžaduje omezení podporovaných jazykových verzí na explicitní seznam, přečtěte si část Dynamické nastavení jazykové verze na straně klienta podle předvolby uživatele tohoto článku.

Aplikace se lokalizují pomocí middlewaru lokalizace. Přidejte do aplikace lokalizační služby pomocí AddLocalization.

Do souboru, Program ve kterém jsou zaregistrované služby, přidejte následující řádek:

builder.Services.AddLocalization();

Ve vývoji na straně serveru určete podporované jazykové verze aplikace před jakýmkoli middlewarem, který by mohl zkontrolovat jazykovou verzi požadavku. Obecně platí, že před voláním umístěte middleware lokalizace požadavku bezprostředně před voláním MapRazorComponents. Následující příklad konfiguruje podporované jazykové verze pro USA angličtinu a kostarický španělština:

Při vývoji na straně serveru zadejte podporované jazykové verze aplikace hned po přidání middlewaruUseRouting směrování do kanálu zpracování. Následující příklad konfiguruje podporované jazykové verze pro USA angličtinu a kostarický španělština:

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

Informace o řazení middlewaru lokalizace v kanálu middlewaru Program souboru najdete v tématu ASP.NET Core Middleware.

Použijte komponentu CultureExample1 zobrazenou v části Ukázková komponenta ke studiu toho, jak globalizace funguje. Vyžádejte žádost s USA angličtinou (en-US). V nastavení jazyka prohlížeče přepněte do španělštiny kostarikánské španělštiny (es-CR). Znovu požádejte o webovou stránku.

Poznámka:

Některé prohlížeče vynutí použití výchozího jazykového nastavení pro požadavky i vlastní nastavení uživatelského rozhraní prohlížeče. Změna jazyka může být obtížná, protože všechny obrazovky uživatelského rozhraní pro nastavení můžou skončit v jazyce, který se nedá přečíst. Prohlížeč, jako je Opera , je dobrou volbou pro testování, protože umožňuje nastavit výchozí jazyk pro požadavky na webové stránky, ale ponechat uživatelské rozhraní nastavení prohlížeče ve vašem jazyce.

Pokud je jazyková verze USA angličtina (en-US), vykreslovaná komponenta používá formátování data měsíce/dne (6/7), 12hodinový čas (AM/PM) a oddělovače čárk v číslech s tečkou pro desetinnou hodnotu (1,999.69):

  • Datum: 7.6.2021 6:45:22
  • Číslo: 1 999,69

Pokud je jazyková verze costakánská španělština (es-CR), vykreslená komponenta používá formátování data dne/měsíce (7/6), 24hodinový čas a oddělovače období v číslech s čárkou pro desetinnou hodnotu (1.999,69):

  • Datum: 6.7.2021 6:49:38
  • Číslo: 1,999,69

Staticky nastavte jazykovou verzi na straně klienta.

BlazorWebAssemblyLoadAllGlobalizationData Nastavte vlastnost v true souboru projektu aplikace (.csproj):

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

Konfigurace linkeru Intermediate Language (IL) pro vykreslování na straně klienta odstraní informace o internacionalizaci s výjimkou národních prostředí explicitně požadovaných národních prostředí. Další informace najdete v tématu Konfigurace linkeru pro ASP.NET Core Blazor.

Jazyková verze aplikace se dá nastavit v JavaScriptu, když Blazor začíná možnost startu applicationCultureBlazor . Následující příklad nakonfiguruje spuštění aplikace pomocí jazykové verze USA angličtiny (en-US).

Zabránit Blazor automatickému startu přidáním autostart="false" značky <script> Blazor:

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

V předchozím příkladu {BLAZOR SCRIPT} je Blazor zástupný symbol cesta ke skriptu a název souboru. Umístění skriptu najdete v tématu ASP.NET Blazor Základní struktura projektu.

Za značku a před koncovou </body> značku přidejte následující <script> blok<script>Blazor:

Blazor Web App:

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

Samostatné Blazor WebAssembly:

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

Hodnota applicationCulture musí odpovídat formátu značky jazyka BCP-47. Další informace o spuštění architektury Blazor najdete v tématu Spuštění ASP.NET Core Blazor.

Alternativou k nastavení počáteční možnosti jazykové verze Blazorje nastavení jazykové verze v kódu jazyka C#. Nastavte CultureInfo.DefaultThreadCurrentCulture a CultureInfo.DefaultThreadCurrentUICulture v Program souboru na stejnou jazykovou verzi.

Přidejte obor System.Globalization názvů do Program souboru:

using System.Globalization;

Přidejte nastavení jazykové verze před řádek, který sestaví a spustí WebAssemblyHostBuilder (await builder.Build().RunAsync();):

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

Poznámka:

Blazor WebAssembly V současné době aplikace načítají pouze prostředky na DefaultThreadCurrentCulturezákladě . Další informace naleznete pouze v tématu Blazor WASM spoléhá na aktuální jazykovou verzi (aktuální jazyková verze uživatelského rozhraní není respektována) (dotnet/aspnetcore #56824).

Použijte komponentu CultureExample1 zobrazenou v části Ukázková komponenta ke studiu toho, jak globalizace funguje. Vyžádejte žádost s USA angličtinou (en-US). V nastavení jazyka prohlížeče přepněte do španělštiny kostarikánské španělštiny (es-CR). Znovu požádejte o webovou stránku. Pokud je požadovaným jazykem kostarská španělština, jazyková verze aplikace zůstane USA angličtina (en-US).

Staticky nastavte jazykovou verzi na straně serveru.

Serverové aplikace se lokalizují pomocí middlewaru lokalizace. Přidejte do aplikace lokalizační služby pomocí AddLocalization.

V souboru Program:

builder.Services.AddLocalization();

Před jakýmkoli middlewarem, který může zkontrolovat jazykovou verzi požadavku, zadejte statickou jazykovou verzi souboru Program . Obecně, umístěte lokalizační middleware žádosti bezprostředně před MapRazorComponents. Následující příklad konfiguruje USA angličtinu:

Zadejte statickou jazykovou verzi souboru Program hned po přidání middlewaru směrování (UseRouting) do kanálu zpracování. Následující příklad konfiguruje USA angličtinu:

app.UseRequestLocalization("en-US");

Hodnota UseRequestLocalization jazykové verze musí odpovídat formátu značky jazyka BCP-47.

Informace o řazení middlewaru lokalizace v kanálu middlewaru Program souboru najdete v tématu ASP.NET Core Middleware.

Serverové aplikace se lokalizují pomocí middlewaru lokalizace. Přidejte do aplikace lokalizační služby pomocí AddLocalization.

V Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

Zadejte statickou jazykovou verzi v Startup.Configure (Startup.cs) ihned po přidání middlewaru směrování do kanálu zpracování. Následující příklad konfiguruje USA angličtinu:

app.UseRequestLocalization("en-US");

Hodnota UseRequestLocalization jazykové verze musí odpovídat formátu značky jazyka BCP-47.

Informace o objednání middlewaru lokalizace v kanálu middlewaru Startup.Configurenaleznete v tématu ASP.NET Core Middleware.

Použijte komponentu CultureExample1 zobrazenou v části Ukázková komponenta ke studiu toho, jak globalizace funguje. Vyžádejte žádost s USA angličtinou (en-US). V nastavení jazyka prohlížeče přepněte do španělštiny kostarikánské španělštiny (es-CR). Znovu požádejte o webovou stránku. Pokud je požadovaným jazykem kostarská španělština, jazyková verze aplikace zůstane USA angličtina (en-US).

Dynamické nastavení jazykové verze na straně klienta podle předvoleb uživatele

Příklady umístění, kde může aplikace ukládat předvolby uživatele, patří do místního úložiště prohlížeče (běžné pro scénáře na straně klienta), v lokalizaci cookie nebo databázi (běžné pro scénáře na straně serveru) nebo v externí službě připojené k externí databázi a přístup k webovému rozhraní API. Následující příklad ukazuje, jak používat místní úložiště prohlížeče.

Přidejte balíček Microsoft.Extensions.Localization do aplikace.

Poznámka:

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

BlazorWebAssemblyLoadAllGlobalizationData Nastavte vlastnost v true souboru projektu:

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

Jazyková verze aplikace pro vykreslování na straně klienta je nastavená pomocí Blazor rozhraní API architektury. Výběr jazykové verze uživatele lze zachovat v místním úložišti prohlížeče.

Poskytněte JS funkce po <script> Blazorznačce, abyste získali a nastavili výběr jazykové verze uživatele s místním úložištěm prohlížeče:

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

Poznámka:

Předchozí příklad znečišťuje klienta globálními funkcemi. Lepší přístup v produkčních aplikacích najdete v tématu Izolace JavaScriptu v modulech JavaScriptu.

Přidejte obory názvů pro System.Globalization a Microsoft.JSInterop do horní části Program souboru:

using System.Globalization;
using Microsoft.JSInterop;

Odeberte následující řádek:

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

Nahraďte předchozí řádek následujícím kódem. Kód přidá Blazorlokalizační službu do kolekce služeb aplikace a AddLocalization použije JS interop k volání JS a načtení výběru jazykové verze uživatele z místního úložiště. Pokud místní úložiště neobsahuje jazykovou verzi pro uživatele, nastaví kód výchozí hodnotu USA angličtinu (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();

Poznámka:

Blazor WebAssembly V současné době aplikace načítají pouze prostředky na DefaultThreadCurrentCulturezákladě . Další informace naleznete pouze v tématu Blazor WASM spoléhá na aktuální jazykovou verzi (aktuální jazyková verze uživatelského rozhraní není respektována) (dotnet/aspnetcore #56824).

Následující CultureSelector komponenta ukazuje, jak provádět následující akce:

  • Nastavte výběr jazykové verze uživatele do místního úložiště prohlížeče prostřednictvím JS zprostředkovatele komunikace.
  • Znovu načtěte komponentu, kterou požadoval (forceLoad: true), která používá aktualizovanou jazykovou verzi.

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);
        }
    }
}

Poznámka:

Další informace o IJSInProcessRuntimevolání javascriptových funkcí z metod .NET v ASP.NET Core Blazor.

Uvnitř uzavírací značky </main> prvku v komponentě MainLayout (MainLayout.razor) přidejte komponentu CultureSelector :

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

CultureExample1 Pomocí komponenty zobrazené v části Ukázková komponenta se seznámíte s tím, jak funguje předchozí příklad.

Dynamické nastavení jazykové verze na straně serveru podle předvoleb uživatele

Příklady umístění, kde může aplikace ukládat předvolby uživatele, patří do místního úložiště prohlížeče (běžné pro scénáře na straně klienta), v lokalizaci cookie nebo databázi (běžné pro scénáře na straně serveru) nebo v externí službě připojené k externí databázi a přístup k webovému rozhraní API. Následující příklad ukazuje, jak použít lokalizaci cookie.

Poznámka:

Následující příklad předpokládá, že aplikace přijímá globální interaktivitu zadáním interaktivního vykreslování na straně serveru (interaktivní SSR) komponenty Routes v App komponentě (Components/App.razor):

<Routes @rendermode="InteractiveServer" />

Pokud aplikace přijme interaktivitu jednotlivých stránek nebo součástí , podívejte se na poznámky na konci této části a upravte režimy vykreslování komponent příkladu.

Přidejte balíček Microsoft.Extensions.Localization do aplikace.

Poznámka:

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

Serverové aplikace se lokalizují pomocí middlewaru lokalizace. Přidejte do aplikace lokalizační služby pomocí AddLocalization.

V souboru Program:

builder.Services.AddLocalization();

Nastavte výchozí a podporovanou jazykovou verzi aplikace pomocí RequestLocalizationOptions.

Před voláním MapRazorComponents v kanálu zpracování požadavků umístěte následující kód:

Po přidání middlewaruUseRouting směrování do kanálu zpracování požadavků umístěte následující kód:

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

app.UseRequestLocalization(localizationOptions);

Informace o řazení middlewaru lokalizace v kanálu middlewaru najdete v tématu ASP.NET Core Middleware.

Následující příklad ukazuje, jak nastavit aktuální jazykovou verzi v objektu cookie , který lze přečíst middleware lokalizace.

Pro komponentu App jsou vyžadovány následující obory názvů:

Do horní části App souboru komponenty (Components/App.razor):

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

Do dolní části App souboru komponenty přidejte následující @code blok:

@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)));
    }
}

Pages/_Host.cshtml Úpravy souboru vyžadují následující obory názvů:

Přidejte do souboru následující kód:

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

Informace o řazení middlewaru lokalizace v kanálu middlewaru najdete v tématu ASP.NET Core Middleware.

Pokud aplikace není nakonfigurovaná tak, aby zpracovávala akce kontroleru:

  • Přidejte služby MVC voláním AddControllers kolekce služby v Program souboru:

    builder.Services.AddControllers();

  • Přidejte do Program souboru směrování koncového bodu kontroleru voláním MapControllers (appIEndpointRouteBuilder):

    app.MapControllers();

Pokud chcete poskytnout uživatelské rozhraní, které uživateli umožní vybrat jazykovou verzi, použijte přístup založený na přesměrování s lokalizací cookie. Aplikace zachová vybranou jazykovou verzi uživatele prostřednictvím přesměrování na kontroler. Kontroler nastaví vybranou cookie jazykovou verzi uživatele na a přesměruje ho zpět na původní identifikátor URI. Postup je podobný tomu, co se stane ve webové aplikaci, když se uživatel pokusí o přístup k zabezpečenému prostředku, kde se uživatel přesměruje na přihlašovací stránku a pak se přesměruje zpět na původní prostředek.

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);
    }
}

Upozorňující

LocalRedirect Použijte výsledek akce, jak je znázorněno v předchozím příkladu, abyste zabránili útokům s otevřeným přesměrováním. Další informace najdete v tématu Prevence útoků s otevřeným přesměrováním v ASP.NET Core.

Následující CultureSelector komponenta ukazuje, jak volat Set metodu CultureController s novou jazykovou verzí. Komponenta se umístí do Shared složky pro použití v celé aplikaci.

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);
        }
    }
}

Přidejte komponentu CultureSelector MainLayout do komponenty. Do zavírací </main> značky v Components/Layout/MainLayout.razor souboru umístěte následující kód:

Přidejte komponentu CultureSelector MainLayout do komponenty. Do zavírací </main> značky v Shared/MainLayout.razor souboru umístěte následující kód:

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

CultureExample1 Pomocí komponenty zobrazené v části Ukázková komponenta se seznámíte s tím, jak funguje předchozí příklad.

Předchozí příklad předpokládá, že aplikace přijímá globální interaktivitu zadáním režimu vykreslování Interactive Server na Routes komponentě App v komponentě (Components/App.razor):

<Routes @rendermode="InteractiveServer" />

Pokud aplikace přijme interaktivitu jednotlivých stránek nebo součástí , proveďte následující změny:

  • Do horní části CultureExample1 souboru komponenty přidejte režim vykreslování Interaktivní server (Components/Pages/CultureExample1.razor):

    @rendermode InteractiveServer

  • V hlavním rozložení aplikace (Components/Layout/MainLayout.razor), použijte režim vykreslování Interactive Server na komponentu CultureSelector :

    <CultureSelector @rendermode="InteractiveServer" />

Dynamické nastavení jazykové verze v předvolbách Blazor Web App uživatele

Tato část se vztahuje na Blazor Web Appinteraktivitu automatického přechodu (Server a WebAssembly).

Příklady umístění, kde může aplikace ukládat předvolby uživatele, patří do místního úložiště prohlížeče (běžné pro scénáře na straně klienta) v lokalizaci cookie nebo databázi (běžné pro scénáře na straně serveru), místní úložiště i lokalizaci cookie (Blazor Web Apps komponentami server a WebAssembly) nebo v externí službě připojené k externí databázi a přístup k webovému rozhraní API. Následující příklad ukazuje, jak používat místní úložiště prohlížeče pro vykreslované komponenty na straně klienta (CSR) a lokalizaci cookie pro vykreslované součásti na straně serveru (SSR).

.Client Aktualizace projektu

Přidejte balíček Microsoft.Extensions.Localization do .Client projektu.

Poznámka:

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

BlazorWebAssemblyLoadAllGlobalizationData Nastavte vlastnost v true .Client souboru projektu:

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

Přidejte obory názvů pro System.Globalization a Microsoft.JSInterop do horní části .Client souboru projektu Program :

using System.Globalization;
using Microsoft.JSInterop;

Odeberte následující řádek:

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

Nahraďte předchozí řádek následujícím kódem. Kód přidá Blazorlokalizační službu do kolekce služeb aplikace a AddLocalization použije JS interop k volání JS a načtení výběru jazykové verze uživatele z místního úložiště. Pokud místní úložiště neobsahuje jazykovou verzi pro uživatele, nastaví kód výchozí hodnotu USA angličtinu (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();

Poznámka:

Blazor WebAssembly V současné době aplikace načítají pouze prostředky na DefaultThreadCurrentCulturezákladě . Další informace naleznete pouze v tématu Blazor WASM spoléhá na aktuální jazykovou verzi (aktuální jazyková verze uživatelského rozhraní není respektována) (dotnet/aspnetcore #56824).

Přidejte do projektu následující CultureSelector komponentu .Client .

Tato komponenta přijímá následující přístupy k práci pro komponenty SSR nebo CSR:

  • Zobrazovaný název každé dostupné jazykové verze v rozevíracím seznamu poskytuje slovník, protože data globalizace na straně klienta obsahují lokalizovaný text zobrazovaných názvů jazykových verzí, které poskytují data globalizace na straně serveru. Například lokalizace na straně serveru se zobrazí English (United States) , kdy en-US se používá jazyková verze a Ingles () kdy se používá jiná jazyková verze. Vzhledem k tomu, že lokalizace zobrazovaných názvů jazykové verze není k dispozici s Blazor WebAssembly globalizací, zobrazovaný název pro USA angličtinu na klientovi pro jakoukoli načtenou jazykovou verzi je pouze en-US. Použití vlastního slovníku umožňuje komponentě alespoň zobrazit úplné názvy anglické jazykové verze.
  • Když uživatel změní jazykovou verzi, JS interop nastaví jazykovou verzi v místním úložišti prohlížeče a akce kontroleru aktualizuje lokalizaci cookie pomocí jazykové verze. Kontroler se přidá do aplikace později v části Aktualizace projektu serveru.

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);
        }
    }
}

Poznámka:

Další informace o IJSInProcessRuntimevolání javascriptových funkcí z metod .NET v ASP.NET Core Blazor.

.Client V projektu umístěte následující CultureClient komponentu, abyste prozkoumali, jak globalizace funguje pro komponenty CSR.

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;
}

Aktualizace projektu serveru

Microsoft.Extensions.Localization Přidejte balíček do projektu serveru.

Poznámka:

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

Serverové aplikace se lokalizují pomocí middlewaru lokalizace. Přidejte do aplikace lokalizační služby pomocí AddLocalization.

V souboru projektu Program serveru, kde jsou zaregistrované služby:

builder.Services.AddLocalization();

Nastavte výchozí a podporovanou jazykovou verzi aplikace pomocí RequestLocalizationOptions.

Před voláním MapRazorComponents v kanálu zpracování požadavků umístěte následující kód:

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

app.UseRequestLocalization(localizationOptions);

Následující příklad ukazuje, jak nastavit aktuální jazykovou verzi v objektu cookie , který lze přečíst middleware lokalizace.

Pro komponentu App jsou vyžadovány následující obory názvů:

Do horní části App souboru komponenty (Components/App.razor):

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

Jazyková verze aplikace pro vykreslování na straně klienta je nastavená pomocí Blazor rozhraní API architektury. Výběr jazykové verze uživatele lze zachovat v místním úložišti prohlížeče pro komponenty CSR.

<script>BlazorPo značce zadejte JS funkce pro získání a nastavení výběru jazykové verze uživatele pomocí místního úložiště prohlížeče:

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

Poznámka:

Předchozí příklad znečišťuje klienta globálními funkcemi. Lepší přístup v produkčních aplikacích najdete v tématu Izolace JavaScriptu v modulech JavaScriptu.

Do dolní části App souboru komponenty přidejte následující @code blok:

@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)));
    }
}

Pokud serverový projekt není nakonfigurovaný tak, aby zpracovával akce kontroleru:

  • Přidejte služby MVC voláním AddControllers kolekce služby v Program souboru:

    builder.Services.AddControllers();

  • Přidejte do Program souboru směrování koncového bodu kontroleru voláním MapControllers (appIEndpointRouteBuilder):

    app.MapControllers();

Pokud chcete uživateli povolit výběr jazykové verze pro komponenty SSR, použijte přístup založený na přesměrování s lokalizací cookie. Aplikace zachová vybranou jazykovou verzi uživatele prostřednictvím přesměrování na kontroler. Kontroler nastaví vybranou cookie jazykovou verzi uživatele na a přesměruje ho zpět na původní identifikátor URI. Postup je podobný tomu, co se stane ve webové aplikaci, když se uživatel pokusí o přístup k zabezpečenému prostředku, kde se uživatel přesměruje na přihlašovací stránku a pak se přesměruje zpět na původní prostředek.

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);
    }
}

Upozorňující

LocalRedirect Použijte výsledek akce, jak je znázorněno v předchozím příkladu, abyste zabránili útokům s otevřeným přesměrováním. Další informace najdete v tématu Prevence útoků s otevřeným přesměrováním v ASP.NET Core.

Přidejte komponentu CultureSelector MainLayout do komponenty. Do zavírací </main> značky v Components/Layout/MainLayout.razor souboru umístěte následující kód:

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

CultureExample1 Pomocí komponenty zobrazené v části Ukázková komponenta se seznámíte s tím, jak funguje předchozí příklad.

V serverovém projektu umístěte následující CultureServer komponentu, abyste prozkoumali, jak globalizace funguje pro komponenty SSR.

Components/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;
}

Přidání obou součástí CultureServer do navigačního CultureClient panelu na bočním panelu vComponents/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>

Interaktivní automatické komponenty

Pokyny v této části také fungují pro komponenty, které přecházejí do režimu interaktivního automatického vykreslování:

@rendermode InteractiveAuto

Lokalizace

Pokud aplikace ještě nepodporuje dynamický výběr jazykové verze, přidejte balíček Microsoft.Extensions.Localization do aplikace.

Poznámka:

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

Lokalizace na straně klienta

BlazorWebAssemblyLoadAllGlobalizationData Nastavte vlastnost v true souboru projektu aplikace (.csproj):

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

Program Do souboru přidejte obor názvů pro System.Globalization začátek souboru:

using System.Globalization;

Přidejte Blazorlokalizační službu do kolekce služeb aplikace pomocí AddLocalization:

builder.Services.AddLocalization();

Lokalizace na straně serveru

K nastavení jazykové verze aplikace použijte middleware lokalizace.

Pokud aplikace ještě nepodporuje dynamický výběr jazykové verze:

  • Přidejte do aplikace lokalizační služby pomocí AddLocalization.
  • Zadejte výchozí a podporované jazykové verze aplikace v Program souboru. Následující příklad konfiguruje podporované jazykové verze pro USA angličtinu a kostarický španělština.
builder.Services.AddLocalization();

Před jakýmkoli middlewarem, který může zkontrolovat jazykovou verzi požadavku, umístěte middleware lokalizace požadavků. Obecně platí, že middleware umístěte bezprostředně před voláním MapRazorComponents:

Ihned po přidání middlewaruUseRouting směrování do kanálu zpracování:

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

app.UseRequestLocalization(localizationOptions);

Informace o řazení middlewaru lokalizace v kanálu middlewaru najdete v tématu ASP.NET Core Middleware.

  • Přidejte do aplikace lokalizační služby pomocí AddLocalization.
  • Zadejte výchozí a podporovanou jazykovou verzi aplikace v Startup.Configure (Startup.cs). Následující příklad konfiguruje podporované jazykové verze pro USA angličtinu a kostarický španělština.

V Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

Okamžitě Startup.Configure po přidání middlewaruUseRouting směrování do kanálu zpracování:

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

app.UseRequestLocalization(localizationOptions);

Informace o objednání middlewaru lokalizace v kanálu middlewaru Startup.Configurenaleznete v tématu ASP.NET Core Middleware.

Pokud by aplikace měla lokalizovat prostředky na základě ukládání nastavení jazykové verze uživatele, použijte lokalizační jazykovou verzi cookie. cookie Použití zajištění, že připojení WebSocket může správně rozšířit jazykovou verzi. Pokud jsou schémata lokalizace založená na cestě URL nebo řetězci dotazu, schéma nemusí být schopné pracovat s webSockety, a proto se nepodaří zachovat jazykovou verzi. Proto se doporučuje použít lokalizační jazykovou verzi cookie. Pokud chcete zobrazit příklad Razor výrazu, který zachovává výběr jazykové verze uživatele, podívejte se na část Dynamické nastavení jazykové verze serveru v tomto článku.

Příklad lokalizovaných prostředků

Příklad lokalizovaných prostředků v této části funguje s předchozími příklady v tomto článku, kde podporované jazykové verze aplikace jsou angličtina (en) jako výchozí národní prostředí a španělština (es) jako alternativní národní prostředí určené uživatelem nebo prohlížeči.

Vytvořte soubor prostředků pro každé národní prostředí. V následujícím příkladu jsou prostředky vytvořeny pro Greeting řetězec v angličtině a španělštině:

  • Angličtina (en): Hello, World!
  • Španělština (es): ¡Hola, Mundo!

Poznámka:

Následující soubor prostředků lze přidat v sadě Visual Studio tak, že kliknete pravým tlačítkem na Pages složku a vyberete Přidat>soubor prostředků nové položky.> Pojmenujte soubor CultureExample2.resx. Jakmile se zobrazí editor, zadejte data pro novou položku. Nastavte název na Greeting hodnotu a hodnotu na Hello, World!hodnotu . Uložte soubor.

Pokud používáte Visual Studio Code, doporučujeme nainstalovat Prohlížeč ResX a Editor Tima Heuera. Přidejte do Pages složky prázdný CultureExample2.resx soubor. Rozšíření automaticky převezme správu souboru v uživatelském rozhraní. Vyberte tlačítko Přidat nový prostředek. Podle pokynů přidejte položku ( Greeting klíč), Hello, World! (hodnota) a None (komentář). Uložte soubor. Pokud soubor zavřete a znovu otevřete, zobrazí se Greeting prostředek.

Tim Heuer's ResX Viewer a Editor nejsou vlastněné ani udržovány Společností Microsoft a nejsou pokryty žádnou smlouvou nebo licencí podpora Microsoftu.

Následující příklad ukazuje typický soubor prostředků. Soubory prostředků můžete ručně umístit do složky aplikace Pages , pokud nechcete používat integrované nástroje s integrovaným vývojovým prostředím (IDE), jako je integrovaný editor souborů prostředků sady Visual Studio nebo Visual Studio Code s příponou pro vytváření a úpravy souborů prostředků.

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>

Poznámka:

Následující soubor prostředků lze přidat v sadě Visual Studio tak, že kliknete pravým tlačítkem na Pages složku a vyberete Přidat>soubor prostředků nové položky.> Pojmenujte soubor CultureExample2.es.resx. Jakmile se zobrazí editor, zadejte data pro novou položku. Nastavte název na Greeting hodnotu a hodnotu na ¡Hola, Mundo!hodnotu . Uložte soubor.

Pokud používáte Visual Studio Code, doporučujeme nainstalovat Prohlížeč ResX a Editor Tima Heuera. Přidejte do Pages složky prázdný CultureExample2.resx soubor. Rozšíření automaticky převezme správu souboru v uživatelském rozhraní. Vyberte tlačítko Přidat nový prostředek. Podle pokynů přidejte položku ( Greeting klíč), ¡Hola, Mundo! (hodnota) a None (komentář). Uložte soubor. Pokud soubor zavřete a znovu otevřete, zobrazí se Greeting prostředek.

Následující příklad ukazuje typický soubor prostředků. Soubory prostředků můžete ručně umístit do složky aplikace Pages , pokud nechcete používat integrované nástroje s integrovaným vývojovým prostředím (IDE), jako je integrovaný editor souborů prostředků sady Visual Studio nebo Visual Studio Code s příponou pro vytváření a úpravy souborů prostředků.

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>

Následující komponenta ukazuje použití lokalizovaného Greeting řetězce s IStringLocalizer<T>. Kód Razor @Loc["Greeting"] v následujícím příkladu lokalizuje řetězec s klíčem k Greeting hodnotě, která je nastavena v předchozích souborech prostředků.

Přidejte obor názvů pro Microsoft.Extensions.Localization soubor aplikace _Imports.razor :

@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"];
    }
}

Volitelně můžete přidat položku nabídky pro CultureExample2 komponentu do navigace v komponentě NavMenu (NavMenu.razor).

Referenční zdroj zprostředkovatele jazykové verze WebAssembly

Pokud chcete lépe pochopit, jak Blazor architektura zpracovává lokalizaci, podívejte se na WebAssemblyCultureProvider třídu v referenčním zdroji ASP.NET Core.

Poznámka:

Odkazy na dokumentaci k referenčnímu zdroji .NET obvykle načítají výchozí větev úložiště, která představuje aktuální vývoj pro příští verzi .NET. Pokud chcete vybrat značku pro konkrétní verzi, použijte rozevírací seznam pro přepnutí větví nebo značek. Další informace najdete v tématu Jak vybrat značku verze zdrojového kódu ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Sdílené prostředky

Pokud chcete vytvořit sdílené prostředky lokalizace, použijte následující přístup.

  • Vytvořte fiktivní třídu s libovolným názvem třídy. V následujícím příkladu:

    • Aplikace používá BlazorSample obor názvů a prostředky lokalizace používají BlazorSample.Localization obor názvů.
    • Fiktivní třída má název SharedResource.
    • Soubor třídy se umístí do Localization složky v kořenovém adresáři aplikace.

    Localization/SharedResource.cs:

    namespace BlazorSample.Localization;

public class SharedResource
{
}

  • Vytvořte sdílené soubory prostředků pomocí akce sestavení .Embedded resource V následujícím příkladu:

    • Soubory jsou umístěny ve Localization složce s fiktivní SharedResource třídou (Localization/SharedResource.cs).

    • Pojmenujte soubory prostředků tak, aby odpovídaly názvu fiktivní třídy. Následující ukázkové soubory obsahují výchozí lokalizační soubor a soubor pro lokalizaci španělštiny (es).

    • Localization/SharedResource.resx

    • Localization/SharedResource.es.resx

    Upozorňující

    Pokud postupujete podle přístupu v této části, nemůžete současně nastavit LocalizationOptions.ResourcesPath a použít IStringLocalizerFactory.Create k načtení prostředků.

  • Chcete-li odkazovat na fiktivní třídu vložené IStringLocalizer<T> do Razor komponenty, buď umístěte @using direktivu pro lokalizační obor názvů nebo do odkazu na fimmy třídy obor názvů lokalizace. V následujících příkladech:

    • První příklad uvádí Localization obor názvů pro SharedResource fiktivní třídu s direktivou @using .
    • Druhý příklad explicitně uvádí SharedResource obor názvů fiktivní třídy.

    V komponentě Razor použijte některý z následujících přístupů:

    @using Localization
@inject IStringLocalizer<SharedResource> Loc

    @inject IStringLocalizer<Localization.SharedResource> Loc

Další pokyny najdete v tématu Globalizace a lokalizace v ASP.NET Core.

Přepsání polohy pomocí podokna Senzory v vývojářských nástrojích

Při použití přepsání umístění pomocí podokna Senzory v Google Chrome nebo vývojářských nástrojích Microsoft Edge se po předběžném nastavení resetuje záložní jazyk. Při testování se vyhněte nastavení jazyka pomocí podokna Senzory . Nastavte jazyk pomocí nastavení jazyka prohlížeče.

Další informace naleznete v tématu Blazor Lokalizace nefunguje s InteractiveServer (dotnet/aspnetcore #53707).

Další materiály