Melokalkan aplikasi Anda

Android berjalan di banyak perangkat dan wilayah. Untuk menjangkau sebagian besar pengguna, aplikasi Anda harus menangani teks, file audio, angka, mata uang, dan grafik sesuai dengan lokal tempat aplikasi Anda digunakan.

Dokumen ini menjelaskan praktik terbaik untuk melokalkan aplikasi Android.

Anda seharusnya memiliki pengetahuan tentang bahasa pemrograman Java dan sudah tidak asing lagi dengan pemuatan resource Android, deklarasi elemen antarmuka pengguna dalam XML, pertimbangan pengembangan seperti siklus hidup aktivitas, serta prinsip-prinsip umum internasionalisasi dan pelokalan.

Praktik terbaik untuk menggunakan framework resource Android adalah dengan memisahkan aspek terlokalkan aplikasi Anda sebanyak mungkin dari fungsionalitas inti berbasis Java:

• Anda bisa menempatkan sebagian besar atau semua konten antarmuka pengguna aplikasi Anda ke dalam file resource, seperti yang dijelaskan dalam dokumen ini dan Menyediakan Resource.
• Di sisi lain, perilaku antarmuka pengguna didorong oleh kode berbasis Java Anda. Misalnya, jika pengguna memasukkan data yang harus diformat atau diurutkan secara berbeda tergantung lokal, maka Anda harus menggunakan bahasa pemrograman Java untuk menangani data tersebut secara terprogram. Dokumen ini tidak membahas cara melokalkan kode berbasis Java Anda.

Untuk panduan singkat tentang melokalkan string dalam aplikasi Anda, lihat kelas pelatihan, Mendukung Berbagai Bahasa.

Ringkasan: Pengalihan resource di Android

Resource adalah string teks, tata letak, suara, grafik, dan data statis lainnya yang diperlukan aplikasi Android Anda. Aplikasi dapat menyertakan beberapa kumpulan resource, yang masing-masingnya disesuaikan untuk konfigurasi perangkat yang berbeda. Saat pengguna menjalankan aplikasi tersebut, Android otomatis memilih dan memuat resource yang paling sesuai dengan perangkat.

(Dokumen ini berfokus pada pelokalan dan lokal. Untuk deskripsi lengkap tentang pengalihan resource dan semua jenis konfigurasi yang dapat Anda tentukan — orientasi layar, jenis layar sentuh, dan sebagainya — lihat Menyediakan Resource Alternatif.)

Saat menulis aplikasi, Anda membuat resource default dan alternatif untuk digunakan aplikasi Anda. Saat pengguna menjalankan aplikasi Anda, sistem Android akan memilih resource yang dimuat berdasarkan lokal perangkat. Untuk membuat resource, tempatkan file di dalam subdirektori yang diberi nama secara khusus pada direktori res/ project.

Alasan pentingnya resource default

Setiap kali aplikasi berjalan di lokal tempat Anda tidak memberikan teks khusus lokal, Android akan memuat string default dari res/values/strings.xml. Jika file default ini tidak ada, atau jika string yang dibutuhkan aplikasi Anda tidak ditemukan, aplikasi Anda tidak akan berjalan dan kemudian menampilkan error. Contoh di bawah mengilustrasikan hal yang dapat terjadi jika file teks default tidak lengkap.

Contoh:

Kode berbasis Java aplikasi hanya merujuk ke dua string saja, text_a dan text_b. Aplikasi ini menyertakan file resource terlokalkan (res/values-en/strings.xml) yang menentukan text_a dan text_b dalam bahasa Inggris. Aplikasi ini juga menyertakan file resource default (res/values/strings.xml) yang menyertakan definisi untuk text_a, tetapi tidak untuk text_b:

• Saat aplikasi ini diluncurkan di perangkat dengan lokal yang disetel ke bahasa Inggris, aplikasi dapat berjalan tanpa masalah, karena res/values-en/strings.xml berisi kedua string teks yang diperlukan.
• Namun, pengguna akan melihat pesan error dan tombol Force Close saat aplikasi ini diluncurkan di perangkat yang disetel ke bahasa selain bahasa Inggris. Aplikasi tersebut tidak akan dimuat.

