Globalisasi dan pelokalan di ASP.NET Core

Note

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

Warning

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 10 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 panduan Blazor pelokalan, yang menambahkan atau menggantikan panduan dalam artikel ini, lihat globalisasi dan pelokalan ASP.NET CoreBlazor.

Terms

  • 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 menyesuaikan aplikasi yang diglobalisasi 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

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.

Terms

  • 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 menyesuaikan aplikasi yang diglobalisasi 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

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 kesiapan untuk dilokalkan, dengan budaya atau lokal tertentu. Untuk informasi selengkapnya, lihat Istilah globalisasi dan pelokalan di bagian akhir dokumen ini.

Pelokalan aplikasi melibatkan hal berikut:

  1. Membuat konten aplikasi dapat dilokalkan
  2. Menyediakan sumber daya yang dilokalkan untuk bahasa dan budaya yang Anda dukung
  3. 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. IStringLocalizer menggunakan ResourceManager dan ResourceReader untuk menyediakan sumber daya budaya spesifik 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, implementasi IStringLocalizer<T> berasal dari Dependency Injection. 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 tanpa memiliki file .resx bahasa default dan hanya dengan membungkus literal string dapat mengurangi beban kerja 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 meng-encode argumen yang diformat dalam string sumber daya, tetapi tidak meng-encode 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();
        }

Note

Umumnya, hanya melokalisasi teks, bukan HTML.

Pada tingkat terendah, Anda dapat memanfaatkan 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 kelas Startup untuk menyimpan string global atau bersama-sama. 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 bawaan IViewLocalizer menemukan file sumber daya berdasarkan nama file dari 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:

Key Value
<i>Hello</i> <b>{0}!</b> <i>Bonjour</i> <b>{0} !</b>

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

Note

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>

Lokalisasi DataAnnotations

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 yang bukan untuk 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 menggunakan 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 mana yang diterjemahkan (dari file .resx) yang dicari oleh ResourceManager. String khusus budaya dalam ResourceManager yang dicari ditentukan oleh CurrentUICulture. Setiap utas di .NET memiliki objek CurrentCulture 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 Thursday, February 18, 2016 diatur ke CurrentCulture (Spanyol, Spanyol), outputnya adalah es-ES.jueves, 18 de febrero de 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:

  1. Di Penjelajah Solusi, klik kanan pada folder yang akan berisi file> sumber daya Tambahkan>Item Baru.

    Menu kontekstual berlapis: Di Penjelajah Solusi, menu kontekstual terbuka untuk Sumber Daya. Menu kontekstual kedua terbuka untuk Tambahkan memperlihatkan perintah Item Baru disorot.

  2. Dalam kotak Cari templat yang diinstal, masukkan "sumber daya" dan beri nama file.

    Dialog Tambahkan Item Baru

  3. Masukkan nilai kunci (string asli) di kolom Nama dan string yang diterjemahkan di kolom Nilai .

    File Welcome.es.resx (file sumber daya Selamat Datang untuk Spanyol) dengan kata Halo di kolom Nama dan kata Hola (Halo dalam bahasa Spanyol) di kolom Nilai

    Visual Studio memperlihatkan file Welcome.es.resx .

    Penjelajah Solusi memperlihatkan file sumber daya Selamat Datang Spanyol (es)

Penamaan file sumber daya

Sumber daya dinamai berdasarkan nama tipe lengkap dari kelas mereka, dengan mengabaikan nama assembly. 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 tipe lengkap. Misalnya, dalam proyek sampel, sumber daya untuk jenis ExtraNamespace.Tools tersebut akan diberi nama ExtraNamespace.Tools.fr.resx.

Dalam proyek sampel, metode ConfigureServices mengatur ResourcesPath ke "Sumber Daya", sehingga jalur relatif proyek untuk file sumber daya Prancis pengontrol rumah adalah Resources/Controllers.HomeController.fr.resx. Atau, Anda dapat menggunakan folder untuk mengatur file sumber daya. Untuk pengontrol rumah, jalurnya adalah Resources/Controllers/HomeController.fr.resx. Jika Anda tidak menggunakan opsi , ResourcesPathfile .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 Dot
Resources/Controllers/HomeController.fr.resx Path

