Melokalkan aplikasi Anda

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

Halaman ini menjelaskan praktik terbaik untuk melokalkan aplikasi Android.

Anda harus memiliki pengetahuan tentang bahasa pemrograman Kotlin atau Java dan sudah terbiasa dengan Pemuatan resource Android, mendeklarasikan elemen antarmuka pengguna dalam XML, pertimbangan pengembangan seperti siklus proses aktivitas, serta prinsip umum internasionalisasi dan pelokalan.

Sebaiknya gunakan framework resource Android untuk memisahkan aspek yang dilokalkan dari aplikasi Anda sebanyak mungkin dari fungsi aplikasi inti.

• Masukkan sebagian besar atau semua konten antarmuka pengguna aplikasi Anda ke dalam file resource, seperti yang dijelaskan di halaman ini dan dalam Ringkasan resource aplikasi.
• Di sisi lain, perilaku antarmuka pengguna didorong oleh kode berbasis Kotlin atau Java Anda. Misalnya, jika pengguna memasukkan data yang harus diformat atau diurutkan secara berbeda tergantung lokalitas, Anda harus menggunakan bahasa pemrograman Kotlin atau Java untuk menangani data tersebut secara terprogram. Halaman ini tidak membahas cara melokalkan kode berbasis Java atau Kotlin.

Untuk panduan pelokalan lokal string dalam aplikasi Anda, lihat Mendukung berbagai bahasa dan budaya.

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.

Halaman ini berfokus pada pelokalan dan lokalitas. Untuk deskripsi lengkap tentang pengalihan resource dan semua jenis konfigurasi yang dapat Anda tentukan, seperti orientasi layar atau jenis layar sentuh, 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 lokalitas perangkat. Untuk membuat resource, tempatkan file di dalam subdirektori yang diberi nama secara khusus pada direktori res/ project.

Alasan pentingnya resource default

Saat aplikasi berjalan di lokalitas mana pun yang belum Anda beri teks khusus lokalitas, 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 berikut mengilustrasikan hal yang dapat terjadi jika file teks default tidak lengkap.

Contoh:

Kode berbasis Kotlin atau berbasis Java aplikasi hanya merujuk ke dua string, 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 lokalitas yang disetel ke bahasa Inggris, aplikasi dapat berjalan tanpa masalah, karena res/values-en/strings.xml berisi kedua string teks yang diperlukan.
• Namun, saat aplikasi ini diluncurkan di perangkat yang disetel ke bahasa selain bahasa Inggris, pengguna melihat pesan error dan tombol Force Close. 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 ini berlaku untuk semua jenis resource, tidak hanya string: Anda harus membuat kumpulan file resource default yang berisi semua resource yang dipanggil oleh aplikasi Anda, seperti tata letak, drawable, atau animasi. Untuk informasi tentang pengujian, lihat bagian Menguji resource default.

Menggunakan resource untuk pelokalan

Bagian ini membahas cara membuat resource default serta resource alternatif. Panduan ini juga menjelaskan cara menetapkan resource yang diprioritaskan dan cara merujuk ke resource dalam kode.

Membuat resource default

Tempatkan teks default aplikasi di res/values/strings.xml. Untuk string ini, gunakan bahasa default—bahasa yang Anda harapkan digunakan oleh sebagian besar pengguna aplikasi Anda.

Kumpulan resource default juga menyertakan semua drawable serta tata letak default dan dapat menyertakan jenis resource lain seperti animasi. Resource ini berada di direktori berikut:

• res/drawable/: direktori wajib berisi minimam 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 default-nya lengkap: file string terlokalkan dapat berisi subset string, tetapi file string default harus berisi semuanya.

Membuat resource alternatif

Sebagian besar pelokalan aplikasi 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 penentu yang berbeda. Agar dapat membuat resource alternatif untuk lokalitas yang berbeda, gunakan penentu 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 dan Anda ingin melokalkan semua teks dalam aplikasi ke bahasa Prancis dan semua teks, kecuali judul aplikasi, ke bahasa Jepang. Dalam hal ini, Anda harus membuat tiga file strings.xml, 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 Kotlin atau Java merujuk ke R.string.title, inilah 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.

