ASP.NET Globalisasi dan pelokalan Core Blazor

Artikel
11/06/2024

Catatan

Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Peringatan

Versi ASP.NET Core ini tidak lagi didukung. Untuk informasi selengkapnya, lihat Kebijakan Dukungan .NET dan .NET Core. Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Penting

Informasi ini berkaitan dengan produk pra-rilis yang mungkin dimodifikasi secara substansial sebelum dirilis secara komersial. Microsoft tidak memberikan jaminan, tersirat maupun tersurat, sehubungan dengan informasi yang diberikan di sini.

Untuk rilis saat ini, lihat versi .NET 8 dari artikel ini.

Artikel ini menjelaskan cara merender konten global dan terlokalisasi kepada pengguna dalam budaya dan bahasa yang berbeda.

Globalisasi dan pelokalan

Untuk globalisasi, Blazor menyediakan pemformatan angka dan tanggal. Untuk pelokalan, Blazor merender konten menggunakan sistem .NET Resources.

Serangkaian fitur pelokalan ASP.NET Core terbatas didukung:

Didukung: IStringLocalizer dan IStringLocalizer<T> didukung di Blazor aplikasi.

Tidak didukung: IHtmlLocalizerpelokalan Anotasi Data , IViewLocalizer, dan ASP.NET fitur Core MVC dan tidak didukung di Blazor aplikasi.

Artikel ini menjelaskan cara menggunakan Blazorfitur globalisasi dan pelokalan berdasarkan:

HeaderAccept-Language, yang diatur oleh browser berdasarkan preferensi bahasa pengguna di pengaturan browser.
Budaya yang ditetapkan oleh aplikasi tidak didasarkan pada nilai Accept-Language header. Pengaturan dapat statis untuk semua pengguna atau dinamis berdasarkan logika aplikasi. Saat pengaturan didasarkan pada preferensi pengguna, pengaturan biasanya disimpan untuk dimuat ulang pada kunjungan mendatang.

Untuk informasi umum tambahan, lihat sumber daya berikut ini:

Seringkali, istilah bahasa dan budaya digunakan secara bergantian ketika berhadapan dengan konsep globalisasi dan pelokalan.

Dalam artikel ini, bahasa mengacu pada pilihan yang dibuat oleh pengguna di pengaturan browser mereka. Pilihan bahasa pengguna dikirimkan dalam permintaan browser di Accept-Language header. Pengaturan browser biasanya menggunakan kata "bahasa" di UI.

Budaya berkaitan dengan anggota .NET dan Blazor API. Misalnya, permintaan pengguna dapat menyertakan header yang menentukan bahasa dari perspektif pengguna, tetapi aplikasi pada akhirnya mengatur CurrentCulture properti ("budaya") dari bahasa yang diminta pengguna.Accept-Language API biasanya menggunakan kata "budaya" dalam nama anggotanya.

Panduan dalam artikel ini tidak mencakup pengaturan atribut bahasa HTML halaman (<html lang="...">), alat aksesiblitas mana yang digunakan. Anda dapat mengatur nilai secara statis dengan menetapkan bahasa ke lang atribut <html> tag atau ke document.documentElement.lang di JavaScript. Anda dapat secara dinamis mengatur nilai document.documentElement.lang dengan JS interop.

Catatan

Contoh kode dalam artikel ini mengadopsi jenis referensi nullable (NRTs) dan .NET compiler null-state static analysis, yang didukung di ASP.NET Core di .NET 6 atau yang lebih baru. Saat menargetkan ASP.NET Core 5.0 atau yang lebih lama, hapus penunjukan jenis null (?) dari contoh artikel.

Globalisasi

Direktif @bind atribut menerapkan format dan mengurai nilai untuk ditampilkan berdasarkan bahasa pilihan pertama pengguna yang didukung aplikasi. @bind@bind:culture mendukung parameter untuk menyediakan System.Globalization.CultureInfo untuk mengurai dan memformat nilai.

Budaya saat ini dapat diakses dari System.Globalization.CultureInfo.CurrentCulture properti.

CultureInfo.InvariantCulture digunakan untuk jenis bidang berikut (<input type="{TYPE}" />, di mana {TYPE} tempat penampung adalah jenisnya):

date
number

Jenis bidang sebelumnya:

Ditampilkan menggunakan aturan pemformatan berbasis browser yang sesuai.
Tidak boleh berisi teks bentuk bebas.
Berikan karakteristik interaksi pengguna berdasarkan implementasi browser.

Blazor memberikan dukungan bawaan untuk merender nilai dalam budaya saat ini. Oleh karena itu, menentukan budaya dengan @bind:culture tidak disarankan saat menggunakan date jenis bidang dan number .

Jenis bidang berikut ini memiliki persyaratan pemformatan tertentu dan tidak didukung oleh semua browser utama, sehingga tidak didukung oleh Blazor:

datetime-local
month
week

Untuk dukungan browser saat ini dari jenis sebelumnya, lihat Dapatkah saya menggunakan.

Dukungan globalisasi .NET dan Komponen Internasional untuk Unicode (ICU) (Blazor WebAssembly)

Blazor WebAssembly menggunakan API globalisasi yang berkurang dan serangkaian Komponen Internasional bawaan untuk lokal Unicode (ICU). Untuk informasi selengkapnya, lihat globalisasi .NET dan ICU: ICU di WebAssembly.

