Melokalisasi string di UI Anda dan manifes paket aplikasi

Untuk informasi selengkapnya tentang proposisi nilai pelokalan aplikasi SDK Aplikasi Windows Anda, lihat Globalisasi dan pelokalan.

Jika Anda ingin aplikasi mendukung bahasa tampilan yang berbeda, dan Anda memiliki literal string dalam kode atau markup XAML atau manifes paket aplikasi, maka pindahkan string tersebut ke dalam File Sumber Daya (.resw). Anda kemudian dapat membuat salinan yang diterjemahkan dari File Sumber Daya tersebut untuk setiap bahasa yang didukung aplikasi Anda.

Literal string yang dikodekan secara permanen dapat muncul dalam kode imperatif atau dalam markup XAML, misalnya sebagai properti Teks dari TextBlock. File tersebut juga dapat muncul di file sumber manifes paket aplikasi Anda ( Package.appxmanifest file ), misalnya sebagai nilai untuk Nama tampilan pada tab Aplikasi dari Visual Studio Manifest Designer. Pindahkan string ini ke File Sumber Daya (.resw), dan ganti literal string yang dikodekan secara permanen di aplikasi Anda dan dalam manifes Anda dengan referensi ke pengidentifikasi sumber daya.

Tidak seperti sumber daya gambar, di mana hanya satu sumber daya gambar yang terkandung dalam file sumber daya gambar, beberapa sumber daya string terkandung dalam file sumber daya string. File sumber daya string adalah File Sumber Daya (.resw), dan Anda biasanya membuat file sumber daya semacam ini di folder \Strings di proyek Anda. Untuk latar belakang tentang cara menggunakan kualifikasi dalam nama File Sumber Daya Anda (.resw), lihat Menyesuaikan sumber daya Anda untuk bahasa, skala, dan kualifikasi lainnya.

Menyimpan string dalam file sumber daya

1. Atur bahasa default aplikasi Anda.

   1. Dengan solusi Anda terbuka di Visual Studio, buka Package.appxmanifest.
   2. Pada tab Aplikasi, konfirmasikan bahwa bahasa Default diatur dengan tepat (misalnya, "en" atau "en-US"). Langkah-langkah yang tersisa akan mengasumsikan bahwa Anda telah mengatur bahasa default ke "en-US".

   Catatan

   Minimal, Anda perlu menyediakan sumber daya string yang dilokalkan untuk bahasa default ini. Itu adalah sumber daya yang akan dimuat jika tidak ada kecocokan yang lebih baik yang dapat ditemukan untuk bahasa pilihan pengguna atau pengaturan bahasa tampilan.

2. Buat File Sumber Daya (.resw) untuk bahasa default.

   1. Di bawah simpul proyek Anda, buat folder baru dan beri nama Strings.
   2. Di bawah Strings, buat sub-folder baru dan beri nama en-US.
   3. Di bawah en-US, buat File Sumber Daya baru (.resw) (di bawah jenis file WinUI dalam dialog Tambahkan Item Baru) dan konfirmasikan bahwa file tersebut bernama Resources.resw.

   Catatan

   Jika Anda memiliki .NET Resources Files (.resx) yang ingin Anda porting, lihat Porting XAML dan UI.

