Globalisasi dan pelokalan di ASP.NET Core

Artikel
11/06/2024

Catatan

Ini bukan versi terbaru dari artikel ini. Untuk rilis saat ini, lihat versi .NET 9 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 9 dari artikel ini.

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

Situs web multibahasa memungkinkan situs web untuk menjangkau audiens yang lebih luas. ASP.NET Core menyediakan layanan dan middleware untuk dilokalkan ke dalam berbagai bahasa dan budaya.

Untuk Blazor panduan pelokalan, yang menambahkan atau menggantikan panduan dalam artikel ini, lihat ASP.NET globalisasi dan pelokalan CoreBlazor.

Syarat

Globalisasi (G11N): Proses pembuatan aplikasi mendukung berbagai bahasa dan wilayah. Singkatan berasal dari huruf pertama dan terakhir dan jumlah huruf di antaranya.
Pelokalan (L10N): Proses penyesuaian aplikasi globalisasi untuk bahasa dan wilayah tertentu.
Internasionalisasi (I18N): Baik globalisasi maupun pelokalan.
Budaya: Bahasa dan, secara opsional, suatu wilayah.
Budaya netral: Budaya yang memiliki bahasa tertentu, tetapi bukan wilayah (misalnya "en", "es").
Budaya tertentu: Budaya yang memiliki bahasa dan wilayah tertentu (misalnya, "en-US", "en-GB", "es-CL").
Budaya induk: Budaya netral yang berisi budaya tertentu (misalnya, "en" adalah budaya induk "en-US" dan "en-GB").
Lokal: Lokal sama dengan budaya.

Kode bahasa dan negara/wilayah

Format RFC 4646 untuk nama budaya adalah <language code>-<country/region code>, di mana <language code> mengidentifikasi bahasa dan <country/region code> mengidentifikasi subkultur. Misalnya, es-CL untuk bahasa Spanyol (Chili), en-US untuk bahasa Inggris (Amerika Serikat), dan en-AU untuk bahasa Inggris (Australia). RFC 4646 adalah kombinasi dari kode kultur huruf kecil dua huruf ISO 639 yang terkait dengan bahasa dan kode subkultur huruf besar dua huruf ISO 3166 yang terkait dengan negara atau wilayah. Untuk informasi selengkapnya, lihat System.Globalization.CultureInfo .

Tugas untuk melokalisasi aplikasi

Globalisasi dan pelokalan aplikasi melibatkan tugas-tugas berikut:

Melihat atau mengunduh kode sampel (cara mengunduh)

Sumber Daya Tambahan:

Penyedia budaya url menggunakan middleware sebagai filter di ASP.NET Core
Menerapkan RouteDataRequest CultureProvider secara global dengan middleware sebagai filter
IStringLocalizer : Menggunakan ResourceManager dan ResourceReader untuk menyediakan sumber daya khusus budaya pada waktu proses. Antarmuka memiliki pengindeks dan IEnumerable untuk mengembalikan string yang dilokalkan.
IHtmlLocalizer: Untuk sumber daya yang berisi HTML.
Menampilkan dan DataAnnotations
Memecahkan masalah pelokalan ASP.NET Core
Menggoralisasi dan melokalisasi aplikasi .NET
Sumber daya dalam File .resx
Toolkit Aplikasi Multibahasa Microsoft
Pelokalan & Generik

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

Situs web multibahasa memungkinkan situs web untuk menjangkau audiens yang lebih luas. ASP.NET Core menyediakan layanan dan middleware untuk dilokalkan ke dalam berbagai bahasa dan budaya.

Syarat