Untuk memuat file data ICU kustom untuk mengontrol lokal aplikasi, lihat WASM Globalization Icu. Saat ini, diperlukan pembuatan file data ICU kustom secara manual. Alat .NET untuk memudahkan proses pembuatan file direncanakan untuk .NET 9 pada bulan November 2024.

Memuat subset kustom lokal dalam Blazor WebAssembly aplikasi didukung di .NET 8 atau yang lebih baru. Untuk informasi selengkapnya, akses bagian ini untuk versi 8.0 atau yang lebih baru dari artikel ini.

Globalisasi invarian

Bagian ini hanya berlaku untuk skenario sisi Blazor klien.

Jika aplikasi tidak memerlukan pelokalan, konfigurasikan aplikasi untuk mendukung budaya invarian, yang umumnya didasarkan pada bahasa Inggris Amerika Serikat (en-US). Menggunakan globalisasi invarian mengurangi ukuran unduhan aplikasi dan menghasilkan startup aplikasi yang lebih cepat. Atur InvariantGlobalization properti ke true dalam file proyek aplikasi (.csproj):

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

Atau, konfigurasikan globalisasi invarian dengan pendekatan berikut:

Di runtimeconfig.json:

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

Dengan variabel lingkungan:
- Kunci: DOTNET_SYSTEM_GLOBALIZATION_INVARIANT
- Nilai: true atau 1

Untuk informasi selengkapnya, lihat Opsi konfigurasi runtime untuk globalisasi (dokumentasi.NET).

Informasi zona waktu

Bagian ini hanya berlaku untuk skenario sisi Blazor klien.

Mengadopsi globalisasi invarian hanya menghasilkan penggunaan nama zona waktu yang tidak dilokalkan. Untuk memangkas kode dan data zona waktu, yang mengurangi ukuran unduhan aplikasi dan menghasilkan startup aplikasi yang lebih cepat, terapkan <InvariantTimezone> properti MSBuild dengan nilai true dalam file proyek aplikasi:

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

Catatan

<BlazorEnableTimeZoneSupport> mengambil alih pengaturan sebelumnya <InvariantTimezone> . Sebaiknya hapus <BlazorEnableTimeZoneSupport> pengaturan.

File data disertakan untuk membuat informasi zona waktu benar. Jika aplikasi tidak memerlukan fitur ini, pertimbangkan untuk menonaktifkannya dengan mengatur <BlazorEnableTimeZoneSupport> properti MSBuild ke false dalam file proyek aplikasi:

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

Komponen demonstrasi

Komponen berikut CultureExample1 dapat digunakan untuk menunjukkan Blazor konsep globalisasi dan pelokalan yang dicakup oleh artikel ini.

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

Format string angka (N2) dalam contoh sebelumnya (.ToString("N2")) adalah penentu format numerik .NET standar. N2 Format ini didukung untuk semua jenis numerik, termasuk pemisah grup, dan merender hingga dua tempat desimal.

Secara opsional, tambahkan item menu ke navigasi di NavMenu komponen (NavMenu.razor) untuk CultureExample1 komponen.

Mengatur budaya secara dinamis dari `Accept-Language` header

Microsoft.Extensions.Localization Tambahkan paket ke aplikasi.

Header Accept-Language diatur oleh browser dan dikontrol oleh preferensi bahasa pengguna di pengaturan browser. Di pengaturan browser, pengguna mengatur satu atau beberapa bahasa pilihan dalam urutan preferensi. Urutan preferensi digunakan oleh browser untuk mengatur nilai kualitas (q, 0-1) untuk setiap bahasa di header. Contoh berikut menentukan Amerika Serikat bahasa Inggris, Inggris, dan Kosta Rika Spanyol dengan preferensi untuk Amerika Serikat bahasa Inggris atau Inggris:

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

Budaya aplikasi diatur dengan mencocokkan bahasa yang diminta pertama yang cocok dengan budaya aplikasi yang didukung.

Dalam pengembangan sisi klien, atur BlazorWebAssemblyLoadAllGlobalizationData properti ke true dalam file proyek aplikasi sisi klien (.csproj):

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

Dalam pengembangan sisi klien, secara dinamis mengatur budaya dari Accept-Language header tidak didukung.

Catatan

Jika spesifikasi aplikasi memerlukan pembatasan budaya yang didukung ke daftar eksplisit, lihat bagian Secara dinamis mengatur budaya sisi klien menurut preferensi pengguna di artikel ini.

Aplikasi dilokalkan menggunakan Middleware Pelokalan. Tambahkan layanan pelokalan ke aplikasi dengan AddLocalization.

Tambahkan baris berikut ke Program file tempat layanan terdaftar:

builder.Services.AddLocalization();

Dalam pengembangan sisi server, tentukan budaya aplikasi yang didukung sebelum middleware apa pun yang mungkin memeriksa budaya permintaan. Umumnya, tempatkan Middleware Pelokalan Permintaan segera sebelum memanggil MapRazorComponents. Contoh berikut mengonfigurasi budaya yang didukung untuk bahasa Inggris Amerika Serikat dan Bahasa Spanyol Costa Rican:

Dalam pengembangan sisi server, tentukan budaya aplikasi yang didukung segera setelah Middleware Perutean (UseRouting) ditambahkan ke alur pemrosesan. Contoh berikut mengonfigurasi budaya yang didukung untuk bahasa Inggris Amerika Serikat dan Bahasa Spanyol Costa Rican:

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

Untuk informasi tentang memesan Middleware Pelokalan di alur Program middleware file, lihat ASP.NET Core Middleware.