Jika perangkat disetel ke bahasa Jepang, Android akan mencari title dalam file res/values-ja/strings.xml. Namun, karena tidak ada string seperti itu yang disertakan dalam file tersebut, Android akan menggunakan default-nya 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 penentu yang dapat ditentukan dalam nama direktori resource, lokalitas 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 penentu yang lebih diutamakan daripada lokalitas dalam proses pemilihan adalah kode negara seluler (MCC) dan kode jaringan seluler (MNC).

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. Untuk mengetahui deskripsi yang lebih detail tentang proses tersebut, lihat Cara Android menemukan resource yang paling cocok. Semua penentu akan dijelaskan dan dicantumkan dalam urutan prioritas di Ringkasan resource aplikasi.

Merujuk ke resource dalam kode

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

Mengelola string untuk pelokalan

Bagian ini menjelaskan praktik terbaik untuk mengelola string yang terkait dengan pelokalan.

Memindahkan semua string ke dalam strings.xml

Saat membuat aplikasi, jangan melakukan hardcode pada string mana pun. Sebagai gantinya, deklarasikan semua string sebagai resource dalam file strings.xml default sehingga akan memudahkan Anda dalam mengupdate dan melokalkan. String dalam file strings.xml dapat dengan mudah diekstrak, diterjemahkan, dan diintegrasikan kembali ke dalam aplikasi Anda, dengan penentu 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, perhatikan dengan cermat cara Anda berkomunikasi dengan pengguna. Secara umum, gunakan gaya yang bersahabat tetapi singkat, dan 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 aplikasi, menu opsi, kolom sistem, dan notifikasi. 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 membantu 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 seperti berikut:

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

Menandai bagian pesan yang tidak akan diterjemahkan

Sering kali, string berisi teks yang tidak dimaksudkan untuk diterjemahkan ke dalam bahasa lain. Contoh umumnya adalah 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 tidak akan diterjemahkan, gunakan tag placeholder <xliff:g>. Berikut adalah contoh tag yang menunjukkan bahwa teks "%1$s" tidak akan diubah selama penerjemahan untuk menghindari pesan rusak:

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

Saat Anda mendeklarasikan tag placeholder, 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 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 Menerjemahkan dan melokalkan aplikasi.

Tips pelokalan

Ikuti tips ini saat Anda melokalkan aplikasi.

Rancang aplikasi Anda agar dapat berfungsi di semua lokalitas

Jangan berasumsi apa pun tentang perangkat yang digunakan pengguna menjalankan aplikasi Anda. Perangkat mungkin memiliki hardware yang tidak Anda perkirakan sebelumnya atau mungkin disetel ke lokalitas yang tidak Anda rencanakan atau yang tidak dapat Anda uji. Rancang aplikasi Anda agar dapat berfungsi normal atau gagal karena wajar, apa pun perangkat yang digunakan.

Penting: Pastikan aplikasi Anda menyertakan kumpulan lengkap resource default: sertakan folder res/drawable/ dan res/values/ tanpa pengubah tambahan di 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, jika file default res/values/strings.xml tidak memiliki satu string yang diperlukan aplikasi, saat aplikasi berjalan di lokalitas yang tidak didukung dan mencoba memuat res/values/strings.xml, pengguna akan melihat pesan error dan tombol Force Close.

Untuk mengetahui informasi selengkapnya, lihat bagian Menguji resource default.

Rancang tata letak yang fleksibel

Jika harus menyusun ulang tata letak agar sesuai dengan bahasa tertentu, Anda dapat membuat tata letak alternatif untuk bahasa tersebut, seperti res/layout-de/main.xml untuk tata letak berbahasa Jerman. Namun, tindakan 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 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.
• 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 lokalitas untuk setiap resource di aplikasi Anda. Misalnya, tata letak yang ditentukan dalam file res/layout/main.xml mungkin berfungsi di semua lokalitas 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 Britania. Anda ingin string alternatif ini digunakan saat aplikasi berjalan di perangkat di wilayah Inggris.