3. Buka Resources.resw dan tambahkan sumber daya string ini.

   Strings/en-US/Resources.resw

   

   Dalam contoh ini, "Salam" adalah pengidentifikasi sumber daya string yang dapat Anda rujuk dari markup Anda, seperti yang akan kami tampilkan. Untuk pengidentifikasi "Salam", nilai string disediakan untuk properti Teks, dan nilai string disediakan untuk properti Lebar. "Greeting.Text" adalah contoh pengidentifikasi properti karena sesuai dengan properti elemen UI. Anda juga dapat, misalnya, menambahkan "Greeting.Foreground" di kolom Nama, dan mengatur Nilainya menjadi "Merah". Pengidentifikasi "Perpisahan" adalah pengidentifikasi sumber daya string sederhana; tidak memiliki sub-properti dan dapat dimuat dari kode imperatif, seperti yang akan kita tunjukkan. Kolom Komentar adalah tempat yang baik untuk memberikan instruksi khusus kepada penerjemah.

   Dalam contoh ini, karena kami memiliki entri pengidentifikasi sumber daya string sederhana bernama "Farewell", kami juga tidak dapat memiliki pengidentifikasi properti berdasarkan pengidentifikasi yang sama. Jadi, menambahkan "Farewell.Text" akan menyebabkan kesalahan Entri Duplikat saat membangun Resources.resw.

   Pengidentifikasi sumber daya tidak membedakan huruf besar/kecil, dan harus unik per file sumber daya. Pastikan untuk menggunakan pengidentifikasi sumber daya yang bermakna untuk memberikan konteks tambahan bagi penerjemah. Dan jangan ubah pengidentifikasi sumber daya setelah sumber daya string dikirim untuk diterjemahkan. Tim pelokalan menggunakan pengidentifikasi sumber daya untuk melacak penambahan, penghapusan, dan pembaruan dalam sumber daya. Perubahan pengidentifikasi sumber daya—yang juga dikenal sebagai "pergeseran pengidentifikasi sumber daya"—mengharuskan string diterjemahkan ulang, karena akan muncul seolah-olah string dihapus dan yang lain ditambahkan.

Merujuk pada pengidentifikasi sumber daya string dari XAML

Anda menggunakan direktif x:Uid untuk mengaitkan kontrol atau elemen lain dalam markup Anda dengan pengidentifikasi sumber daya string.

<TextBlock x:Uid="Greeting"/>

Pada run-time, \Strings\en-US\Resources.resw dimuat (karena saat ini itulah satu-satunya File Sumber Daya dalam proyek). Direktif x:Uid pada TextBlock menyebabkan pencarian terjadi, untuk menemukan pengidentifikasi properti di dalam Resources.resw yang berisi pengidentifikasi sumber daya string "Salam". Pengidentifikasi properti "Greeting.Text" dan "Greeting.Width" ditemukan dan nilainya diterapkan ke TextBlock, mengganti nilai apa pun yang diatur secara lokal dalam markup. Nilai "Greeting.Foreground" juga akan diterapkan, jika Anda menambahkannya. Tetapi hanya pengidentifikasi properti yang digunakan untuk mengatur properti pada elemen markup XAML, sehingga pengaturan x:Uid ke "Perpisahan" pada TextBlock ini tidak akan berpengaruh. Resources.resw memang berisi pengidentifikasi sumber daya string "Perpisahan", tetapi tidak berisi pengidentifikasi properti untuk itu.

Saat menetapkan pengidentifikasi sumber daya string ke elemen XAML, pastikan bahwa semua pengidentifikasi properti untuk pengidentifikasi tersebut sesuai untuk elemen XAML. Misalnya, jika Anda mengatur x:Uid="Greeting" pada TextBlock , maka "Greeting.Text" akan diselesaikan karena jenis TextBlock memiliki properti Teks. Tetapi jika Anda mengatur x:Uid="Greeting" pada Tombol maka "Greeting.Text" akan menyebabkan kesalahan run-time karena jenis Tombol tidak memiliki properti Teks. Salah satu solusi untuk kasus tersebut adalah menulis pengidentifikasi properti bernama "ButtonGreeting.Content", dan menetapkan x:Uid="ButtonGreeting" pada Tombol.

Alih-alih mengatur Lebar dari File Sumber Daya, Anda mungkin ingin agar kontrol dapat menyesuaikan ukuran secara dinamis terhadap konten.

Catatan

Untuk properti terkait, Anda memerlukan sintaks khusus pada kolom Nama dalam file .resw. Misalnya, untuk menetapkan nilai untuk properti terlampir AutomationProperties.Name untuk pengidentifikasi "Salam", inilah yang akan Anda masukkan di kolom Nama .

Greeting.[using:Microsoft.UI.Xaml.Automation]AutomationProperties.Name

Rujuk pengidentifikasi sumber daya string dari kode

Anda dapat secara eksplisit memuat sumber daya string berdasarkan pengidentifikasi sumber daya string sederhana.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader();
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("Farewell");

