Menerapkan strategi untuk memilih bahasa/budaya untuk setiap permintaan di aplikasi ASP.NET Core yang dilokalkan

Hisham Bin Ateya, Damien Bowden, Bart Calixto, Nadeem Afana, dan Rick Anderson

Salah satu tugas untuk melokalisasi aplikasi adalah menerapkan strategi untuk memilih budaya yang sesuai untuk setiap respons yang dikembalikan aplikasi.

Mengonfigurasi middleware Pelokalan

Budaya saat ini pada permintaan diatur dalam Middleware pelokalan. Middleware pelokalan diaktifkan di Program.cs. Middleware pelokalan harus dikonfigurasi sebelum middleware apa pun yang mungkin memeriksa budaya permintaan (misalnya, app.UseMvcWithDefaultRoute()).

builder.Services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[] { "en-US", "fr" };
    options.SetDefaultCulture(supportedCultures[0])
        .AddSupportedCultures(supportedCultures)
        .AddSupportedUICultures(supportedCultures);
});

UseRequestLocalization menginisialisasi RequestLocalizationOptions objek. Pada setiap permintaan daftar RequestCultureProvider dalam RequestLocalizationOptions dijumlahkan dan penyedia pertama yang dapat berhasil menentukan budaya permintaan digunakan. Penyedia default berasal dari RequestLocalizationOptions kelas :

1. QueryStringRequestCultureProvider
2. CookieRequestCultureProvider
3. AcceptLanguageHeaderRequestCultureProvider

Daftar default berubah dari yang paling spesifik ke paling tidak spesifik. Nantinya dalam artikel ini Anda akan melihat bagaimana Anda dapat mengubah pesanan dan bahkan menambahkan penyedia budaya kustom. Jika tidak ada penyedia yang dapat menentukan budaya permintaan, maka DefaultRequestCulture akan digunakan.

QueryStringRequestCultureProvider

Beberapa aplikasi akan menggunakan string kueri untuk mengatur CultureInfo. Untuk aplikasi yang menggunakan cookie pendekatan header Atau Terima-Bahasa, menambahkan string kueri ke URL berguna untuk kode penelusuran kesalahan dan pengujian. Secara default, QueryStringRequestCultureProvider terdaftar sebagai penyedia pelokalan pertama dalam RequestCultureProvider daftar. Anda meneruskan parameter culture string kueri dan ui-culture. Contoh berikut menetapkan budaya tertentu (bahasa dan wilayah) ke Spanyol/Meksiko:

http://localhost:5000/?culture=es-MX&ui-culture=es-MX

Jika hanya culture atau ui-culture diteruskan, penyedia string kueri mengatur kedua nilai menggunakan nilai yang diteruskan. Misalnya, mengatur hanya budaya yang akan mengatur Culture dan UICulture:

http://localhost:5000/?culture=es-MX

CookieRequestCultureProvider

Aplikasi produksi akan sering menyediakan mekanisme untuk mengatur budaya dengan budaya cookieASP.NET Core . MakeCookieValue Gunakan metode untuk membuat cookie.

mengembalikan CookieRequestCultureProviderDefaultCookieName nama default cookie yang digunakan untuk melacak informasi budaya pilihan pengguna. Nama defaultnya cookie adalah .AspNetCore.Culture.

Formatnya cookie adalah c=%LANGCODE%|uic=%LANGCODE%, di mana c adalah Culture dan uic adalah UICulture, misalnya:

c=en-UK|uic=en-US

Jika hanya salah satu info budaya atau budaya UI yang disediakan, budaya yang disediakan digunakan untuk info budaya dan budaya UI.

Header HTTP Terima Bahasa

Header Terima-Bahasa dapat diatur di sebagian besar browser dan awalnya dimaksudkan untuk menentukan bahasa pengguna. Pengaturan ini menunjukkan apa yang telah diatur browser untuk dikirim atau telah diwarisi dari sistem operasi yang mendasar. Header HTTP Accept-Language dari permintaan browser bukanlah cara yang tak terduga untuk mendeteksi bahasa pilihan pengguna (lihat Mengatur preferensi bahasa di browser). Aplikasi produksi harus menyertakan cara bagi pengguna untuk menyesuaikan pilihan budaya mereka.

Mengatur header HTTP Accept-Language di Edge