Untuk melakukannya, buat file kecil bernama res/values-en-rGB/strings.xml yang hanya menyertakan string yang akan berbeda saat aplikasi berjalan di wilayah Inggris Raya. Untuk semua string lainnya, aplikasi tersebut akan kembali ke default-nya dan menggunakan apa yang telah ditentukan dalam res/values/strings.xml.

Menggunakan objek Konteks Android untuk pencarian lokalitas secara manual

Anda dapat mencari lokalitas menggunakan objek Context yang disediakan oleh Android, seperti yang ditunjukkan dalam contoh berikut:

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();

Menggunakan layanan terjemahan aplikasi

Layanan Terjemahan Aplikasi terintegrasi ke dalam Konsol Play. Dengan memanfaatkan layanan ini, Anda berkesempatan mendapatkan penawaran instan dan 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

Uji aplikasi yang dilokalkan di perangkat atau menggunakan Android Emulator. Khususnya, uji aplikasi Anda untuk memastikan bahwa semua resource default yang diperlukan disertakan.

Menguji di perangkat

Perlu diingat bahwa perangkat yang sedang diuji mungkin secara signifikan berbeda dengan perangkat yang tersedia untuk konsumen di tempat lain. Lokalitas yang tersedia di perangkat Anda mungkin berbeda dengan yang tersedia di perangkat lain. Selain itu, resolusi dan kepadatan layar perangkat mungkin berbeda sehingga dapat memengaruhi tampilan string dan drawable di UI Anda.

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

Menguji di emulator

Untuk mengetahui detail tentang penggunaan emulator, lihat Menjalankan aplikasi di Android Emulator.

Membuat dan menggunakan lokalitas kustom

Lokalitas "kustom" adalah kombinasi bahasa atau wilayah yang tidak didukung secara eksplisit oleh image sistem Android. Anda dapat menguji cara aplikasi berjalan di lokalitas kustom dengan membuat lokalitas kustom di emulator. Ada dua cara untuk melakukannya:

• Menggunakan aplikasi Custom Locale yang dapat diakses dari tab aplikasi. Setelah membuat lokalitas kustom, beralihlah ke lokalitas dengan menyentuh lama nama lokalitas.
• Ubah ke lokalitas kustom dari shell adb, seperti yang dijelaskan di bagian berikut.

Saat Anda menyetel emulator ke lokalitas yang tidak tersedia di image sistem Android, sistem akan ditampilkan dalam bahasa default-nya. Namun demikian, aplikasi Anda telah dilokalkan dengan benar.

Mengubah lokalitas emulator dari shell adb

Untuk mengubah lokalitas di emulator menggunakan shell adb, lakukan hal berikut:

1. Pilih lokalitas yang ingin Anda uji dan tentukan tag bahasa BCP-47nya, seperti fr-CA untuk bahasa Prancis Kanada.
   
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 shell adb (#), 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. Setelah layar utama muncul kembali, luncurkan ulang aplikasi Anda, dan aplikasi akan diluncurkan dengan lokal baru.

Menguji resource default

Untuk menguji apakah aplikasi menyertakan setiap resource string yang diperlukan atau tidak, lakukan hal berikut:

1. Setel emulator atau perangkat ke bahasa yang tidak didukung oleh aplikasi Anda. Misalnya, jika aplikasi memiliki string bahasa Prancis di res/values-fr/ tetapi tidak memiliki string bahasa Spanyol dalam res/values-es/, setel lokalitas emulator ke bahasa Spanyol. (Anda dapat menggunakan aplikasi Lokalitas Kustom untuk menyetel emulator ke lokalitas 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, setel emulator atau perangkat tersebut ke orientasi potret dan lihat apakah aplikasi berjalan.