Globalisasi (G11N): Proses pembuatan aplikasi mendukung berbagai bahasa dan wilayah. Singkatan berasal dari huruf pertama dan terakhir dan jumlah huruf di antaranya.
Pelokalan (L10N): Proses penyesuaian aplikasi globalisasi untuk bahasa dan wilayah tertentu.
Internasionalisasi (I18N): Baik globalisasi maupun pelokalan.
Budaya: Bahasa dan, secara opsional, suatu wilayah.
Budaya netral: Budaya yang memiliki bahasa tertentu, tetapi bukan wilayah (misalnya "en", "es").
Budaya tertentu: Budaya yang memiliki bahasa dan wilayah tertentu (misalnya, "en-US", "en-GB", "es-CL").
Budaya induk: Budaya netral yang berisi budaya tertentu (misalnya, "en" adalah budaya induk "en-US" dan "en-GB").
Lokal: Lokal sama dengan budaya.

Kode bahasa dan negara/wilayah

Tugas untuk melokalisasi aplikasi

Globalisasi dan pelokalan aplikasi melibatkan tugas-tugas berikut:

Melihat atau mengunduh kode sampel (cara mengunduh)

Sumber Daya Tambahan:

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

Situs web multibahasa memungkinkan situs untuk menjangkau audiens yang lebih luas. ASP.NET Core menyediakan layanan dan middleware untuk dilokalkan ke dalam berbagai bahasa dan budaya.

Internasionalisasi melibatkan System.Globalization dan Pelokalan. Globalisasi adalah proses merancang aplikasi yang mendukung budaya yang berbeda. Globalisasi menambahkan dukungan untuk input, tampilan, dan output dari sekumpulan skrip bahasa yang ditentukan yang terkait dengan area geografis tertentu.

Pelokalan adalah proses mengadaptasi aplikasi global, yang telah Anda proses untuk pelokalan, dengan budaya/lokal tertentu. Untuk informasi selengkapnya, lihat Istilah globalisasi dan pelokalan di dekat akhir dokumen ini.

Pelokalan aplikasi melibatkan hal berikut:

Membuat konten aplikasi dapat dilokalkan
Menyediakan sumber daya yang dilokalkan untuk bahasa dan budaya yang Anda dukung
Menerapkan strategi untuk memilih bahasa/budaya untuk setiap permintaan

Melihat atau mengunduh kode sampel (cara mengunduh)

Membuat konten aplikasi dapat dilokalkan

IStringLocalizer dan IStringLocalizer<T> dirancang untuk meningkatkan produktivitas saat mengembangkan aplikasi yang dilokalkan. IStringLocalizerResourceManager menggunakan dan ResourceReader untuk menyediakan sumber daya khusus budaya pada waktu proses. Antarmuka memiliki pengindeks dan IEnumerable untuk mengembalikan string yang dilokalkan. IStringLocalizer tidak memerlukan penyimpanan string bahasa default dalam file sumber daya. Anda dapat mengembangkan aplikasi yang ditargetkan untuk pelokalan dan tidak perlu membuat file sumber daya di awal pengembangan. Kode di bawah ini menunjukkan cara membungkus string "Tentang Judul" untuk pelokalan.

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

namespace Localization.Controllers
{
    [Route("api/[controller]")]
    public class AboutController : Controller
    {
        private readonly IStringLocalizer<AboutController> _localizer;

        public AboutController(IStringLocalizer<AboutController> localizer)
        {
            _localizer = localizer;
        }

        [HttpGet]
        public string Get()
        {
            return _localizer["About Title"];
        }
    }
}

Dalam kode sebelumnya, IStringLocalizer<T> implementasi berasal dari Injeksi Dependensi. Jika nilai "Tentang Judul" yang dilokalkan tidak ditemukan, maka kunci pengindeks dikembalikan, yaitu, string "Tentang Judul". Anda dapat meninggalkan string literal bahasa default di aplikasi dan membungkusnya di localizer, sehingga Anda dapat fokus pada pengembangan aplikasi. Anda mengembangkan aplikasi dengan bahasa default dan menyiapkannya untuk langkah pelokalan tanpa terlebih dahulu membuat file sumber daya default. Atau, Anda dapat menggunakan pendekatan tradisional dan menyediakan kunci untuk mengambil string bahasa default. Untuk banyak pengembang, alur kerja baru tidak memiliki file .resx bahasa default dan hanya membungkus literal string dapat mengurangi overhead pelokalan aplikasi. Pengembang lain akan lebih memilih alur kerja tradisional karena dapat membuatnya lebih mudah untuk bekerja dengan literal string yang lebih panjang dan membuatnya lebih mudah untuk memperbarui string yang dilokalkan.