Untuk mencegah situasi ini, pastikan bahwa file res/values/strings.xml ada dan file tersebut menentukan setiap string yang diperlukan. Situasi tersebut berlaku untuk semua jenis resource, tidak hanya string: Anda harus membuat kumpulan file resource default yang berisi semua resource yang akan dipanggil aplikasi Anda—tata letak, drawable, animasi, dll. Untuk informasi tentang pengujian, lihat Pengujian untuk Resource Default.

Menggunakan resource untuk pelokalan

Cara membuat resource default

Tempatkan teks default aplikasi di res/values/strings.xml.

String teks di res/values/strings.xml harus menggunakan bahasa default, yaitu bahasa yang menurut Anda paling sering digunakan oleh pengguna aplikasi Anda.

Kumpulan resource default juga harus menyertakan semua drawable serta tata letak default, dan dapat menyertakan jenis resource lain seperti animasi:

• res/drawable/(direktori wajib berisi setidaknya satu file grafis, untuk ikon aplikasi di Google Play)
• res/layout/ (direktori wajib berisi file XML yang menentukan tata letak default)
• res/anim/ (diperlukan jika Anda memiliki folder res/anim-<qualifiers>)
• res/xml/ (diperlukan jika Anda memiliki folder res/xml-<qualifiers>)
• res/raw/ (diperlukan jika Anda memiliki folder res/raw-<qualifiers>)

Tips: Di kode Anda, periksa setiap referensi ke resource Android. Pastikan bahwa resource default sudah ditentukan untuk setiap referensi tersebut. Pastikan juga file string defaultnya lengkap: File string terlokalkan dapat berisi subset string, tetapi file string default harus berisi semuanya.

Cara membuat resource alternatif

Sebagian besar pelokalan aplikasi adalah memberikan teks alternatif untuk bahasa yang berbeda. Dalam beberapa kasus, Anda juga memberikan resource grafis, suara, dan tata letak alternatif, serta resource khusus lokal lainnya.

Aplikasi dapat menentukan banyak direktori res/<qualifiers>/, yang masing-masingnya memiliki qualifier yang berbeda. Agar dapat membuat resource alternatif untuk lokal yang berbeda, gunakan qualifier yang menentukan bahasa atau kombinasi bahasa-wilayah. (Nama direktori resource harus sesuai dengan skema penamaan yang dijelaskan dalam Menyediakan Resource Alternatif, atau aplikasi Anda tidak akan dapat mengompilasi.)

Contoh:

Misalnya bahasa default aplikasi Anda adalah bahasa Inggris. Misalnya Anda juga ingin melokalkan semua teks dalam aplikasi ke bahasa Prancis, dan sebagian besar teks di aplikasi (semuanya kecuali judul aplikasi) ke bahasa Jepang. Dalam hal ini, Anda dapat membuat tiga file strings.xml alternatif, masing-masing disimpan dalam direktori resource khusus lokal:

1. res/values/strings.xml
   Berisi teks bahasa Inggris untuk semua string yang digunakan aplikasi tersebut, termasuk teks untuk string bernama title.
2. res/values-fr/strings.xml
   Berisi teks bahasa Prancis untuk semua string, termasuk title.
3. res/values-ja/strings.xml
   Berisi teks bahasa Jepang untuk semua string kecuali title.
   

Jika kode berbasis Java merujuk ke R.string.title, berikut adalah hal yang akan terjadi pada waktu proses:

• Jika perangkat disetel ke bahasa selain bahasa Prancis, Android akan memuat title dari file res/values/strings.xml.
• Jika perangkat disetel ke bahasa Prancis, Android akan memuat title dari file res/values-fr/strings.xml.

Perhatikan bahwa jika perangkat disetel ke bahasa Jepang, Android akan mencari title dalam file res/values-ja/strings.xml. Tetapi, karena tidak ada string seperti itu yang disertakan dalam file tersebut, Android akan menggunakan defaultnya kembali, dan memuat title dalam bahasa Inggris dari file res/values/strings.xml.

Resource mana yang lebih diutamakan?