File sumber daya yang menggunakan @inject IViewLocalizer dalam Razor antarmuka mengikuti pola yang sama. File sumber daya untuk tampilan dapat diberi nama menggunakan penamaan titik atau penamaan jalur. Razor file sumber daya tampilan meniru jalur dari file tampilan terkait. Jika kita menetapkan ResourcesPath ke "Sumber Daya", file sumber daya bahasa Prancis yang terkait dengan tampilan Views/Home/About.cshtml bisa menjadi salah satu dari berikut ini:

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

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

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

RootNamespaceAttribute

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

Warning

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

Jika namespace akar rakitan berbeda dengan nama rakitan:

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

Jika RootNamespace berbeda dari AssemblyName, sertakan yang 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 jatuh kembali budaya

Proses pelokalan melakukan "penggunaan kembali budaya" saat mencari sumber daya. Dimulai dari kebudayaan yang diminta, jika tidak ditemukan, ia akan kembali ke kebudayaan induk dari kebudayaan tersebut. Sebagai catatan tambahan, properti 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 induk "es"—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 metode Startup.ConfigureServices

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 lokalisasi

Budaya saat ini pada permintaan diatur dalam Middleware pelokalan. Middleware pelokalan diaktifkan dalam metode Startup.Configure. Middleware pelokalan harus dikonfigurasi sebelum middleware apa pun yang mungkin memeriksa kultur 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);

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 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 pendekatan header Accept-Language, menambahkan string kueri ke URL berguna untuk debugging dan pengujian kode. Secara default, QueryStringRequestCultureProvider terdaftar sebagai penyedia pelokalan pertama dalam RequestCultureProvider daftar. Anda meneruskan parameter "kueri string" culture 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 teruskan. Misalnya, mengatur hanya kebudayaan sistem akan mengatur Culture dan UICulture:

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

CookieRequestCultureProvider

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

CookieRequestCultureProvider DefaultCookieName mengembalikan 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 Accept-Language dapat diatur di sebagian besar browser dan awalnya dimaksudkan untuk menentukan bahasa pengguna. Pengaturan ini menunjukkan apa yang telah diatur browser untuk mengirim atau telah diwarisi dari sistem operasi dasar. Permintaan HTTP header Accept-Language dari browser bukanlah cara yang tidak selalu dapat diandalkan 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

  1. Dari ikon roda gigi, ketuk Opsi Internet.

  2. Ketuk Bahasa.

    Opsi Internet

  3. Ketuk Atur Preferensi Bahasa.

  4. Ketuk Tambahkan bahasa.

  5. Tambahkan bahasa.

  6. 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 membuat penyedia untuk mencari nilai-nilai ini bagi 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.

Permintaan perubahan urutan penyedia kultur

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 melalui AddInitialRequestCultureProvider yang menetapkan urutan menjadi 0, sehingga penyedia ini lebih diutamakan daripada yang lainnya.

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 SetLanguage menetapkan kultur 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 memasukkan RequestLocalizationOptions ke dalam Razor partial melalui wadah Injeksi Dependensi .

Pengikatan Model pada data rute dan string kueri

Lihat Perilaku globalisasi pengikatan model untuk data rute dan string kueri.

Istilah-istilah globalisasi dan lokalisasi

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).

Terms:

  • 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 lokalisasi.
  • 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.

Note

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

Note

Sebelum aplikasi web ASP.NET Core 3.0, menulis satu log berjenis LogLevel.Warning untuk setiap permintaan jika kebudayaan yang diminta tidak didukung. Pengelogan satu LogLevel.Warning per permintaan dapat membuat file log besar dengan informasi redundan. Perilaku ini telah diubah di ASP.NET Core 3.0. Elemen RequestLocalizationMiddleware menulis log jenis LogLevel.Debug, dengan demikian mengurangi ukuran log produksi.

Sumber daya tambahan

  • Last updated on