Catatan

Beberapa browser memaksa Anda menggunakan pengaturan bahasa default untuk permintaan dan pengaturan UI browser sendiri. Ini dapat membuat perubahan bahasa kembali ke bahasa yang Sulit Anda pahami karena semua layar antarmuka pengguna pengaturan mungkin berakhir dalam bahasa yang tidak dapat Anda baca. Browser seperti Opera adalah pilihan yang baik untuk pengujian karena memungkinkan Anda mengatur bahasa default untuk permintaan halaman web tetapi meninggalkan antarmuka pengguna pengaturan browser dalam bahasa Anda.

Ketika budaya Amerika Serikat Bahasa Inggris (en-US), komponen yang dirender menggunakan pemformatan tanggal bulan/hari (6/7), waktu 12 jam (PMAM/), dan pemisah koma dalam angka dengan titik untuk nilai desimal ():1,999.69

Tanggal: 7/6/2021 06:45:22
Nomor: 1.999,69

Ketika budayanya adalah Costa Rican Spanyol (es-CR), komponen yang dirender menggunakan pemformatan tanggal hari/bulan (7/6), waktu 24 jam, dan pemisah periode dalam angka dengan koma untuk nilai desimal (1.999,69):

Tanggal: 6/7/2021 6:49:38
Nomor: 1.999,69

Mengatur budaya sisi klien secara statis

Atur BlazorWebAssemblyLoadAllGlobalizationData properti ke true dalam file proyek aplikasi (.csproj):

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

Konfigurasi Intermediate Language (IL) Linker untuk penyajian sisi klien menghapus informasi internasionalisasi kecuali untuk lokal yang diminta secara eksplisit. Untuk informasi selengkapnya, lihat Mengonfigurasi Linker untuk ASP.NET Core Blazor.

Budaya aplikasi dapat diatur di JavaScript saat Blazor dimulai dengan applicationCultureBlazor opsi mulai. Contoh berikut mengonfigurasi aplikasi untuk diluncurkan menggunakan budaya bahasa Inggris Amerika Serikat (en-US).

Cegah Blazor mulai otomatis dengan menambahkan autostart="false" ke Blazor<script> tag:

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

Dalam contoh sebelumnya, {BLAZOR SCRIPT} tempat penampung adalah Blazor jalur skrip dan nama file. Untuk lokasi skrip, lihat struktur proyek ASP.NET CoreBlazor.

Tambahkan blok berikut <script> setelah Blazortag dan <script> sebelum tag penutup</body>:

Blazor Web App:

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

Mandiri Blazor WebAssembly:

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

Nilai untuk applicationCulture harus sesuai dengan format tag bahasa BCP-47. Untuk informasi lebih lanjut tentang startup Blazor, lihat startup BlazorASP.NET Core.

Alternatif untuk mengatur opsi mulai budaya Blazoradalah mengatur budaya dalam kode C#. Atur CultureInfo.DefaultThreadCurrentCulture Program dan CultureInfo.DefaultThreadCurrentUICulture dalam file ke budaya yang sama.

System.Globalization Tambahkan namespace ke Program file:

using System.Globalization;

Tambahkan pengaturan budaya sebelum garis yang membangun dan menjalankan WebAssemblyHostBuilder (await builder.Build().RunAsync();):

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

Catatan