Anda dapat menggunakan kode yang sama ini dari dalam proyek Pustaka Kelas. Saat runtime, sumber daya dari aplikasi yang menjadi host pustaka dimuat. Kami menyarankan agar pustaka memuat sumber daya dari aplikasi yang menghostingnya, karena aplikasi kemungkinan memiliki tingkat pelokalan yang lebih besar. Jika pustaka memang perlu menyediakan sumber daya, maka itu harus memberi aplikasi hostingnya opsi untuk mengganti sumber daya tersebut sebagai input.

Jika nama sumber daya disegmentasi (berisi karakter "."), ganti titik dengan karakter garis miring ("/") dalam nama sumber daya. Pengidentifikasi properti, misalnya, berisi titik-titik; jadi Anda harus melakukan penggantian ini untuk memuat salah satu dari mereka dari kode.

this.myXAMLTextBlockElement.Text = resourceLoader.GetString("Fare/Well"); // <data name="Fare.Well" ...> ...

Jika ragu, Anda dapat menggunakan MakePri.exe untuk mengekstrak file PRI aplikasi Anda. Setiap sumber daya uri ditampilkan dalam file yang di-dump.

<ResourceMapSubtree name="Fare"><NamedResource name="Well" uri="ms-resource://<GUID>/Resources/Fare/Well">...

Lihat pengidentifikasi sumber daya string dari manifes paket aplikasi Anda

1. Buka file sumber manifes paket aplikasi Anda (file Package.appxmanifest), yang secara default Display name aplikasi Anda dinyatakan sebagai string literal.

   

2. Untuk membuat versi string ini yang dapat dilokalkan, buka Resources.resw dan tambahkan sumber daya string baru dengan nama "AppDisplayName" dan nilai "Adventure Works Cycles".

3. Ganti string Nama Tampilan literal dengan referensi ke pengidentifikasi sumber daya string yang baru saja Anda buat ("AppDisplayName"). Anda menggunakan ms-resource skema URI (Pengidentifikasi Sumber Daya Seragam) untuk melakukan ini.

   

4. Ulangi proses ini untuk setiap string dalam manifes yang ingin Anda lokalkan. Misalnya, Nama pendek aplikasi Anda (yang dapat Anda konfigurasi untuk muncul di petak aplikasi Anda pada menu Mulai). Untuk daftar semua item dalam manifes paket aplikasi yang dapat Anda lokalkan, lihat Item manifes yang dapat dilokalkan.

Melokalisasi sumber daya string

1. Buat salinan File Sumber Daya Anda (.resw) untuk bahasa lain.

   1. Di bagian "String", buat sub-folder baru dan beri nama "de-DE" untuk Deutsch (Deutschland).

   Catatan

   Untuk nama folder, Anda dapat menggunakan tag bahasa BCP-47 apa pun. Lihat Menyesuaikan sumber daya Anda untuk bahasa, skala, dan kualifikasi lainnya untuk detail tentang kualifikasi bahasa dan daftar tag bahasa umum. 2. Buat salinan Strings/en-US/Resources.resw dalam Strings/de-DE folder.

2. Terjemahkan string.

   1. Buka Strings/de-DE/Resources.resw dan terjemahkan nilai di kolom Nilai. Anda tidak perlu menerjemahkan komentar.

   Strings/de-DE/Resources.resw

   

Jika mau, Anda dapat mengulangi langkah 1 dan 2 untuk bahasa lebih lanjut.

Strings/fr-FR/Resources.resw

Menguji aplikasi Anda

Uji aplikasi untuk bahasa tampilan default Anda. Anda kemudian dapat mengubah bahasa tampilan di Pengaturan>Waktu & Wilayah Bahasa>> dan menguji ulang aplikasi Anda. Lihat string di antarmuka pengguna (UI) Anda dan juga di shell (misalnya, bilah judul Anda—yang merupakan Nama Tampilan Anda—dan Nama Pendek pada tile Anda).

Catatan