Jika beberapa file resource cocok dengan konfigurasi perangkat, Android akan mengikuti sekumpulan aturan dalam menentukan file yang akan digunakan. Di antara qualifier yang dapat ditentukan dalam nama direktori resource, lokal hampir selalu diutamakan.

Contoh:

Asumsikan bahwa aplikasi menyertakan kumpulan grafik default dan dua kumpulan grafik lain, masing-masingnya dioptimalkan untuk penyiapan perangkat yang berbeda:

• res/drawable/
  Berisi grafis default.
• res/drawable-small-land-stylus/
  Berisi grafis yang dioptimalkan untuk digunakan dengan perangkat yang mengharapkan input dari stilus dan memiliki layar berkepadatan rendah QVGA dalam orientasi lanskap.
• res/drawable-ja/
  Berisi grafis yang dioptimalkan untuk digunakan dengan bahasa Jepang.

Jika aplikasi berjalan di perangkat yang dikonfigurasi untuk menggunakan bahasa Jepang, Android akan memuat grafis dari res/drawable-ja/, meskipun perangkat kebetulan adalah salah satu yang mengharapkan input dari stilus dan memiliki layar berkepadatan rendah QVGA dalam orientasi lanskap.

Pengecualian: Satu-satunya qualifier yang lebih diutamakan daripada lokal dalam proses pemilihan adalah MCC dan MNC (kode negara seluler dan kode jaringan seluler).

Contoh:

Asumsikan bahwa Anda mendapati situasi berikut:

• Kode aplikasi memanggil R.string.text_a
• Tersedia dua file resource yang relevan:
  • res/values-mcc404/strings.xml, yang menyertakan text_a dalam bahasa default aplikasi, dalam hal ini bahasa Inggris.
  • res/values-hi/strings.xml, yang menyertakan text_a dalam bahasa Hindi.
• Aplikasi sedang berjalan di perangkat yang memiliki konfigurasi berikut:
  • Kartu SIM terhubung ke jaringan seluler di India (MCC 404).
  • Bahasa disetel ke bahasa Hindi (hi).

Android akan memuat text_a dari res/values-mcc404/strings.xml (dalam bahasa Inggris), meskipun jika perangkat dikonfigurasikan untuk bahasa Hindi. Hal ini dikarenakan dalam proses pemilihan resource, Android mengutamakan kecocokan MCC daripada kecocokan bahasa.

Proses pemilihan tidak selalu terlihat sederhana seperti yang ditampilkan dalam contoh-contoh tersebut. Silakan baca Cara Android Menemukan Resource yang Paling Cocok untuk deskripsi yang lebih terperinci tentang proses tersebut. Semua qualifier akan dijelaskan dan dicantumkan dalam urutan prioritas di Tabel 2 tentang Menyediakan Resource Alternatif.

Merujuk ke resource dalam kode

Dalam kode berbasis Java aplikasi, Anda merujuk ke resource menggunakan sintaks R.resource_type.resource_name atau android.R.resource_type.resource_name. Untuk informasi selengkapnya, lihat Mengakses Resource.

Mengelola string untuk pelokalan

Pindahkan semua string ke dalam strings.xml

Saat membuat aplikasi, jangan melakukan hard code pada string mana pun. Sebagai gantinya, deklarasikan semua string sebagai resource dalam file strings.xml default, yang memudahkan Anda dalam mengupdate dan melokalkan. String dalam file strings.xml nantinya dapat dengan mudah diekstrak, diterjemahkan, dan diintegrasikan kembali ke dalam aplikasi Anda (dengan qualifier yang sesuai) tanpa adanya perubahan pada kode yang dikompilasi.

Jika Anda membuat gambar dengan teks, masukkan string tersebut ke dalam strings.xml, serta buat ulang gambar tersebut setelah diterjemahkan.

Ikuti panduan Android untuk string UI

Saat merancang dan mengembangkan UI, pastikan Anda memperhatikan cara berkomunikasi dengan pengguna. Secara umum, gunakan gaya yang ringkas dan padat yang bersahabat tetapi singkat, serta gunakan gaya yang konsisten di seluruh UI.