Saat ini, Blazor WebAssembly aplikasi hanya memuat sumber daya berdasarkan DefaultThreadCurrentCulture. Untuk informasi selengkapnya, lihat Blazor WASM hanya bergantung pada budaya saat ini (budaya UI saat ini tidak dihormati) (dotnet/aspnetcore #56824).

Gunakan komponen yang CultureExample1 ditunjukkan di bagian Komponen demonstrasi untuk mempelajari cara kerja globalisasi. Terbitkan permintaan dengan bahasa Inggris Amerika Serikat (en-US). Beralih ke Costa Rican Spanyol (es-CR) di pengaturan bahasa browser. Minta halaman web lagi. Ketika bahasa yang diminta adalah Bahasa Spanyol Costa Rican, budaya aplikasi tetap Amerika Serikat Bahasa Inggris (en-US).

Mengatur budaya sisi server secara statis

Aplikasi sisi server dilokalkan menggunakan Middleware Pelokalan. Tambahkan layanan pelokalan ke aplikasi dengan AddLocalization.

Dalam file Program:

builder.Services.AddLocalization();

Tentukan budaya statis dalam Program file sebelum middleware apa pun yang mungkin memeriksa budaya permintaan. Umumnya, tempatkan Middleware Pelokalan Permintaan segera sebelum MapRazorComponents. Contoh berikut mengonfigurasi Amerika Serikat bahasa Inggris:

Tentukan budaya statis dalam Program file segera setelah Middleware Perutean (UseRouting) ditambahkan ke alur pemrosesan. Contoh berikut mengonfigurasi Amerika Serikat bahasa Inggris:

app.UseRequestLocalization("en-US");

Nilai budaya untuk UseRequestLocalization harus sesuai dengan format tag bahasa BCP-47.

Untuk informasi tentang memesan Middleware Pelokalan di alur Program middleware file, lihat ASP.NET Core Middleware.

Aplikasi sisi server dilokalkan menggunakan Middleware Pelokalan. Tambahkan layanan pelokalan ke aplikasi dengan AddLocalization.

Dalam Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

Tentukan budaya statis di Startup.Configure (Startup.cs) segera setelah Middleware Perutean ditambahkan ke alur pemrosesan. Contoh berikut mengonfigurasi Amerika Serikat bahasa Inggris:

app.UseRequestLocalization("en-US");

Nilai budaya untuk UseRequestLocalization harus sesuai dengan format tag bahasa BCP-47.

Untuk informasi tentang memesan Middleware Pelokalan di alur Startup.Configuremiddleware , lihat ASP.NET Core Middleware.

Mengatur budaya sisi klien secara dinamis berdasarkan preferensi pengguna

Contoh lokasi di mana aplikasi mungkin menyimpan preferensi pengguna termasuk dalam penyimpanan lokal browser (umum untuk skenario sisi klien), dalam pelokalan cookie atau database (umum untuk skenario sisi server), atau dalam layanan eksternal yang dilampirkan ke database eksternal dan diakses oleh API web. Contoh berikut menunjukkan cara menggunakan penyimpanan lokal browser.

Microsoft.Extensions.Localization Tambahkan paket ke aplikasi.

Catatan

Untuk panduan tentang menambahkan paket ke aplikasi .NET, lihat artikel di bagian Menginstal dan mengelola paket di Alur kerja konsumsi paket (dokumentasi NuGet). Konfirmasikan versi paket yang benar di NuGet.org.

Atur properti ke BlazorWebAssemblyLoadAllGlobalizationData true dalam file proyek:

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

Budaya aplikasi untuk penyajian sisi klien diatur menggunakan Blazor API kerangka kerja. Pilihan budaya pengguna dapat dipertahankan di penyimpanan lokal browser.

Berikan JS fungsi setelah <script> Blazortag untuk mendapatkan dan mengatur pilihan budaya pengguna dengan penyimpanan lokal browser:

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

Catatan

Contoh sebelumnya mencemari klien dengan fungsi global. Untuk pendekatan yang lebih baik dalam aplikasi produksi, lihat Isolasi JavaScript dalam modul JavaScript.

Tambahkan namespace untuk System.Globalization dan Microsoft.JSInterop ke bagian Program atas file:

using System.Globalization;
using Microsoft.JSInterop;

Hapus baris berikut:

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

Ganti baris sebelumnya dengan kode berikut. Kode menambahkan Blazorlayanan pelokalan ke koleksi layanan aplikasi dengan AddLocalization dan menggunakan JS interop untuk memanggil JS dan mengambil pilihan budaya pengguna dari penyimpanan lokal. Jika penyimpanan lokal tidak berisi budaya untuk pengguna, kode menetapkan nilai default Amerika Serikat Bahasa Inggris (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();

Catatan

Komponen berikut menunjukkan CultureSelector cara melakukan tindakan berikut:

Atur pilihan budaya pengguna ke penyimpanan lokal browser melalui JS interop.
Muat ulang komponen yang mereka minta (forceLoad: true), yang menggunakan budaya yang diperbarui.

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

Catatan

Untuk informasi selengkapnya tentang IJSInProcessRuntime, lihat Memanggil fungsi JavaScript dari metode .NET di ASP.NET Core Blazor.

Di dalam tag </main> penutup elemen dalam MainLayout komponen (MainLayout.razor), tambahkan CultureSelector komponen:

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

Gunakan komponen yang CultureExample1 ditunjukkan di bagian Komponen demonstrasi untuk mempelajari cara kerja contoh sebelumnya.

Mengatur budaya sisi server secara dinamis berdasarkan preferensi pengguna

Contoh lokasi di mana aplikasi mungkin menyimpan preferensi pengguna termasuk dalam penyimpanan lokal browser (umum untuk skenario sisi klien), dalam pelokalan cookie atau database (umum untuk skenario sisi server), atau dalam layanan eksternal yang dilampirkan ke database eksternal dan diakses oleh API web. Contoh berikut menunjukkan cara menggunakan pelokalan cookie.

Catatan

Contoh berikut mengasumsikan bahwa aplikasi mengadopsi interaktivitas global dengan menentukan penyajian sisi server interaktif (SSR interaktif) pada Routes komponen dalam App komponen (Components/App.razor):

<Routes @rendermode="InteractiveServer" />

Jika aplikasi mengadopsi interaktivitas per halaman/komponen , lihat komentar di akhir bagian ini untuk memodifikasi mode render komponen contoh.

Microsoft.Extensions.Localization Tambahkan paket ke aplikasi.

Catatan

Aplikasi sisi server dilokalkan menggunakan Middleware Pelokalan. Tambahkan layanan pelokalan ke aplikasi dengan AddLocalization.

Dalam file Program:

builder.Services.AddLocalization();

Atur budaya default dan didukung aplikasi dengan RequestLocalizationOptions.

Sebelum panggilan ke MapRazorComponents dalam alur pemrosesan permintaan, letakkan kode berikut:

Setelah Middleware Perutean (UseRouting) ditambahkan ke alur pemrosesan permintaan, letakkan kode berikut:

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

app.UseRequestLocalization(localizationOptions);

Untuk informasi tentang memesan Middleware Pelokalan di alur middleware, lihat ASP.NET Core Middleware.

Contoh berikut menunjukkan cara mengatur budaya saat ini dalam cookie yang dapat dibaca oleh Middleware Pelokalan.

Namespace berikut diperlukan untuk App komponen:

Tambahkan yang berikut ini ke bagian App atas file komponen (Components/App.razor):

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

Tambahkan blok berikut @code ke bagian App bawah file komponen:

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

Modifikasi pada Pages/_Host.cshtml file memerlukan namespace berikut:

Tambahkan teks berikut ke file:

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

Untuk informasi tentang memesan Middleware Pelokalan di alur middleware, lihat ASP.NET Core Middleware.

Jika aplikasi tidak dikonfigurasi untuk memproses tindakan pengontrol:

Tambahkan layanan MVC dengan memanggil AddControllers kumpulan layanan dalam Program file:
```
builder.Services.AddControllers();
```
Tambahkan perutean titik akhir pengontrol dalam Program file dengan memanggil MapControllers pada IEndpointRouteBuilder (app):
```
app.MapControllers();
```

Untuk menyediakan UI agar pengguna dapat memilih budaya, gunakan pendekatan berbasis pengalihan dengan pelokalan cookie. Aplikasi ini mempertahankan budaya yang dipilih pengguna melalui pengalihan ke pengontrol. Pengontrol mengatur budaya yang dipilih pengguna menjadi cookie dan mengalihkan pengguna kembali ke URI asli. Prosesnya mirip dengan apa yang terjadi di aplikasi web ketika pengguna mencoba mengakses sumber daya yang aman, di mana pengguna dialihkan ke halaman masuk lalu dialihkan kembali ke sumber daya asli.

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

Peringatan

Gunakan hasil LocalRedirect tindakan, seperti yang ditunjukkan dalam contoh sebelumnya, untuk mencegah serangan pengalihan terbuka. Untuk informasi selengkapnya, lihat Mencegah serangan pengalihan terbuka di ASP.NET Core.

Komponen berikut CultureSelector menunjukkan cara memanggil Set metode CultureController dengan budaya baru. Komponen ditempatkan di Shared folder untuk digunakan di seluruh aplikasi.

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

CultureSelector Tambahkan komponen ke MainLayout komponen. Tempatkan markup berikut di dalam tag penutup </main> dalam Components/Layout/MainLayout.razor file:

CultureSelector Tambahkan komponen ke MainLayout komponen. Tempatkan markup berikut di dalam tag penutup </main> dalam Shared/MainLayout.razor file:

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

Gunakan komponen yang CultureExample1 ditunjukkan di bagian Komponen demonstrasi untuk mempelajari cara kerja contoh sebelumnya.

Contoh sebelumnya mengasumsikan bahwa aplikasi mengadopsi interaktivitas global dengan menentukan mode render Server Interaktif pada Routes komponen dalam App komponen (Components/App.razor):

<Routes @rendermode="InteractiveServer" />

Jika aplikasi mengadopsi interaktivitas per halaman/komponen , buat perubahan berikut:

Tambahkan mode render Server Interaktif ke bagian CultureExample1 atas file komponen (Components/Pages/CultureExample1.razor):
```
@rendermode InteractiveServer
```
Di tata letak utama aplikasi (Components/Layout/MainLayout.razor), terapkan mode render Server Interaktif ke CultureSelector komponen:
```
<CultureSelector @rendermode="InteractiveServer" />
```

Mengatur budaya secara dinamis dalam preferensi Blazor Web App pengguna

Bagian ini berlaku untuk Blazor Web Appyang mengadopsi interaktivitas Otomatis (Server dan WebAssembly).

Contoh lokasi di mana aplikasi mungkin menyimpan preferensi pengguna termasuk dalam penyimpanan lokal browser (umum untuk skenario sisi klien), dalam pelokalan cookie atau database (umum untuk skenario sisi server), penyimpanan lokal dan pelokalan cookie (Blazor Web Appdengan komponen server dan WebAssembly), atau dalam layanan eksternal yang dilampirkan ke database eksternal dan diakses oleh API web. Contoh berikut menunjukkan cara menggunakan penyimpanan lokal browser untuk komponen yang dirender sisi klien (CSR) dan pelokalan cookie untuk komponen server-side rendered (SSR).

Pembaruan untuk `.Client` proyek

Microsoft.Extensions.Localization Tambahkan paket ke .Client proyek.

Catatan

Atur properti ke BlazorWebAssemblyLoadAllGlobalizationData true dalam .Client file proyek:

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

Tambahkan namespace layanan untuk System.Globalization dan ke bagian .Client atas file proyek Program Microsoft.JSInterop:

using System.Globalization;
using Microsoft.JSInterop;

Hapus baris berikut:

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

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

Catatan

Tambahkan komponen berikut CultureSelector ke .Client proyek.

Komponen mengadopsi pendekatan berikut untuk bekerja baik untuk komponen SSR atau CSR:

Nama tampilan setiap budaya yang tersedia dalam daftar dropdown disediakan oleh kamus karena data globalisasi sisi klien mencakup teks nama tampilan budaya yang dilokalkan yang disediakan data globalisasi sisi server. Misalnya, pelokalan sisi server ditampilkan English (United States) ketika en-US adalah budaya dan Ingles () ketika budaya yang berbeda digunakan. Karena pelokalan nama tampilan budaya tidak tersedia dengan Blazor WebAssembly globalisasi, nama tampilan untuk Amerika Serikat bahasa Inggris pada klien untuk budaya yang dimuat hanyalah en-US. Menggunakan kamus kustom memungkinkan komponen untuk setidaknya menampilkan nama budaya inggris lengkap.
Ketika pengguna mengubah budaya, JS interop mengatur budaya di penyimpanan browser lokal dan tindakan pengontrol memperbarui pelokalan cookie dengan budaya. Pengontrol ditambahkan ke aplikasi nanti di bagian Pembaruan proyek server.

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

Catatan

Untuk informasi selengkapnya tentang IJSInProcessRuntime, lihat Memanggil fungsi JavaScript dari metode .NET di ASP.NET Core Blazor.

.Client Dalam proyek, tempatkan komponen berikut CultureClient untuk mempelajari cara kerja globalisasi untuk komponen 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;
}

Pembaruan proyek server

Microsoft.Extensions.Localization Tambahkan paket ke proyek server.

Catatan

Aplikasi sisi server dilokalkan menggunakan Middleware Pelokalan. Tambahkan layanan pelokalan ke aplikasi dengan AddLocalization.

Dalam file proyek Program server tempat layanan didaftarkan:

builder.Services.AddLocalization();

Atur budaya default dan didukung aplikasi dengan RequestLocalizationOptions.

Sebelum panggilan ke MapRazorComponents dalam alur pemrosesan permintaan, letakkan kode berikut:

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

app.UseRequestLocalization(localizationOptions);

Contoh berikut menunjukkan cara mengatur budaya saat ini dalam cookie yang dapat dibaca oleh Middleware Pelokalan.

Namespace berikut diperlukan untuk App komponen:

Tambahkan yang berikut ini ke bagian App atas file komponen (Components/App.razor):

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

Budaya aplikasi untuk penyajian sisi klien diatur menggunakan Blazor API kerangka kerja. Pilihan budaya pengguna dapat dipertahankan di penyimpanan lokal browser untuk komponen CSR.

BlazorSetelah tag , <script> berikan JS fungsi untuk mendapatkan dan mengatur pilihan budaya pengguna dengan penyimpanan lokal browser:

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

Catatan

Contoh sebelumnya mencemari klien dengan fungsi global. Untuk pendekatan yang lebih baik dalam aplikasi produksi, lihat Isolasi JavaScript dalam modul JavaScript.

Tambahkan blok berikut @code ke bagian App bawah file komponen:

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

Jika proyek server tidak dikonfigurasi untuk memproses tindakan pengontrol:

Tambahkan layanan MVC dengan memanggil AddControllers kumpulan layanan dalam Program file:
```
builder.Services.AddControllers();
```
Tambahkan perutean titik akhir pengontrol dalam Program file dengan memanggil MapControllers pada IEndpointRouteBuilder (app):
```
app.MapControllers();
```

Untuk memungkinkan pengguna memilih budaya untuk komponen SSR, gunakan pendekatan berbasis pengalihan dengan pelokalan cookie. Aplikasi ini mempertahankan budaya yang dipilih pengguna melalui pengalihan ke pengontrol. Pengontrol mengatur budaya yang dipilih pengguna menjadi cookie dan mengalihkan pengguna kembali ke URI asli. Prosesnya mirip dengan apa yang terjadi di aplikasi web ketika pengguna mencoba mengakses sumber daya yang aman, di mana pengguna dialihkan ke halaman masuk lalu dialihkan kembali ke sumber daya asli.

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

Peringatan

CultureSelector Tambahkan komponen ke MainLayout komponen. Tempatkan markup berikut di dalam tag penutup </main> dalam Components/Layout/MainLayout.razor file:

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

Gunakan komponen yang CultureExample1 ditunjukkan di bagian Komponen demonstrasi untuk mempelajari cara kerja contoh sebelumnya.

Dalam proyek server, tempatkan komponen berikut CultureServer untuk mempelajari cara kerja globalisasi untuk komponen 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;
}