1. Cari Pengaturan bahasa pilihan.

2. Bahasa pilihan tercantum dalam kotak Bahasa pilihan.

3. Pilih Tambahkan bahasa untuk ditambahkan ke daftar.

4. Pilih Tindakan lainnya ... di samping bahasa untuk mengubah urutan preferensi.

Header HTTP Bahasa Konten

Header entitas Content-Language:

• Digunakan untuk menjelaskan bahasa yang ditujukan untuk audiens.
• Memungkinkan pengguna untuk membedakan sesuai dengan bahasa pilihan pengguna sendiri.

Header entitas digunakan dalam permintaan DAN respons HTTP.

Header Content-Language dapat ditambahkan dengan mengatur properti ApplyCurrentCultureToResponseHeaders.

Content-Language Menambahkan header:

• RequestLocalizationMiddleware Memungkinkan untuk mengatur Content-Language header dengan CurrentUICulture.
• Menghilangkan kebutuhan untuk mengatur header Content-Language respons secara eksplisit.

app.UseRequestLocalization(new RequestLocalizationOptions
{
    ApplyCurrentCultureToResponseHeaders = true
});

Menerapkan RouteDataRequest CultureProvider

Menetapkan RouteDataRequestCultureProvider budaya berdasarkan nilai culture nilai rute. Lihat Penyedia budaya url menggunakan middleware sebagai filter untuk informasi tentang:

• Menggunakan middleware sebagai fitur filter ASP.NET Core.
• Cara menggunakan RouteDataRequestCultureProvider untuk mengatur budaya aplikasi dari url.

Lihat Menerapkan RouteDataRequest CultureProvider secara global dengan middleware sebagai filter untuk informasi tentang cara menerapkan RouteDataRequestCultureProvider secara global.

Menggunakan penyedia kustom

Misalkan Anda ingin membiarkan pelanggan Anda menyimpan bahasa dan budaya mereka dalam database Anda. Anda dapat menulis penyedia untuk mencari nilai-nilai ini untuk pengguna. Kode berikut menunjukkan cara menambahkan penyedia kustom:

private const string enUSCulture = "en-US";

services.Configure<RequestLocalizationOptions>(options =>
{
    var supportedCultures = new[]
    {
        new CultureInfo(enUSCulture),
        new CultureInfo("fr")
    };

    options.DefaultRequestCulture = new RequestCulture(culture: enUSCulture, uiCulture: enUSCulture);
    options.SupportedCultures = supportedCultures;
    options.SupportedUICultures = supportedCultures;

    options.AddInitialRequestCultureProvider(new CustomRequestCultureProvider(async context =>
    {
        // My custom request culture logic
        return await Task.FromResult(new ProviderCultureResult("en"));
    }));
});

Gunakan RequestLocalizationOptions untuk menambahkan atau menghapus penyedia pelokalan.

Mengubah pesanan penyedia kultur permintaan

RequestLocalizationOptions memiliki tiga penyedia kultur permintaan default: QueryStringRequestCultureProvider, , CookieRequestCultureProviderdan AcceptLanguageHeaderRequestCultureProvider. Gunakan RequestLocalizationOptions.RequestCultureProviders properti untuk mengubah urutan penyedia ini seperti yang ditunjukkan pada hal berikut ini:

    app.UseRequestLocalization(options =>
    {
        var questStringCultureProvider = options.RequestCultureProviders[0];    
        options.RequestCultureProviders.RemoveAt(0);
        options.RequestCultureProviders.Insert(1, questStringCultureProvider);
    });

Dalam contoh sebelumnya, urutan QueryStringRequestCultureProvider dan CookieRequestCultureProvider dialihkan, sehingga RequestLocalizationMiddleware mencari budaya dari cookieyang pertama, lalu string kueri.

Seperti yang disebutkan sebelumnya, tambahkan penyedia kustom yang AddInitialRequestCultureProvider menetapkan pesanan ke 0, sehingga penyedia ini lebih diutamakan daripada yang lain.

Kultur penimpaan pengguna

Properti RequestLocalizationOptions.CultureInfoUseUserOverride memungkinkan aplikasi memutuskan apakah akan menggunakan pengaturan Windows non-default untuk CultureInfoDateTimeFormat properti dan NumberFormat atau tidak. Ini tidak berdampak pada Linux. Ini secara langsung sesuai dengan UseUserOverride.

    app.UseRequestLocalization(options =>
    {
        options.CultureInfoUseUserOverride = false;
    });

