Bagikan melalui

Xamarin.Forms Pelokalan String dan Gambar

  • Artikel

Pelokalan adalah proses mengadaptasi aplikasi untuk memenuhi persyaratan bahasa atau budaya tertentu dari target pasar. Untuk mencapai pelokalan, teks dan gambar dalam aplikasi mungkin perlu diterjemahkan ke dalam beberapa bahasa. Aplikasi yang dilokalkan secara otomatis menampilkan teks yang diterjemahkan berdasarkan pengaturan budaya perangkat seluler:

Cuplikan layar aplikasi pelokalan di iOS dan Android

Kerangka kerja .NET menyertakan mekanisme bawaan untuk melokalisasi aplikasi menggunakan file sumber daya Resx. File sumber daya menyimpan teks dan konten lain sebagai pasangan nama/nilai yang memungkinkan aplikasi mengambil konten untuk kunci yang disediakan. File sumber daya memungkinkan konten yang dilokalkan dipisahkan dari kode aplikasi.

Menggunakan file sumber daya untuk melokalisasi aplikasi mengharuskan Xamarin.Forms Anda melakukan langkah-langkah berikut:

  1. Buat file Resx yang berisi teks yang diterjemahkan.
  2. Tentukan budaya default dalam proyek bersama.
  3. Melokalisasi teks di Xamarin.Forms.
  4. Melokalisasi gambar berdasarkan pengaturan budaya untuk setiap platform.
  5. Melokalisasi nama aplikasi pada setiap platform.
  6. Uji pelokalan pada setiap platform.

Membuat file Resx

File sumber daya adalah file XML dengan ekstensi .resx yang dikompilasi ke dalam file sumber daya biner (.resources) selama proses build. Visual Studio 2019 menghasilkan kelas yang menyediakan API yang digunakan untuk mengambil sumber daya. Aplikasi yang dilokalkan biasanya berisi file sumber daya default dengan semua string yang digunakan dalam aplikasi, serta file sumber daya untuk setiap bahasa yang didukung. Aplikasi sampel memiliki folder Resx di proyek bersama yang berisi file sumber daya, dan file sumber daya defaultnya yang disebut AppResources.resx.

File sumber daya berisi informasi berikut untuk setiap item:

  • Nama menentukan kunci yang digunakan untuk mengakses teks dalam kode.
  • Nilai menentukan teks yang diterjemahkan.
  • Komentar adalah bidang opsional yang berisi informasi tambahan.

File sumber daya ditambahkan dengan dialog Tambahkan Item Baru di Visual Studio 2019:

Menambahkan Sumber Daya baru di Visual Studio 2019

Setelah file ditambahkan, baris dapat ditambahkan untuk setiap sumber daya teks:

Tentukan sumber daya teks default dalam file .resx

Pengaturan drop-down Pengubah Akses menentukan bagaimana Visual Studio menghasilkan kelas yang digunakan untuk mengakses sumber daya. Mengatur Pengubah Akses ke Publik atau Internal menghasilkan kelas yang dihasilkan dengan tingkat aksesibilitas yang ditentukan. Mengatur Pengubah Akses ke Tidak ada pembuatan kode tidak menghasilkan file kelas. File sumber daya default harus dikonfigurasi untuk menghasilkan file kelas, yang menghasilkan file dengan ekstensi .designer.cs ditambahkan ke proyek.

Setelah file sumber daya default dibuat, file tambahan dapat dibuat untuk setiap budaya yang didukung aplikasi. Setiap file sumber daya tambahan harus menyertakan budaya terjemahan dalam nama file dan harus memiliki Pengubah Akses yang diatur ke Tidak ada pembuatan kode.

Pada runtime, aplikasi mencoba menyelesaikan permintaan sumber daya dalam urutan kekhususan. Misalnya, jika budaya perangkat adalah en-US , aplikasi mencari file sumber daya dalam urutan ini:

  1. AppResources.en-US.resx
  2. AppResources.en.resx
  3. AppResources.resx (default)

Cuplikan layar berikut menunjukkan file terjemahan Spanyol bernama AppResources.es.resx:

Tentukan sumber daya teks bahasa Spanyol default dalam file .resx

File terjemahan menggunakan nilai Nama yang sama yang ditentukan dalam file default tetapi berisi string bahasa Spanyol di kolom Nilai. Selain itu, Pengubah Akses diatur ke Tidak ada pembuatan kode.