Tambahkan komponen CultureClient dan CultureServer ke navigasi bilah samping di Components/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>

Komponen Otomatis Interaktif

Panduan di bagian ini juga berfungsi untuk komponen yang mengadopsi mode render Otomatis Interaktif:

@rendermode InteractiveAuto

Pelokalan

Jika aplikasi belum mendukung pemilihan budaya dinamis, tambahkan Microsoft.Extensions.Localization paket ke aplikasi.

Catatan

Pelokalan sisi klien

Atur BlazorWebAssemblyLoadAllGlobalizationData properti ke true dalam file proyek aplikasi (.csproj):

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

Program Dalam file, tambahkan namespace layanan untuk System.Globalization ke bagian atas file:

using System.Globalization;

Tambahkan Blazorlayanan pelokalan ke koleksi layanan aplikasi dengan AddLocalization:

builder.Services.AddLocalization();

Pelokalan sisi server

Gunakan Middleware Pelokalan untuk mengatur budaya aplikasi.

Jika aplikasi belum mendukung pemilihan budaya dinamis:

Tambahkan layanan pelokalan ke aplikasi dengan AddLocalization.
Tentukan budaya default dan didukung aplikasi dalam Program file. Contoh berikut mengonfigurasi budaya yang didukung untuk bahasa Inggris Amerika Serikat dan Bahasa Spanyol Costa Rican.

