Menyediakan sumber daya yang dilokalkan untuk bahasa dan budaya dalam aplikasi ASP.NET Core

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

Salah satu tugas untuk melokalisasi aplikasi adalah menyediakan string yang dilokalkan dalam file sumber daya. Artikel ini berisi tentang bekerja dengan file sumber daya.

SupportedCultures dan SupportedUICultures

ASP.NET Core memiliki dua koleksi 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. Lihat StringComparer.CurrentCulture untuk informasi selengkapnya tentang bagaimana server mendapatkan budaya. SupportedUICultures menentukan string yang diterjemahkan (dari file .resx) yang dicari oleh ResourceManager. Hanya ResourceManager mencari string khusus budaya yang ditentukan oleh CurrentUICulture. Setiap utas di .NET memiliki CurrentCulture objek dan CurrentUICulture . ASP.NET Core memeriksa nilai-nilai ini saat merender fungsi yang bergantung pada budaya. Misalnya, jika budaya utas saat ini diatur ke "en-US" (Inggris, Amerika Serikat), DateTime.Now.ToLongDateString() menampilkan "Kamis, 18 Februari 2016", tetapi jika CurrentCulture diatur ke "es-ES" (Spanyol, Spanyol) outputnya adalah "jueves, 18 de febrero de 2016".

File sumber daya

CATATAN:Penampil dan Editor ResX menyediakan mekanisme alternatif untuk bekerja dengan file sumber daya menggunakan Visual Studio Code.

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, lalu pilih Tambahkan>Item Baru.

   

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

   

3. 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 Pengontrol.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, ConfigureServices metode mengatur ResourcesPath ke "Sumber Daya", sehingga jalur relatif proyek untuk file sumber daya Prancis pengontrol rumah adalah Sumber Daya/Pengontrol.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 Pengontrol.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
Sumber Daya/Pengontrol.HomeController.fr.resx	Titik
Resources/Controllers/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 , ResourcesPathfile .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 kode bahasa dan budaya. 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 adalah bagian dari nama file (misalnya, en-us, fr-ca, dan en-gb). Kode-kode ini ditempatkan antara nama file dan ekstensi file .resx , seperti dalam Welcome.es-MX.resx (Spanyol/Meksiko).

Langkah berikutnya

Melokalisasi aplikasi juga melibatkan tugas-tugas berikut:

• Buat konten aplikasi dapat dilokalkan.
• Menerapkan strategi untuk memilih bahasa/budaya untuk setiap permintaan

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
• Strategi untuk memilih bahasa dan budaya di aplikasi ASP.NET Core yang dilokalkan
• 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