File sumber daya ditambahkan dengan dialog Tambahkan File Baru di Visual Studio 2019 untuk Mac:

Menambahkan Sumber Daya baru di Visual Studio 2019 untuk Mac

Setelah file sumber daya default dibuat, teks dapat ditambahkan dengan membuat data elemen dalam root elemen dalam file sumber daya:

<?xml version="1.0" encoding="utf-8"?>
<root>
    ...
    <data name="AddButton" xml:space="preserve">
        <value>Add Note</value>
    </data>
    <data name="NotesLabel" xml:space="preserve">
        <value>Notes:</value>
    </data>
    <data name="NotesPlaceholder" xml:space="preserve">
        <value>e.g. Get Milk</value>
    </data>
</root>

File kelas .designer.cs dapat dibuat dengan mengatur properti Custom Tool di opsi file sumber daya:

Alat Kustom yang ditentukan dalam properti file sumber daya

Mengatur Alat Kustom ke PublicResXFileCodeGenerator akan menghasilkan kelas yang dihasilkan dengan public akses. Mengatur Alat Kustom ke InternalResXFileCodeGenerator akan menghasilkan kelas yang dihasilkan dengan internal akses. Nilai Custom Tool kosong tidak akan menghasilkan kelas. Nama kelas yang dihasilkan akan cocok dengan nama file sumber daya. Misalnya, file AppResources.resx akan menghasilkan pembuatan AppResources kelas dalam file yang disebut AppResources.designer.cs.

File sumber daya tambahan dapat dibuat untuk setiap budaya yang didukung. Setiap file bahasa harus menyertakan budaya terjemahan dalam nama file sehingga file yang menargetkan es-MX harus diberi nama AppResources.es-MX.resx.

Pada runtime, aplikasi mencoba menyelesaikan permintaan sumber daya dalam urutan kekhususan. Misalnya, jika budaya perangkat adalah en-US , aplikasi mencari file sumber daya dalam urutan ini:

  1. AppResources.en-US.resx
  2. AppResources.en.resx
  3. AppResources.resx (default)

File terjemahan bahasa harus memiliki nilai Nama yang sama yang ditentukan sebagai file default. XML berikut menunjukkan file terjemahan Spanyol bernama AppResources.es.resx:

<?xml version="1.0" encoding="utf-8"?>
<root>
    ...
    <data name="NotesLabel" xml:space="preserve">
        <value>Notas:</value>
    </data>
    <data name="NotesPlaceholder" xml:space="preserve">
        <value>por ejemplo . comprar leche</value>
    </data>
    <data name="AddButton" xml:space="preserve">
        <value>Agregar nuevo elemento</value>
    </data>
</root>

Tentukan budaya default

Agar file sumber daya berfungsi dengan benar, aplikasi harus memiliki atribut yang NeutralResourcesLanguage ditentukan. Dalam proyek yang berisi file sumber daya, file AssemblyInfo.cs harus disesuaikan untuk menentukan budaya default. Kode berikut menunjukkan cara mengatur NeutralResourcesLanguage ke en-US dalam file AssemblyInfo.cs :

using System.Resources;

// The resources from the neutral language .resx file are stored directly
// within the library assembly. For that reason, changing en-US to a different
// language in this line will not by itself change the language shown in the
// app. See the discussion of UltimateResourceFallbackLocation in the
// documentation for additional information:
// https://learn.microsoft.com/dotnet/api/system.resources.neutralresourceslanguageattribute
[assembly: NeutralResourcesLanguage("en-US")]

Peringatan

Jika Anda tidak menentukan NeutralResourcesLanguage atribut , ResourceManager kelas mengembalikan null nilai untuk budaya apa pun tanpa file sumber daya tertentu. Ketika budaya default ditentukan, mengembalikan ResourceManager hasil dari file Resx default untuk budaya yang tidak didukung. Oleh karena itu, disarankan agar Anda selalu menentukan NeutralResourcesLanguage sehingga teks ditampilkan untuk budaya yang tidak didukung.

Setelah file sumber daya default dibuat dan budaya default yang ditentukan dalam file AssemblyInfo.cs , aplikasi dapat mengambil string yang dilokalkan pada runtime.

Untuk informasi selengkapnya tentang file sumber daya, lihat Membuat file sumber daya untuk aplikasi .NET.

Menentukan bahasa yang didukung di iOS