builder.Services.AddLocalization();

Tempatkan Middleware Pelokalan Permintaan sebelum middleware apa pun yang mungkin memeriksa budaya permintaan. Umumnya, tempatkan middleware segera sebelum memanggil MapRazorComponents:

Segera setelah Middleware Perutean (UseRouting) ditambahkan ke alur pemrosesan:

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

app.UseRequestLocalization(localizationOptions);

Untuk informasi tentang memesan Middleware Pelokalan di alur middleware, lihat ASP.NET Core Middleware.

Tambahkan layanan pelokalan ke aplikasi dengan AddLocalization.
Tentukan budaya default dan didukung aplikasi di Startup.Configure (Startup.cs). Contoh berikut mengonfigurasi budaya yang didukung untuk bahasa Inggris Amerika Serikat dan Bahasa Spanyol Costa Rican.

Dalam Startup.ConfigureServices (Startup.cs):

services.AddLocalization();

Segera Startup.Configure setelah Middleware Perutean (UseRouting) ditambahkan ke alur pemrosesan:

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

app.UseRequestLocalization(localizationOptions);

Untuk informasi tentang memesan Middleware Pelokalan di alur Startup.Configuremiddleware , lihat ASP.NET Core Middleware.

Jika aplikasi harus melokalisasi sumber daya berdasarkan penyimpanan pengaturan budaya pengguna, gunakan budaya pelokalan cookie. Penggunaan cookie memastikan bahwa koneksi WebSocket dapat menyebarkan budaya dengan benar. Jika skema pelokalan didasarkan pada jalur URL atau string kueri, skema mungkin tidak dapat bekerja dengan WebSocket, sehingga gagal mempertahankan budaya. Oleh karena itu, pendekatan yang direkomendasikan adalah menggunakan budaya cookielokalisasi . Lihat bagian Secara dinamis mengatur budaya sisi server menurut preferensi pengguna di artikel ini untuk melihat contoh Razor ekspresi yang mempertahankan pilihan budaya pengguna.