Pastikan Anda membaca dan mengikuti rekomendasi Desain Material untuk gaya penulisan dan pilihan kata. Dengan melakukannya, aplikasi Anda akan tampak lebih elegan bagi pengguna dan membantu pengguna memahami UI Anda dengan lebih cepat.

Selain itu, selalu gunakan terminologi standar Android jika memungkinkan—misalnya untuk elemen UI seperti Panel Tindakan, Menu Opsi, Kolom Sistem, Notifikasi, dan sebagainya. Penggunaan istilah Android dengan benar dan konsisten akan membuat penerjemahan menjadi lebih mudah dan menghasilkan produk akhir yang lebih baik bagi pengguna.

Berikan konteks yang memadai untuk string yang dideklarasikan

Saat mendeklarasikan string dalam file strings.xml, pastikan Anda menjelaskan konteks penggunaan string tersebut. Informasi ini sangat berharga bagi penerjemah dan akan menghasilkan kualitas terjemahan yang lebih baik. Hal ini juga membantu Anda mengelola string secara lebih efektif.

Berikut contohnya:

<!-- The action for submitting a form. This text is on a button that can fit 30 chars -->
    <string name="login_submit_button">Sign in</string>
    

Pertimbangkan untuk memberikan informasi konteks yang meliputi:

• Untuk apa string ini? Kapan dan di mana string akan ditampilkan kepada pengguna?
• Di mana letaknya dalam tata letak? Misalnya, terjemahan bersifat kurang fleksibel untuk tombol daripada kotak teks.

Tandai bagian pesan yang tidak boleh diterjemahkan

Sering kali, string dapat berisi teks yang tidak boleh diterjemahkan ke bahasa lain. Contoh umumnya dapat berupa potongan kode, placeholder untuk nilai, simbol khusus, atau nama. Saat menyiapkan string untuk diterjemahkan, cari dan tandai teks yang harus tetap sebagaimana adanya, tanpa diterjemahkan, agar penerjemah tidak mengubahnya.

Untuk menandai teks yang seharusnya tidak diterjemahkan, gunakan tag placeholder <xliff:g>. Berikut adalah contoh tag yang memastikan teks "%1$s" tidak berubah selama proses penerjemahan (jika tidak pesannya akan rusak):

    <string name="countdown">
      <xliff:g id="time" example="5 days">%1$s</xliff:g> until holiday
    </string>
    

Saat Anda mendeklarasikan tag placeholder, selalu tambahkan atribut id yang menjelaskan kegunaan placeholder tersebut. Jika nantinya aplikasi Anda mengganti nilai placeholder, pastikan untuk memberikan atribut contoh guna memperjelas penggunaan yang diharapkan.

Berikut ini beberapa contoh tag placeholder:

    <resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
    <!-- Example placeholder for a special unicode symbol -->
    <string name="star_rating">Check out our 5
        <xliff:g id="star">\u2605</xliff:g>
    </string>
    <!-- Example placeholder for a for a URL -->
    <string name="app_homeurl">
        Visit us at <xliff:g
        id="application_homepage">http://my/app/home.html</xliff:g>
    </string>
    <!-- Example placeholder for a name -->
    <string name="prod_name">
        Learn more at <xliff:g id="prod_gamegroup">Game Group</xliff:g>
    </string>
    <!-- Example placeholder for a literal -->
    <string name="promo_message">
        Please use the "<xliff:g id="promotion_code">ABCDEFG</xliff:g>" to get a discount.
    </string>
    ...
    </resources>
    

Checklist pelokalan

Untuk ringkasan lengkap proses pelokalan dan pendistribusian aplikasi Android, lihat dokumen Checklist Pelokalan.

Tips pelokalan

Rancang aplikasi Anda agar dapat berfungsi di semua lokal

Anda tidak dapat mengasumsikan apa pun tentang perangkat yang digunakan pengguna untuk menjalankan aplikasi Anda. Perangkat mungkin memiliki hardware yang tidak diantisipasi, atau mungkin disetel ke lokal yang tidak direncanakan atau yang tidak dapat diuji. Rancang aplikasi Anda agar dapat berfungsi normal atau gagal karena wajar, apa pun perangkat yang digunakan.

Penting: Pastikan bahwa aplikasi Anda menyertakan kumpulan lengkap resource default.