Di iOS, Anda harus mendeklarasikan semua bahasa yang didukung dalam file Info.plist untuk proyek Anda. Dalam file Info.plist, gunakan tampilan Sumber untuk mengatur array untuk CFBundleLocalizations kunci, dan berikan nilai yang sesuai dengan file Resx. Selain itu, pastikan Anda mengatur bahasa yang diharapkan melalui CFBundleDevelopmentRegion kunci:

Cuplikan layar editor Info.plist memperlihatkan bagian Pelokalan

Atau, buka file Info.plist di editor XML dan tambahkan yang berikut ini:

<key>CFBundleLocalizations</key>
<array>
    <string>de</string>
    <string>es</string>
    <string>fr</string>
    <string>ja</string>
    <string>pt</string> <!-- Brazil -->
    <string>pt-PT</string> <!-- Portugal -->
    <string>ru</string>
    <string>zh-Hans</string>
    <string>zh-Hant</string>
</array>
<key>CFBundleDevelopmentRegion</key>
<string>en</string>

Catatan

Apple memperlakukan bahasa Portugis sedikit berbeda dari yang Anda harapkan. Untuk informasi selengkapnya, lihat Menambahkan Bahasa di developer.apple.com.

Untuk informasi selengkapnya, lihat Menentukan bahasa default dan yang didukung di Info.plist.

Tentukan bahasa yang didukung pada UWP

Ini hanya diperlukan jika Anda membuat App Bundle saat Anda mengemas aplikasi untuk sideloading atau toko. Saat Anda membuat App Bundle UWP, saat bundel diinstal, itu hanya akan memuat sumber daya yang terkait dengan pengaturan bahasa perangkat penginstalan. Oleh karena itu, jika perangkat hanya memiliki bahasa Inggris, maka hanya sumber daya bahasa Inggris yang akan diinstal dengan aplikasi. Untuk informasi dan instruksi selengkapnya, lihat Aplikasi Bursa Windows 8.1: Pastikan sumber daya diinstal pada perangkat terlepas dari apakah perangkat memerlukannya.

Melokalisasi teks di Xamarin.Forms

Teks dilokalkan menggunakan Xamarin.Forms kelas yang dihasilkan AppResources . Kelas ini dinamai berdasarkan nama file sumber daya default. Karena file sumber daya proyek sampel bernama AppResources.resx, Visual Studio menghasilkan kelas yang cocok yang disebut AppResources. Properti statis dihasilkan di AppResources kelas untuk setiap baris dalam file sumber daya. Properti statis berikut dihasilkan di kelas aplikasi AppResources sampel:

  • Tambahkan Tombol
  • NotesLabel
  • NotesPlaceholder

Mengakses nilai-nilai ini sebagai properti x:Static memungkinkan teks yang dilokalkan ditampilkan di XAML:

<ContentPage ...
             xmlns:resources="clr-namespace:LocalizationDemo.Resx">
    <Label Text="{x:Static resources:AppResources.NotesLabel}" />
    <Entry Placeholder="{x:Static resources:AppResources.NotesPlaceholder}" />
    <Button Text="{x:Static resources:AppResources.AddButton}" />
</ContentPage>

Teks yang dilokalkan juga dapat diambil dalam kode:

public LocalizedCodePage()
{
    Label notesLabel = new Label
    {
        Text = AppResources.NotesLabel,
        // ...
    };

    Entry notesEntry = new Entry
    {
        Placeholder = AppResources.NotesPlaceholder,
        //...
    };

    Button addButton = new Button
    {
        Text = AppResources.AddButton,
        // ...
    };

    Content = new StackLayout
    {
        Children = {
            notesLabel,
            notesEntry,
            addButton
        }
    };
}

Properti di AppResources kelas menggunakan nilai saat ini untuk System.Globalization.CultureInfo.CurrentUICulture menentukan file sumber daya budaya mana yang akan diambil nilainya.

Melokalisasi gambar

Selain menyimpan teks, file Resx mampu menyimpan lebih dari sekadar teks, mereka juga dapat menyimpan gambar dan data biner. Namun, perangkat seluler memiliki berbagai ukuran dan kepadatan layar dan setiap platform seluler memiliki fungsionalitas untuk menampilkan gambar yang bergantung pada kepadatan. Oleh karena itu, fungsionalitas pelokalan gambar platform harus digunakan alih-alih menyimpan gambar dalam file sumber daya.

Melokalisasi gambar di Android