Contoh sumber daya yang dilokalkan

Contoh sumber daya yang dilokalkan di bagian ini berfungsi dengan contoh sebelumnya dalam artikel ini di mana budaya yang didukung aplikasi adalah bahasa Inggris (en) sebagai lokal default dan Spanyol (es) sebagai lokal alternatif yang dapat dipilih pengguna atau yang ditentukan browser.

Buat file sumber daya untuk setiap lokal. Dalam contoh berikut, sumber daya dibuat untuk Greeting string dalam bahasa Inggris dan Spanyol:

Bahasa Inggris (en): Hello, World!
Spanyol (es): ¡Hola, Mundo!

Catatan

File sumber daya berikut dapat ditambahkan di Visual Studio dengan mengklik Pages kanan folder dan memilih Tambahkan>File Sumber Daya Item>Baru. Beri nama file CultureExample2.resx. Saat editor muncul, berikan data untuk entri baru. Atur Nama ke Greeting dan Nilai ke Hello, World!. Simpan file.

Jika menggunakan Visual Studio Code, sebaiknya instal Penampil dan Editor ResX Tim Heuer. Tambahkan file kosong CultureExample2.resx ke Pages folder . Ekstensi secara otomatis mengambil alih pengelolaan file di UI. Pilih tombol Tambahkan Sumber Daya Baru. Ikuti instruksi untuk menambahkan entri untuk Greeting (kunci), Hello, World! (nilai), dan None (komentar). Simpan file. Jika Anda menutup dan membuka kembali file, Anda dapat melihat Greeting sumber daya.

Penampil dan Editor ResX Tim Heuer tidak dimiliki atau dikelola oleh Microsoft dan tidak tercakup oleh Perjanjian Dukungan Microsoft atau lisensi apa pun.

Berikut ini menunjukkan file sumber daya umum. Anda dapat menempatkan file sumber daya secara manual ke folder aplikasi Pages jika Anda lebih suka tidak menggunakan alat bawaan dengan lingkungan pengembangan terintegrasi (IDE), seperti editor file sumber daya bawaan Visual Studio atau Visual Studio Code dengan ekstensi untuk membuat dan mengedit file sumber daya.

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>

Catatan

File sumber daya berikut dapat ditambahkan di Visual Studio dengan mengklik Pages kanan folder dan memilih Tambahkan>File Sumber Daya Item>Baru. Beri nama file CultureExample2.es.resx. Saat editor muncul, berikan data untuk entri baru. Atur Nama ke Greeting dan Nilai ke ¡Hola, Mundo!. Simpan file.

Jika menggunakan Visual Studio Code, sebaiknya instal Penampil dan Editor ResX Tim Heuer. Tambahkan file kosong CultureExample2.resx ke Pages folder . Ekstensi secara otomatis mengambil alih pengelolaan file di UI. Pilih tombol Tambahkan Sumber Daya Baru. Ikuti instruksi untuk menambahkan entri untuk Greeting (kunci), ¡Hola, Mundo! (nilai), dan None (komentar). Simpan file. Jika Anda menutup dan membuka kembali file, Anda dapat melihat Greeting sumber daya.

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>

Komponen berikut menunjukkan penggunaan string yang dilokalkan Greeting dengan IStringLocalizer<T>. Razor Markup @Loc["Greeting"] dalam contoh berikut melokalisasi string yang dikunci ke Greeting nilai , yang diatur dalam file sumber daya sebelumnya.

Tambahkan namespace layanan untuk Microsoft.Extensions.Localization ke file aplikasi _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"];
    }
}

Secara opsional, tambahkan item menu untuk CultureExample2 komponen ke navigasi di NavMenu komponen (NavMenu.razor).

Sumber referensi penyedia budaya WebAssembly

Untuk lebih memahami bagaimana Blazor kerangka kerja memproses pelokalan, lihat WebAssemblyCultureProvider kelas di sumber referensi ASP.NET Core.

Catatan