Pastikan untuk menyertakan folder res/drawable/ dan res/values/ (tanpa pengubah tambahan di nama folder) yang berisi semua gambar dan teks yang diperlukan aplikasi Anda.

Jika kehilangan bahkan hanya satu resource default, aplikasi Anda tidak akan berjalan pada perangkat yang disetel ke lokal yang tidak didukung. Misalnya, file default res/values/strings.xml mungkin kekurangan satu string yang diperlukan aplikasi: Saat aplikasi berjalan di lokal yang tidak didukung dan mencoba untuk memuat res/values/strings.xml, pengguna akan melihat pesan error dan tombol Force Close.

Untuk informasi selengkapnya, lihat Menguji Resource Default.

Rancang tata letak yang fleksibel

Jika Anda perlu mengatur ulang tata letak agar sesuai dengan bahasa tertentu (misalnya bahasa Jerman dengan kata-katanya yang panjang), Anda dapat membuat tata letak alternatif untuk bahasa tersebut (misalnya res/layout-de/main.xml). Namun, melakukan ini dapat membuat aplikasi Anda lebih sulit dikelola. Akan lebih baik jika Anda membuat satu tata letak yang lebih fleksibel.

Situasi umum lainnya adalah bahasa yang memerlukan sesuatu yang berbeda dalam tata letaknya. Misalnya, Anda mungkin memiliki formulir kontak yang harus menyertakan dua kolom nama saat aplikasi berjalan dalam bahasa Jepang, sedangkan saat aplikasi dijalankan dalam bahasa lain, formulir kontak menyertakan tiga kolom nama. Anda dapat menangani hal ini dengan salah satu dari dua cara berikut:

• Buat satu tata letak dengan kolom yang dapat Anda aktifkan atau nonaktifkan secara terprogram, berdasarkan bahasa, atau
• Setel agar tata letak utama berisi tata letak lain yang menyertakan kolom yang dapat diubah. Tata letak kedua dapat memiliki konfigurasi yang berbeda untuk bahasa yang berbeda.

Hindari membuat file resource dan string teks lebih banyak dari yang Anda perlukan

Anda mungkin tidak perlu membuat alternatif khusus lokal untuk setiap resource di aplikasi Anda. Misalnya, tata letak yang ditentukan dalam file res/layout/main.xml mungkin bekerja di semua lokal, sehingga Anda tidak perlu membuat file tata letak alternatif lain.

Selain itu, Anda mungkin tidak perlu membuat teks alternatif untuk setiap string. Misalnya, asumsikan hal-hal berikut:

• Bahasa default aplikasi Anda adalah bahasa Inggris Amerika. Setiap string yang digunakan aplikasi telah ditentukan, menggunakan ejaan Bahasa Inggris Amerika, dalam res/values/strings.xml.
• Untuk beberapa frasa penting, Anda ingin memberikan ejaan bahasa Inggris Inggris. Anda ingin string alternatif ini digunakan saat aplikasi berjalan di perangkat di wilayah Inggris.

Untuk melakukannya, Anda dapat membuat file kecil bernama res/values-en-rGB/strings.xml yang hanya menyertakan string yang seharusnya akan berbeda saat aplikasi berjalan di wilayah Inggris. Untuk semua string lainnya, aplikasi tersebut akan kembali ke defaultnya dan menggunakan yang telah ditentukan dalam res/values/strings.xml.

Gunakan objek Konteks Android untuk pencarian lokal secara manual

Anda dapat mencari lokal menggunakan objek Context yang disediakan oleh Android:

    val primaryLocale: Locale = context.resources.configuration.locales[0]
    val locale: String = primaryLocale.displayName
    

    Locale primaryLocale = context.getResources().getConfiguration().getLocales().get(0);
    String locale = primaryLocale.getDisplayName();
    

Gunakan Layanan Penerjemahan Aplikasi

Layanan Penerjemahan Aplikasi terintegrasi ke dalam Konsol Play, dan juga dapat diakses dari Android Studio. Ini adalah cara cepat dan mudah untuk mendapatkan penawaran instan serta melakukan pemesanan dengan perusahaan penerjemahan. Anda dapat memesan terjemahan ke dalam satu atau beberapa bahasa untuk string UI aplikasi, teks Listingan Play Store, nama IAP, dan teks kampanye iklan.