Di Android, drawable yang dilokalkan (gambar) disimpan menggunakan konvensi penamaan untuk folder di direktori Sumber Daya . Folder diberi nama yang dapat digambar dengan akhiran untuk bahasa target. Misalnya, folder bahasa Spanyol diberi nama drawable-es.

Saat kode lokal empat huruf diperlukan, Android memerlukan r tambahan setelah tanda hubung. Misalnya, folder lokal Meksiko (es-MX) harus diberi nama drawable-es-rMX. Nama file gambar di setiap folder lokal harus identik:

Gambar yang dilokalkan dalam proyek Android

Untuk informasi selengkapnya, lihat Pelokalan Android.

Melokalisasi gambar di iOS

Di iOS, gambar yang dilokalkan disimpan menggunakan konvensi penamaan untuk folder di direktori Sumber Daya . Folder default bernama Base.lproj. Folder khusus bahasa dinamai dengan bahasa atau nama lokal, diikuti oleh .lproj. Misalnya, folder bahasa Spanyol diberi nama es.lproj.

Kode lokal empat huruf berfungsi seperti kode bahasa dua huruf. Misalnya, folder lokal Meksiko (es-MX) harus diberi nama es-MX.lproj. Nama file gambar di setiap folder lokal harus identik:

Gambar yang dilokalkan dalam proyek iOS

Catatan

iOS mendukung pembuatan Katalog Aset yang dilokalkan alih-alih menggunakan struktur folder .lproj. Namun, ini harus dibuat dan dikelola di Xcode.

Untuk informasi selengkapnya, lihat Pelokalan iOS.

Melokalisasi gambar di UWP

Di UWP, gambar yang dilokalkan disimpan menggunakan konvensi penamaan untuk folder di direktori Aset/Gambar . Folder dinamai dengan bahasa atau lokal. Misalnya, folder bahasa Spanyol bernama es dan folder lokal Meksiko harus diberi nama es-MX. Nama file gambar di setiap folder lokal harus identik:

Gambar yang dilokalkan dalam proyek UWP

Untuk informasi selengkapnya, lihat Pelokalan UWP.

Mengonsumsi gambar yang dilokalkan

Karena setiap platform menyimpan gambar dengan struktur file yang unik, XAML menggunakan OnPlatform kelas untuk mengatur ImageSource properti berdasarkan platform saat ini:

<Image>
    <Image.Source>
        <OnPlatform x:TypeArguments="ImageSource">
            <On Platform="iOS, Android" Value="flag.png" />
            <On Platform="UWP" Value="Assets/Images/flag.png" />
        </OnPlatform>
    </Image.Source>
</Image>

Catatan

Ekstensi OnPlatform markup menawarkan cara yang lebih ringkas untuk menentukan nilai khusus platform. Untuk informasi selengkapnya, lihat Ekstensi markup OnPlatform.

Sumber gambar dapat diatur berdasarkan Device.RuntimePlatform properti dalam kode:

string imgSrc = Device.RuntimePlatform == Device.UWP ? "Assets/Images/flag.png" : "flag.png";
Image flag = new Image
{
    Source = ImageSource.FromFile(imgSrc),
    WidthRequest = 100
};

Melokalisasi nama aplikasi

Nama aplikasi ditentukan per platform dan tidak menggunakan file sumber daya Resx. Untuk melokalisasi nama aplikasi di Android, lihat Melokalisasi nama aplikasi di Android. Untuk melokalisasi nama aplikasi di iOS, lihat Melokalisasi nama aplikasi di iOS. Untuk melokalisasi nama aplikasi di UWP, lihat Melokalkan string dalam manifes paket UWP.

Menguji pelokalan

Pelokalan pengujian paling baik dilakukan dengan mengubah bahasa perangkat Anda. Dimungkinkan untuk menetapkan nilai System.Globalization.CultureInfo.CurrentUICulture dalam kode tetapi perilaku tidak konsisten di seluruh platform sehingga ini tidak disarankan untuk pengujian.

Di iOS, di aplikasi pengaturan, Anda dapat mengatur bahasa untuk setiap aplikasi secara khusus tanpa mengubah bahasa perangkat Anda.

Di Android, pengaturan bahasa terdeteksi dan di-cache saat aplikasi dimulai. Jika Anda mengubah bahasa, Anda mungkin perlu keluar dan memulai ulang aplikasi untuk melihat perubahan yang diterapkan.