Tautan dokumentasi ke sumber referensi .NET biasanya memuat cabang default repositori, yang mewakili pengembangan saat ini untuk rilis .NET berikutnya. Untuk memilih tag rilis tertentu, gunakan daftar dropdown Beralih cabang atau tag. Untuk informasi lebih lanjut, lihat Cara memilih tag versi kode sumber ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Sumber Daya Bersama

Untuk membuat sumber daya bersama pelokalan, adopsi pendekatan berikut.

Buat kelas dummy dengan nama kelas arbitrer. Dalam contoh berikut:
- Aplikasi ini menggunakan BlazorSample namespace layanan, dan aset pelokalan menggunakan BlazorSample.Localization namespace layanan.
- Kelas dummy diberi nama SharedResource.
- File kelas ditempatkan di Localization folder di akar aplikasi.
Localization/SharedResource.cs:
```
namespace BlazorSample.Localization;

public class SharedResource
{
}
```
Buat file sumber daya bersama dengan Tindakan Build .Embedded resource Dalam contoh berikut:
- File ditempatkan di Localization folder dengan kelas dummy SharedResource (Localization/SharedResource.cs).
- Beri nama file sumber daya agar sesuai dengan nama kelas dummy. Contoh file berikut menyertakan file pelokalan default dan file untuk pelokalan Spanyol (es).
- Localization/SharedResource.resx
- Localization/SharedResource.es.resx
Peringatan

Saat mengikuti pendekatan di bagian ini, Anda tidak dapat mengatur LocalizationOptions.ResourcesPath dan menggunakan IStringLocalizerFactory.Create secara bersamaan untuk memuat sumber daya.
Untuk mereferensikan kelas dummy untuk disuntikkan dalam Razor komponen, tempatkan @using IStringLocalizer<T> direktif untuk namespace pelokalan atau sertakan namespace pelokalan dalam referensi kelas dummy. Dalam contoh berikut:
- Contoh pertama menyatakan Localization namespace layanan untuk SharedResource kelas dummy dengan direktif @using .
- Contoh kedua menyatakan SharedResource namespace kelas dummy secara eksplisit.
Razor Dalam komponen, gunakan salah satu pendekatan berikut:
```
@using Localization
@inject IStringLocalizer<SharedResource> Loc
```
```
@inject IStringLocalizer<Localization.SharedResource> Loc
```

Untuk panduan tambahan, lihat Globalisasi dan pelokalan di ASP.NET Core.

Penimpaan lokasi menggunakan panel "Sensor" di alat pengembang

Saat menggunakan penimpaan lokasi menggunakan panel Sensor di Google Chrome atau alat pengembang Microsoft Edge, bahasa fallback diatur ulang setelah prarender. Hindari mengatur bahasa menggunakan panel Sensor saat pengujian. Atur bahasa menggunakan pengaturan bahasa browser.

Untuk informasi selengkapnya, lihat Blazor Pelokalan tidak berfungsi dengan InteractiveServer (dotnet/aspnetcore #53707).

Bagikan melalui

ASP.NET Globalisasi dan pelokalan Core Blazor

Globalisasi dan pelokalan

Globalisasi

Dukungan globalisasi .NET dan Komponen Internasional untuk Unicode (ICU) (Blazor WebAssembly)

Globalisasi invarian

Informasi zona waktu

Komponen demonstrasi

Mengatur budaya secara dinamis dari `Accept-Language` header

Mengatur budaya sisi klien secara statis

Mengatur budaya sisi server secara statis

Mengatur budaya sisi klien secara dinamis berdasarkan preferensi pengguna

Mengatur budaya sisi server secara dinamis berdasarkan preferensi pengguna

Mengatur budaya secara dinamis dalam preferensi Blazor Web App pengguna

Pembaruan untuk `.Client` proyek

Pembaruan proyek server

Komponen Otomatis Interaktif

Pelokalan

Pelokalan sisi klien

Pelokalan sisi server

Contoh sumber daya yang dilokalkan

Sumber referensi penyedia budaya WebAssembly

Sumber Daya Bersama

Penimpaan lokasi menggunakan panel "Sensor" di alat pengembang

Sumber Daya Tambahan:

Sumber Daya Tambahan:

Bagikan melalui

ASP.NET Globalisasi dan pelokalan Core Blazor

Globalisasi dan pelokalan

Globalisasi

Dukungan globalisasi .NET dan Komponen Internasional untuk Unicode (ICU) (Blazor WebAssembly)

Globalisasi invarian

Informasi zona waktu

Komponen demonstrasi

Mengatur budaya secara dinamis dari Accept-Language header

Mengatur budaya sisi klien secara statis

Mengatur budaya sisi server secara statis

Mengatur budaya sisi klien secara dinamis berdasarkan preferensi pengguna

Mengatur budaya sisi server secara dinamis berdasarkan preferensi pengguna

Mengatur budaya secara dinamis dalam preferensi Blazor Web App pengguna

Pembaruan untuk .Client proyek

Pembaruan proyek server

Komponen Otomatis Interaktif

Pelokalan

Pelokalan sisi klien

Pelokalan sisi server

Contoh sumber daya yang dilokalkan

Sumber referensi penyedia budaya WebAssembly

Sumber Daya Bersama

Penimpaan lokasi menggunakan panel "Sensor" di alat pengembang

Sumber Daya Tambahan:

Sumber Daya Tambahan:

Mengatur budaya secara dinamis dari `Accept-Language` header

Pembaruan untuk `.Client` proyek