Jika nama folder dapat ditemukan yang cocok dengan pengaturan bahasa tampilan, maka File Sumber Daya di dalam folder tersebut dimuat. Jika tidak, mekanisme cadangan terjadi, diakhiri dengan penggunaan sumber daya untuk bahasa bawaan aplikasi Anda.

Memecah string ke dalam beberapa Berkas Sumber Daya

Anda dapat menyimpan semua string Anda dalam satu File Sumber Daya (resw), atau Anda dapat memperhitungkannya di beberapa File Sumber Daya. Misalnya, Anda mungkin ingin menyimpan pesan kesalahan dalam satu File Sumber Daya, string manifes paket aplikasi Anda di string lain, dan string UI Anda di urutan ketiga. Inilah yang akan menjadi struktur folder Anda dalam kasus tersebut.

Untuk mencakup referensi pengidentifikasi sumber daya string ke file tertentu, Anda cukup menambahkan /<resources-file-name>/ sebelum pengidentifikasi. Contoh markup di bawah ini mengasumsikan bahwa ErrorMessages.resw berisi sumber daya yang namanya adalah "PasswordTooWeak.Text" dan yang nilainya menjelaskan kesalahan.

<TextBlock x:Uid="/ErrorMessages/PasswordTooWeak"/>

Anda hanya perlu menambahkan /<resources-file-name>/ sebelum pengidentifikasi sumber daya string untuk file sumber daya yang lainResources.resw. Itu karena "Resources.resw" adalah nama file default, jadi itulah yang diasumsikan jika Anda menghilangkan nama file (seperti yang kami lakukan dalam contoh sebelumnya dalam topik ini).

Contoh kode di bawah ini mengasumsikan bahwa ErrorMessages.resw berisi sumber daya yang namanya adalah "MismatchedPasswords" dan yang nilainya menjelaskan kesalahan.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader(
    Microsoft.Windows.ApplicationModel.Resources.ResourceLoader.GetDefaultResourceFilePath(),
    "ErrorMessages");
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("MismatchedPasswords");

Catatan

Konstruktor ResourceLoader(String) dengan satu parameter menerima jalur file .pri, bukan nama peta sumber daya. Untuk memuat subpohon sumber daya bernama (misalnya, dari file .resw yang terpisah) menggunakan .pri bawaan, gunakan konstruktor dua parameter: ResourceLoader(ResourceLoader.GetDefaultResourceFilePath(), "YourResourceMap").

Jika Anda memindahkan sumber daya "AppDisplayName" Anda keluar dari Resources.resw dan masuk ke ManifestResources.resw, maka dalam manifes paket aplikasi Anda, Anda akan mengubah ms-resource:AppDisplayName menjadi ms-resource:/ManifestResources/AppDisplayName.

Jika nama file sumber daya tersegmentasi (berisi karakter "."), maka biarkan titik-titik dalam nama saat Anda mereferensikannya. Jangan ganti titik dengan karakter garis miring ("/"), seperti yang Anda lakukan untuk nama sumber daya.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader(
    Microsoft.Windows.ApplicationModel.Resources.ResourceLoader.GetDefaultResourceFilePath(),
    "Err.Msgs");

Jika ragu, Anda dapat menggunakan MakePri.exe untuk mengekstrak file PRI aplikasi Anda. Setiap sumber daya uri ditampilkan dalam file yang di-dump.

<ResourceMapSubtree name="Err.Msgs"><NamedResource name="MismatchedPasswords" uri="ms-resource://<GUID>/Err.Msgs/MismatchedPasswords">...

Memuat string untuk bahasa tertentu atau konteks lainnya

ResourceContext default (yang diperoleh ketika membuat ResourceLoader) berisi nilai pembeda untuk setiap nama pembeda, yang mewakili konteks runtime bawaan (dengan kata lain, pengaturan pengguna dan mesin saat ini). Berkas Sumber Daya (.resw) dicocokkan—berdasarkan kualifikasi pada nama file—terhadap nilai kualifikasi dalam konteks runtime tersebut.