Menguji aplikasi yang dilokalkan

Menguji di perangkat

Perlu diingat bahwa perangkat yang sedang diuji mungkin berbeda secara signifikan dari perangkat yang tersedia untuk konsumen di wilayah geografis lain. Lokal yang tersedia di perangkat Anda mungkin berbeda dengan yang tersedia di perangkat lain. Selain itu, resolusi dan kepadatan layar perangkat mungkin berbeda, yang bisa memengaruhi tampilan string dan drawable di UI Anda.

Untuk mengubah lokal atau bahasa di perangkat, gunakan aplikasi Setelan.

Menguji di emulator

Untuk detail tentang penggunaan emulator, lihat Android Emulator.

Membuat dan menggunakan lokal kustom

Lokal "kustom" adalah kombinasi bahasa/wilayah yang tidak didukung secara eksplisit oleh image sistem Android. Anda dapat menguji cara aplikasi berjalan di lokal kustom dengan membuat lokal kustom di emulator. Ada 2 cara untuk melakukannya:

• Menggunakan aplikasi Lokal Kustom, yang dapat diakses dari tab aplikasi. (Setelah selesai dibuat, beralihlah ke lokal kustom dengan menekan dan menahan nama lokal tersebut.)
• Mengubah ke lokal kustom dari shell adb, seperti yang dijelaskan di bawah ini.

Saat Anda menyetel emulator ke lokal yang tidak tersedia di image sistem Android, sistem akan ditampilkan dalam bahasa defaultnya. Namun, aplikasi Anda seharusnya melokalkannya dengan benar.

Mengubah lokal emulator dari shell adb

Untuk mengubah lokal di emulator dengan menggunakan shell adb.

1. Pilih lokal yang ingin Anda uji dan tentukan tag bahasa BCP-47nya, misalnya, bahasa Prancis Kanada adalah fr-CA.
   
2. Luncurkan emulator.
3. Dari shell command line di komputer host, jalankan perintah berikut:
   adb shell atau jika Anda memiliki perangkat yang terpasang, tentukan bahwa Anda menginginkan emulator tersebut dengan menambahkan opsi -e: adb -e shell
4. Pada prompt adb shell (#), jalankan perintah ini:
   setprop persist.sys.locale [BCP-47 language tag];stop;sleep 5;start
Ganti bagian yang diberi tanda kurung dengan kode yang sesuai dari Langkah 1.

Misalnya, untuk menguji dalam bahasa Prancis Kanada:

setprop persist.sys.locale fr-CA;stop;sleep 5;start

Perintah ini akan memulai ulang emulator. (Terlihat seperti reboot penuh, tetapi sebenarnya tidak.) Setelah layar utama muncul kembali, luncurkan ulang aplikasi Anda, dan aplikasi akan diluncurkan dengan lokal baru.

Menguji resource default

Berikut ini cara menguji apakah aplikasi menyertakan setiap resource string yang diperlukan atau tidak:

1. Setel emulator atau perangkat ke bahasa yang tidak didukung aplikasi Anda. Misalnya, jika aplikasi memiliki string bahasa Prancis di res/values-fr/ tetapi tidak memiliki string bahasa Spanyol dalam res/values-es/, maka setel lokal emulator ke bahasa Spanyol. (Anda dapat menggunakan aplikasi Lokal Kustom untuk menyetel emulator ke lokal yang tidak didukung.)
2. Jalankan aplikasi
3. Jika menampilkan pesan error dan tombol Force Close, aplikasi tersebut mungkin mencari string yang tidak tersedia. Pastikan bahwa file res/values/strings.xml Anda menyertakan definisi untuk setiap string yang digunakan aplikasi.

Jika pengujian berhasil, ulangi prosesnya untuk jenis konfigurasi lainnya. Misalnya, jika aplikasi memiliki file tata letak bernama res/layout-land/main.xml tetapi tidak berisi file bernama res/layout-port/main.xml, maka setel emulator atau perangkat tersebut ke orientasi potret dan lihat apakah aplikasi berjalan.