Mengatur budaya secara terprogram

Contoh proyek Localization.StarterWeb di GitHub ini berisi UI untuk mengatur Culture. File ini Views/Shared/_SelectLanguagePartial.cshtml memungkinkan Anda untuk memilih budaya dari daftar budaya yang didukung:

@using Microsoft.AspNetCore.Builder
@using Microsoft.AspNetCore.Http.Features
@using Microsoft.AspNetCore.Localization
@using Microsoft.AspNetCore.Mvc.Localization
@using Microsoft.Extensions.Options

@inject IViewLocalizer Localizer
@inject IOptions<RequestLocalizationOptions> LocOptions

@{
    var requestCulture = Context.Features.Get<IRequestCultureFeature>();
    var cultureItems = LocOptions.Value.SupportedUICultures
        .Select(c => new SelectListItem { Value = c.Name, Text = c.DisplayName })
        .ToList();
    var returnUrl = string.IsNullOrEmpty(Context.Request.Path) ? "~/" : $"~{Context.Request.Path.Value}";
}

<div title="@Localizer["Request culture provider:"] @requestCulture?.Provider?.GetType().Name">
    <form id="selectLanguage" asp-controller="Home" 
          asp-action="SetLanguage" asp-route-returnUrl="@returnUrl" 
          method="post" class="form-horizontal" role="form">
        <label asp-for="@requestCulture.RequestCulture.UICulture.Name">@Localizer["Language:"]</label> <select name="culture"
          onchange="this.form.submit();"
          asp-for="@requestCulture.RequestCulture.UICulture.Name" asp-items="cultureItems">
        </select>
    </form>
</div>

File Views/Shared/_SelectLanguagePartial.cshtml ditambahkan ke bagian footer file tata letak sehingga akan tersedia untuk semua tampilan:

<div class="container body-content" style="margin-top:60px">
    @RenderBody()
    <hr>
    <footer>
        <div class="row">
            <div class="col-md-6">
                <p>&copy; @System.DateTime.Now.Year - Localization</p>
            </div>
            <div class="col-md-6 text-right">
                @await Html.PartialAsync("_SelectLanguagePartial")
            </div>
        </div>
    </footer>
</div>

Metode ini SetLanguage menetapkan budaya cookie.

[HttpPost]
public IActionResult SetLanguage(string culture, string returnUrl)
{
    Response.Cookies.Append(
        CookieRequestCultureProvider.DefaultCookieName,
        CookieRequestCultureProvider.MakeCookieValue(new RequestCulture(culture)),
        new CookieOptions { Expires = DateTimeOffset.UtcNow.AddYears(1) }
    );

    return LocalRedirect(returnUrl);
}

Anda tidak dapat mencolokkan _SelectLanguagePartial.cshtml ke kode sampel untuk proyek ini. Proyek Localization.StarterWeb di GitHub memiliki kode untuk mengalirkan RequestLocalizationOptions ke Razor sebagian melalui kontainer Injeksi Dependensi.

Model mengikat data rute dan string kueri

Lihat Perilaku globalisasi data rute pengikatan model dan string kueri.

Langkah berikutnya

Melokalisasi aplikasi juga melibatkan tugas-tugas berikut:

• Buat konten aplikasi dapat dilokalkan.
• Menyediakan sumber daya yang dilokalkan untuk bahasa dan budaya yang didukung aplikasi

Sumber Daya Tambahan:

• Penyedia budaya url menggunakan middleware sebagai filter di ASP.NET Core
• Menerapkan RouteDataRequest CultureProvider secara global dengan middleware sebagai filter
• Globalisasi dan pelokalan di ASP.NET Core
• Membuat konten aplikasi ASP.NET Core dapat dilokalkan
• Menyediakan sumber daya yang dilokalkan untuk bahasa dan budaya dalam aplikasi ASP.NET Core
• Memecahkan masalah pelokalan ASP.NET Core
• Menggoralisasi dan melokalisasi aplikasi .NET
• Proyek Localization.StarterWeb yang digunakan dalam artikel.
• Sumber daya dalam File .resx
• Toolkit Aplikasi Multibahasa Microsoft
• Pelokalan & Generik