Tetapi mungkin ada kalanya Anda ingin aplikasi Anda menggantikan pengaturan sistem dan menentukan secara eksplisit bahasa, skala, atau nilai kualifikasi lainnya yang digunakan saat mencari File Sumber Daya yang cocok untuk dimuat. Misalnya, Anda mungkin ingin pengguna Anda dapat memilih bahasa alternatif untuk tipsalat atau pesan kesalahan.

Anda dapat melakukannya dengan membuat ResourceContext baru, mengganti nilainya, lalu menggunakan objek konteks tersebut dalam pencarian string Anda. Untuk contoh serupa menggunakan sumber daya gambar, lihat Memuat gambar untuk bahasa tertentu atau konteks lainnya.

var resourceManager = new Microsoft.Windows.ApplicationModel.Resources.ResourceManager();
var resourceContext = resourceManager.CreateResourceContext();
resourceContext.QualifierValues["Language"] = "de-DE";
var resourceMap = resourceManager.MainResourceMap.GetSubtree("Resources");
this.myXAMLTextBlockElement.Text = resourceMap.GetValue("Farewell", resourceContext).ValueAsString;

Menggunakan QualifierValues seperti dalam contoh kode di atas berfungsi untuk kualifikasi apa pun. Untuk kasus khusus Bahasa, Anda dapat melakukan ini sebagai gantinya.

resourceContext.Languages = new string[] { "de-DE" };

Memuat string dari Pustaka Kelas

Sumber daya string dari Class Library yang direferensikan biasanya ditambahkan ke subfolder paket yang menyertakannya selama proses build. Pengidentifikasi sumber daya dari string tersebut biasanya mengambil formulir LibraryName/ResourcesFileName/ResourceIdentifier.

Pustaka bisa mendapatkan ResourceLoader untuk sumber dayanya sendiri. Misalnya, kode berikut menggambarkan bagaimana pustaka atau aplikasi yang mereferensikannya bisa mendapatkan ResourceLoader untuk sumber daya string pustaka.

var resourceLoader = new Microsoft.Windows.ApplicationModel.Resources.ResourceLoader(
    Microsoft.Windows.ApplicationModel.Resources.ResourceLoader.GetDefaultResourceFilePath(),
    "ContosoControl/Resources");
this.myXAMLTextBlockElement.Text = resourceLoader.GetString("exampleResourceName");

Jika Anda ragu tentang jalur tersebut, Anda dapat menentukan opsi baris perintah untuk MakePri.exe untuk mengeluarkan file PRI dari komponen atau pustaka Anda. Setiap sumber daya uri ditampilkan dalam file yang di-dump.

<NamedResource name="exampleResourceName" uri="ms-resource://Contoso.Control/Contoso.Control/ReswFileName/exampleResourceName">...

Memuat string dari paket lain

Sumber daya dari sebuah paket aplikasi dikelola dan diakses melalui ResourceMap tingkat atas paket itu sendiri yang dapat diakses melalui ResourceManager. Dalam setiap paket, berbagai komponen dapat memiliki ResourceMap subtrees mereka sendiri, yang dapat Anda akses melalui ResourceMap.GetSubtree.

Paket kerangka kerja dapat mengakses sumber dayanya sendiri dengan URI pengidentifikasi sumber daya absolut. Lihat juga skema URI dalam dokumentasi UWP untuk informasi selengkapnya.

Memuat string dalam aplikasi yang tidak dikemas

Pada Windows Versi 1903 (Pembaruan Mei 2019), aplikasi yang tidak dipaket juga dapat memanfaatkan Sistem Manajemen Sumber Daya.

Cukup buat kontrol/pustaka kontrol pengguna SDK Aplikasi Windows Anda dan simpan string apa pun dalam file sumber daya. Anda kemudian dapat merujuk ke pengidentifikasi sumber daya string dari XAML, merujuk ke pengidentifikasi sumber daya string dari kode, atau memuat string dari Class Library.

Untuk menggunakan sumber daya dalam aplikasi yang tidak dikemas, Anda harus melakukan beberapa hal:

1. Gunakan konstruktor ResourceManager yang kelebihan beban untuk meneruskan nama file file file .pri aplikasi Anda saat menyelesaikan sumber daya dari kode karena tidak ada tampilan default dalam skenario yang tidak dikemas.
2. Gunakan MakePri.exe untuk membuat file resources.pri aplikasi Anda secara manual.
   • Jalankan makepri new /pr <PROJECTROOT> /cf <PRICONFIG> /of resources.pri
   • <PRICONFIG> harus menghilangkan bagian "<pengemasan>" sehingga semua sumber daya dibundel dalam satu file resources.pri. Jika menggunakan file konfigurasi default MakePri.exe yang dibuat oleh createconfig, Anda perlu menghapus bagian "<packaging>" secara manual setelah dibuat.
   • <PRICONFIG> harus berisi semua pengindeks relevan yang diperlukan untuk menggabungkan semua sumber daya dalam proyek Anda ke dalam satu file resources.pri. File konfigurasi MakePri.exe default yang dibuat oleh createconfig mencakup semua pengindeks."
   • Jika Anda tidak menggunakan konfigurasi default, pastikan pengindeks PRI diaktifkan (tinjau konfigurasi default untuk cara melakukan ini) untuk menggabungkan PRI yang ditemukan dari referensi proyek, referensi NuGet, dan sebagainya, yang terletak di dalam akar proyek.

     Catatan

     Dengan menghilangkan /IndexName, dan dalam proyek yang tidak memiliki manifes aplikasi, namespace IndexName/root file PRI secara otomatis diatur ke Aplikasi, yang dimengerti oleh runtime untuk aplikasi yang tidak dikemas (ini menghapus dependensi keras sebelumnya pada ID paket). Saat menentukan URI sumber daya, referensi ms-resource:/// yang menghilangkan namespace layanan akar menyimpulkan Aplikasi sebagai namespace layanan akar untuk aplikasi yang tidak dikemas (atau Anda dapat menentukan Aplikasi secara eksplisit seperti dalam ms-resource://Application/).

3. Salin file PRI ke direktori output build dari .exe
4. Jalankan .exe

   Catatan

   Sistem Manajemen Sumber Daya menggunakan bahasa tampilan sistem daripada daftar bahasa pilihan pengguna saat menyelesaikan sumber daya berdasarkan bahasa dalam aplikasi yang tidak dikemas. Daftar bahasa pilihan pengguna hanya digunakan untuk aplikasi paket SDK Aplikasi Windows.

Penting

Anda harus membangun ulang file PRI secara manual setiap kali sumber daya dimodifikasi. Sebaiknya gunakan skrip pasca-build yang menangani perintah MakePri.exe dan menyalin output resources.pri ke direktori .exe.

Melokalisasi aplikasi paket WinUI 3

Untuk memastikan pelokalan yang tepat dari aplikasi desktop WinUI 3 yang dikemas, deklarasikan setiap bahasa yang didukung dalam file package.appxmanifest proyek Anda. Saat Anda membuat proyek, bahasa yang ditentukan ditambahkan ke manifes aplikasi yang dihasilkan (AppxManifest.xml) dan sumber daya yang sesuai digunakan.

Catatan

Aplikasi WinUI yang tidak dikemas (lihat Membuat proyek WinUI pertama Anda) tidak berisi package.appxmanifest file, jadi tidak ada tindakan lebih lanjut yang diperlukan setelah menambahkan sumber daya yang sesuai ke proyek.

1. Buka .wapprojpackage.appxmanifest di editor teks dan temukan bagian berikut:

   <Resources>
       <Resource Language="x-generate"/>
   </Resources>
   

2. Gantilah elemen <Resource Language="x-generate"> dengan elemen <Resource /> untuk setiap bahasa yang Anda dukung. Misalnya, markup berikut menentukan bahwa sumber daya yang dilokalkan "en-US" dan "es-ES" tersedia:

   <Resources>
       <Resource Language="en-US"/>
       <Resource Language="es-ES"/>
   </Resources>
   

API penting

• ApplicationModel.Resources.ResourceLoader

Lihat juga

• Membuat aplikasi Anda dapat dilokalkan
• Sampel MRT Core
• Cara memuat sumber daya string