IHtmlLocalizer<T> Gunakan implementasi untuk sumber daya yang berisi HTML. IHtmlLocalizer Html mengodekan argumen yang diformat dalam string sumber daya, tetapi tidak mengodekan HTML string sumber daya itu sendiri. Dalam sampel yang disorot di bawah ini, hanya nilai name parameter yang dikodekan HTML.

using System;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Localization;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Localization;

namespace Localization.Controllers
{
    public class BookController : Controller
    {
        private readonly IHtmlLocalizer<BookController> _localizer;

        public BookController(IHtmlLocalizer<BookController> localizer)
        {
            _localizer = localizer;
        }

        public IActionResult Hello(string name)
        {
            ViewData["Message"] = _localizer["<b>Hello</b><i> {0}</i>", name];

            return View();
        }

Catatan

Umumnya, hanya melokalisasi teks, bukan HTML.

Pada tingkat terendah, Anda bisa keluar IStringLocalizerFactory dari Injeksi Dependensi:

{
    public class TestController : Controller
    {
        private readonly IStringLocalizer _localizer;
        private readonly IStringLocalizer _localizer2;

        public TestController(IStringLocalizerFactory factory)
        {
            var type = typeof(SharedResource);
            var assemblyName = new AssemblyName(type.GetTypeInfo().Assembly.FullName);
            _localizer = factory.Create(type);
            _localizer2 = factory.Create("SharedResource", assemblyName.Name);
        }       

        public IActionResult About()
        {
            ViewData["Message"] = _localizer["Your application description page."] 
                + " loc 2: " + _localizer2["Your application description page."];

Kode di atas menunjukkan masing-masing dari dua metode pembuatan pabrik.

Anda dapat mempartisi string yang dilokalkan berdasarkan pengontrol, area, atau hanya memiliki satu kontainer. Di aplikasi sampel, kelas dummy bernama SharedResource digunakan untuk sumber daya bersama.

// Dummy class to group shared resources

namespace Localization
{
    public class SharedResource
    {
    }
}

Beberapa pengembang menggunakan Startup kelas untuk berisi string global atau bersama. Dalam sampel di bawah ini, InfoController dan SharedResource localizer digunakan:

public class InfoController : Controller
{
    private readonly IStringLocalizer<InfoController> _localizer;
    private readonly IStringLocalizer<SharedResource> _sharedLocalizer;

    public InfoController(IStringLocalizer<InfoController> localizer,
                   IStringLocalizer<SharedResource> sharedLocalizer)
    {
        _localizer = localizer;
        _sharedLocalizer = sharedLocalizer;
    }

    public string TestLoc()
    {
        string msg = "Shared resx: " + _sharedLocalizer["Hello!"] +
                     " Info resx " + _localizer["Hello!"];
        return msg;
    }

Lihat pelokalan

Layanan ini IViewLocalizer menyediakan string yang dilokalkan untuk tampilan. Kelas ViewLocalizer mengimplementasikan antarmuka ini dan menemukan lokasi sumber daya dari jalur file tampilan. Kode berikut menunjukkan cara menggunakan implementasi default dari IViewLocalizer:

@using Microsoft.AspNetCore.Mvc.Localization

@inject IViewLocalizer Localizer

@{
    ViewData["Title"] = Localizer["About"];
}
<h2>@ViewData["Title"].</h2>
<h3>@ViewData["Message"]</h3>

<p>@Localizer["Use this area to provide additional information."]</p>

Implementasi IViewLocalizer default menemukan file sumber daya berdasarkan nama file tampilan. Tidak ada opsi untuk menggunakan file sumber daya bersama global. ViewLocalizer mengimplementasikan localizer menggunakan IHtmlLocalizer, jadi Razor tidak mengodekan HTML string yang dilokalkan. Anda dapat membuat parameter string sumber daya dan IViewLocalizer akan mengodekan parameter HTML, tetapi bukan string sumber daya. Pertimbangkan markup berikut Razor :

@Localizer["<i>Hello</i> <b>{0}!</b>", UserManager.GetUserName(User)]

File sumber daya Prancis dapat berisi yang berikut ini:

Tombol	Nilai
`<i>Hello</i> <b>{0}!</b>`	`<i>Bonjour</i> <b>{0} !</b>`

Tampilan yang dirender akan berisi markup HTML dari file sumber daya.

Catatan

Umumnya, hanya melokalisasi teks, bukan HTML.

Untuk menggunakan file sumber daya bersama dalam tampilan, masukkan IHtmlLocalizer<T>:

@using Microsoft.AspNetCore.Mvc.Localization
@using Localization.Services

@inject IViewLocalizer Localizer
@inject IHtmlLocalizer<SharedResource> SharedLocalizer

@{
    ViewData["Title"] = Localizer["About"];
}
<h2>@ViewData["Title"].</h2>

<h1>@SharedLocalizer["Hello!"]</h1>

Pelokalan DataAnnotasi

Pesan kesalahan DataAnnotations dilokalkan dengan IStringLocalizer<T>. Menggunakan opsi ResourcesPath = "Resources", pesan kesalahan di RegisterViewModel dapat disimpan di salah satu jalur berikut:

Resources/ViewModels.Account.RegisterViewModel.fr.resx
Resources/ViewModels/Account/RegisterViewModel.fr.resx

public class RegisterViewModel
{
    [Required(ErrorMessage = "The Email field is required.")]
    [EmailAddress(ErrorMessage = "The Email field is not a valid email address.")]
    [Display(Name = "Email")]
    public string Email { get; set; }

    [Required(ErrorMessage = "The Password field is required.")]
    [StringLength(8, ErrorMessage = "The {0} must be at least {2} characters long.", MinimumLength = 6)]
    [DataType(DataType.Password)]
    [Display(Name = "Password")]
    public string Password { get; set; }

    [DataType(DataType.Password)]
    [Display(Name = "Confirm password")]
    [Compare("Password", ErrorMessage = "The password and confirmation password do not match.")]
    public string ConfirmPassword { get; set; }
}

Atribut non-validasi dilokalkan.

Menggunakan satu string sumber daya untuk beberapa kelas

Kode berikut menunjukkan cara menggunakan satu string sumber daya untuk atribut validasi dengan beberapa kelas:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc()
        .AddDataAnnotationsLocalization(options => {
            options.DataAnnotationLocalizerProvider = (type, factory) =>
                factory.Create(typeof(SharedResource));
        });
}

Dalam kode sebelumnya, SharedResource adalah kelas yang sesuai dengan resx tempat pesan validasi Anda disimpan. Dengan pendekatan ini, DataAnnotations hanya akan menggunakan SharedResource, daripada sumber daya untuk setiap kelas.

Menyediakan sumber daya yang dilokalkan untuk bahasa dan budaya yang Anda dukung

SupportedCultures dan SupportedUICultures

ASP.NET Core memungkinkan Anda menentukan dua nilai budaya, SupportedCultures dan SupportedUICultures. Objek CultureInfo untuk SupportedCultures menentukan hasil fungsi yang bergantung pada budaya, seperti tanggal, waktu, angka, dan pemformatan mata uang. SupportedCultures juga menentukan urutan pengurutan teks, konvensi casing, dan perbandingan string. Untuk informasi selengkapnya tentang bagaimana server mendapatkan budaya, lihat CultureInfo.CurrentCulture dan CultureInfo.CurrentUICulture. SupportedUICultures menentukan string yang diterjemahkan (dari .resx file) yang dicari oleh ResourceManager. Mencari ResourceManager string khusus budaya yang ditentukan oleh CurrentUICulture. Setiap utas di .NET memiliki CurrentCulture objek dan CurrentUICulture . Kerangka kerja memeriksa nilai-nilai ini saat merender fungsi yang bergantung pada budaya. Jika budaya utas saat ini diatur ke en-US (Inggris, Amerika Serikat), DateTime.Now.ToLongDateString() ditampilkan ; tetapi jika CurrentCulture diatur ke es-ES (Spanyol, Spanyol), outputnya adalah jueves, 18 de febrero de 2016.Thursday, February 18, 2016

File sumber daya

File sumber daya adalah mekanisme yang berguna untuk memisahkan string yang dapat dilokalkan dari kode. String yang diterjemahkan untuk bahasa non-default diisolasi dalam file sumber daya .resx . Misalnya, Anda mungkin ingin membuat file sumber daya Spanyol bernama Welcome.es.resx yang berisi string yang diterjemahkan. "es" adalah kode bahasa untuk bahasa Spanyol. Untuk membuat file sumber daya ini di Visual Studio:

Di Penjelajah Solusi, klik kanan pada folder yang akan berisi file> sumber daya Tambahkan>Item Baru.
Dalam kotak Cari templat yang diinstal, masukkan "sumber daya" dan beri nama file.
Masukkan nilai kunci (string asli) di kolom Nama dan string yang diterjemahkan di kolom Nilai .

Visual Studio memperlihatkan file Welcome.es.resx .

Penamaan file sumber daya

Sumber daya dinamai untuk nama jenis lengkap kelas mereka dikurangi nama rakitan. Misalnya, sumber daya Prancis dalam proyek yang assembly utamanya adalah LocalizationWebsite.Web.dll untuk kelas LocalizationWebsite.Web.Startup akan diberi nama Startup.fr.resx. Sumber daya untuk kelas LocalizationWebsite.Web.Controllers.HomeController akan diberi nama Controllers.HomeController.fr.resx. Jika namespace kelas yang ditargetkan tidak sama dengan nama rakitan, Anda akan memerlukan nama jenis lengkap. Misalnya, dalam proyek sampel, sumber daya untuk jenis ExtraNamespace.Tools tersebut akan diberi nama ExtraNamespace.Tools.fr.resx.

Dalam proyek sampel, metode mengatur ResourcesPath ke "Sumber Daya", sehingga jalur relatif proyek untuk home file sumber daya Prancis pengontrol adalah Resources/Controllers.HomeController.fr.resx.ConfigureServices Atau, Anda dapat menggunakan folder untuk mengatur file sumber daya. home Untuk pengontrol, jalurnya adalah Resources/Controllers/HomeController.fr.resx. Jika Anda tidak menggunakan opsi , ResourcesPath file .resx akan masuk ke direktori dasar proyek. File sumber daya untuk HomeController akan diberi nama Controllers.HomeController.fr.resx. Pilihan menggunakan konvensi penamaan titik atau jalur tergantung pada bagaimana Anda ingin mengatur file sumber daya Anda.

Nama sumber daya	Penamaan titik atau jalur
Resources/Controllers.HomeController.fr.resx	Titik
Sumber Daya/Pengontrol/HomeController.fr.resx	Jalur

File sumber daya yang menggunakan @inject IViewLocalizer dalam Razor tampilan mengikuti pola yang sama. File sumber daya untuk tampilan dapat diberi nama menggunakan penamaan titik atau penamaan jalur. Razor lihat file sumber daya yang menilik jalur file tampilan terkait. Dengan asumsi kami mengatur ResourcesPath ke "Sumber Daya", file sumber daya Prancis yang Views/Home/About.cshtml terkait dengan tampilan bisa menjadi salah satu dari yang berikut:

Sumber Daya/Tampilan/Home/About.fr.resx
Sumber Daya/Tampilan.Home. About.fr.resx

Jika Anda tidak menggunakan opsi , ResourcesPath file .resx untuk tampilan akan terletak di folder yang sama dengan tampilan.

RootNamespaceAttribute

Atribut RootNamespaceAttribute menyediakan namespace layanan akar rakitan ketika namespace layanan akar rakitan berbeda dari nama rakitan.

Peringatan

Ini dapat terjadi ketika nama proyek bukan pengidentifikasi .NET yang valid. Misalnya my-project-name.csproj , akan menggunakan namespace my_project_name layanan akar dan nama my-project-name rakitan yang mengarah ke kesalahan ini.

Jika namespace layanan akar rakitan berbeda dari nama rakitan:

Pelokalan tidak berfungsi secara default.
Pelokalan gagal karena cara sumber daya dicari dalam rakitan. RootNamespace adalah nilai build-time yang tidak tersedia untuk proses eksekusi.

RootNamespace Jika berbeda dari , sertakan AssemblyNameyang berikut ini di AssemblyInfo.cs (dengan nilai parameter diganti dengan nilai aktual):

using System.Reflection;
using Microsoft.Extensions.Localization;

[assembly: ResourceLocation("Resource Folder Name")]
[assembly: RootNamespace("App Root Namespace")]

Kode sebelumnya memungkinkan resolusi file resx yang berhasil.

Perilaku fallback budaya

Saat mencari sumber daya, pelokalan terlibat dalam "fallback budaya". Mulai dari budaya yang diminta, jika tidak ditemukan, ia kembali ke budaya induk budaya itu. Selain itu, properti ini CultureInfo.Parent mewakili budaya induk. Ini biasanya (tetapi tidak selalu) berarti menghapus penanda nasional dari ISO. Misalnya, dialek bahasa Spanyol yang diucapkan di Meksiko adalah "es-MX". Ini memiliki "es" induk —Bahasa Spanyol yang tidak spesifik untuk negara mana pun.

Bayangkan situs Anda menerima permintaan untuk sumber daya "Selamat Datang" menggunakan budaya "fr-CA". Sistem pelokalan mencari sumber daya berikut, secara berurutan, dan memilih kecocokan pertama:

Welcome.fr-CA.resx
Welcome.fr.resx
Welcome.resx (jika NeutralResourcesLanguage "fr-CA")

Sebagai contoh, jika Anda menghapus penanda budaya ".fr" dan Anda memiliki budaya yang diatur ke Bahasa Prancis, file sumber daya default dibaca dan string dilokalkan. Resource manager menunjuk sumber daya default atau fallback ketika tidak ada yang memenuhi budaya yang Anda minta. Jika Anda hanya ingin mengembalikan kunci saat kehilangan sumber daya untuk budaya yang diminta, Anda tidak boleh memiliki file sumber daya default.

Membuat file sumber daya dengan Visual Studio

Jika Anda membuat file sumber daya di Visual Studio tanpa budaya dalam nama file (misalnya, Welcome.resx), Visual Studio akan membuat kelas C# dengan properti untuk setiap string. Biasanya itu bukan yang Anda inginkan dengan ASP.NET Core. Anda biasanya tidak memiliki file sumber daya .resx default (file .resx tanpa nama budaya). Kami sarankan Anda membuat file .resx dengan nama budaya (misalnya Welcome.fr.resx). Saat Anda membuat file .resx dengan nama budaya, Visual Studio tidak akan menghasilkan file kelas.

Menambahkan budaya lain

Setiap kombinasi bahasa dan budaya (selain bahasa default) memerlukan file sumber daya yang unik. Anda membuat file sumber daya untuk budaya dan lokal yang berbeda dengan membuat file sumber daya baru di mana kode bahasa ISO adalah bagian dari nama file (misalnya, en-us, fr-ca, dan en-gb). Kode ISO ini ditempatkan antara nama file dan ekstensi file .resx , seperti dalam Welcome.es-MX.resx (Spanyol/Meksiko).

Menerapkan strategi untuk memilih bahasa/budaya untuk setiap permintaan

Mengonfigurasi pelokalan

Pelokalan dikonfigurasi dalam Startup.ConfigureServices metode :

services.AddLocalization(options => options.ResourcesPath = "Resources");

services.AddMvc()
    .AddViewLocalization(LanguageViewLocationExpanderFormat.Suffix)
    .AddDataAnnotationsLocalization();

AddLocalization menambahkan layanan pelokalan ke kontainer layanan. Kode di atas juga mengatur jalur sumber daya ke "Sumber Daya".
AddViewLocalization menambahkan dukungan untuk file tampilan yang dilokalkan. Dalam contoh ini, pelokalan tampilan didasarkan pada akhiran file tampilan. Misalnya "fr" dalam Index.fr.cshtml file.
AddDataAnnotationsLocalization menambahkan dukungan untuk pesan validasi yang dilokalkan DataAnnotations melalui IStringLocalizer abstraksi.

Middleware pelokalan

Budaya saat ini pada permintaan diatur dalam Middleware pelokalan. Middleware pelokalan diaktifkan dalam Startup.Configure metode . Middleware pelokalan harus dikonfigurasi sebelum middleware apa pun yang mungkin memeriksa budaya permintaan (misalnya, app.UseMvcWithDefaultRoute()). Middleware Pelokalan harus muncul setelah Middleware Perutean jika menggunakan RouteDataRequestCultureProvider. Untuk informasi selengkapnya tentang urutan middleware, lihat ASP.NET Core Middleware.

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

app.UseRequestLocalization(localizationOptions);

Jika Anda ingin melihat komentar kode yang diterjemahkan ke bahasa selain bahasa Inggris, beri tahu kami dalam masalah diskusi GitHub ini.

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 :

QueryStringRequestCultureProvider
CookieRequestCultureProvider
AcceptLanguageHeaderRequestCultureProvider

Daftar default berubah dari yang paling spesifik ke paling tidak spesifik. Nantinya dalam artikel ini kita 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 Anda hanya meneruskan salah satu dari dua (culture atau ui-culture), penyedia string kueri akan mengatur kedua nilai menggunakan nilai yang Anda lewati. 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 CookieRequestCultureProvider DefaultCookieName 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 Anda hanya menentukan salah satu info budaya dan budaya UI, budaya yang ditentukan akan 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 IE

Dari ikon gigi, ketuk Opsi Internet.
Ketuk Bahasa.
Ketuk Atur Preferensi Bahasa.
Ketuk Tambahkan bahasa.
Tambahkan bahasa.
Ketuk bahasa, lalu ketuk Pindah ke Atas.

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 properti [RequestLocalizationOptions.RequestCultureProviders]](xref:Microsoft.AspNetCore.Builder.RequestLocalizationOptions.RequestCultureProviders) untuk mengubah urutan penyedia ini seperti yang ditunjukkan di bawah 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 cookie terlebih dahulu, lalu mengkueri string.

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

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.

Istilah globalisasi dan pelokalan

Proses melokalisasi aplikasi Anda juga memerlukan pemahaman dasar tentang set karakter yang relevan yang umum digunakan dalam pengembangan perangkat lunak modern dan pemahaman tentang masalah yang terkait dengannya. Meskipun semua komputer menyimpan teks sebagai angka (kode), sistem yang berbeda menyimpan teks yang sama menggunakan angka yang berbeda. Proses pelokalan mengacu pada penerjemahan antarmuka pengguna aplikasi (UI) untuk budaya/lokal tertentu.

Pelokalan adalah proses perantara untuk memverifikasi bahwa aplikasi global siap untuk pelokalan.

Format RFC 4646 untuk nama budaya adalah <languagecode2>-<country/regioncode2>, di mana <languagecode2> adalah kode bahasa dan <country/regioncode2> merupakan kode subkultur. Misalnya, es-CL untuk bahasa Spanyol (Chili), en-US untuk bahasa Inggris (Amerika Serikat), dan en-AU untuk bahasa Inggris (Australia). RFC 4646 adalah kombinasi dari kode kultur huruf kecil dua huruf ISO 639 yang terkait dengan bahasa dan kode subkultur huruf besar dua huruf ISO 3166 yang terkait dengan negara atau wilayah. Untuk informasi selengkapnya, lihat System.Globalization.CultureInfo .

Internasionalisasi sering disingkat dengan "I18N". Singkatan mengambil huruf pertama dan terakhir dan jumlah huruf di antaranya, jadi 18 adalah singkatan dari jumlah huruf antara "I" pertama dan "N". Hal yang sama berlaku untuk Globalisasi (G11N), dan Pelokalan (L10N).

Istilah:

Globalisasi (G11N): Proses pembuatan aplikasi mendukung berbagai bahasa dan wilayah.
Pelokalan (L10N): Proses penyesuaian aplikasi untuk bahasa dan wilayah tertentu.
Internasionalisasi (I18N): Menjelaskan globalisasi dan pelokalan.
Budaya: Ini adalah bahasa dan, secara opsional, suatu wilayah.
Budaya netral: Budaya yang memiliki bahasa tertentu, tetapi bukan wilayah. (misalnya "en", "es")
Budaya tertentu: Budaya yang memiliki bahasa dan wilayah tertentu. (misalnya "en-US", "en-GB", "es-CL")
Budaya induk: Budaya netral yang mengandung budaya tertentu. (misalnya, "en" adalah budaya induk "en-US" dan "en-GB")
Lokal: Lokal sama dengan budaya.

Catatan

Anda mungkin tidak dapat memasukkan koma desimal di bidang desimal. Untuk mendukung validasi jQuery untuk lokal non-Bahasa Inggris yang menggunakan koma (",") untuk format tanggal desimal, dan non-Bahasa Inggris AS, Anda harus mengambil langkah-langkah untuk meng globalisasi aplikasi Anda. Lihat komentar GitHub 4076 ini untuk instruksi tentang menambahkan koma desimal.

Catatan

Sebelum ASP.NET aplikasi web Core 3.0, tulis satu log jenis LogLevel.Warning per permintaan jika budaya yang diminta tidak didukung. Pengelogan satu LogLevel.Warning per permintaan dapat membuat file log besar dengan informasi redundan. Perilaku ini telah diubah dalam ASP.NET 3.0. menulis RequestLocalizationMiddleware log jenis LogLevel.Debug, yang mengurangi ukuran log produksi.

Sumber Daya Tambahan:

Memecahkan masalah pelokalan ASP.NET Core
Proyek Localization.StarterWeb yang digunakan dalam artikel.
Menggoralisasi dan melokalisasi aplikasi .NET
Sumber daya dalam File .resx
Toolkit Aplikasi Multibahasa Microsoft
Pelokalan & Generik

Bagikan melalui

Globalisasi dan pelokalan di ASP.NET Core

Syarat

Kode bahasa dan negara/wilayah

Tugas untuk melokalisasi aplikasi

Sumber Daya Tambahan:

Syarat

Kode bahasa dan negara/wilayah

Tugas untuk melokalisasi aplikasi

Sumber Daya Tambahan:

Membuat konten aplikasi dapat dilokalkan

Lihat pelokalan

Pelokalan DataAnnotasi

Menggunakan satu string sumber daya untuk beberapa kelas

Menyediakan sumber daya yang dilokalkan untuk bahasa dan budaya yang Anda dukung

SupportedCultures dan SupportedUICultures

File sumber daya

Penamaan file sumber daya

RootNamespaceAttribute

Perilaku fallback budaya

Membuat file sumber daya dengan Visual Studio

Menambahkan budaya lain

Menerapkan strategi untuk memilih bahasa/budaya untuk setiap permintaan

Mengonfigurasi pelokalan

Middleware pelokalan

QueryStringRequestCultureProvider

CookieRequestCultureProvider

Header HTTP Terima Bahasa

Mengatur header HTTP Accept-Language di IE

Menggunakan penyedia kustom

Mengubah pesanan penyedia kultur permintaan

Mengatur budaya secara terprogram

Model mengikat data rute dan string kueri

Istilah globalisasi dan pelokalan

Sumber Daya Tambahan:

Sumber Daya Tambahan: