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 Kotlin atau 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.
Sebaiknya gunakan framework resource Android untuk memisahkan aspek yang dilokalkan dari aplikasi Anda sebanyak mungkin dari fungsi aplikasi inti:
- 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 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. Topik ini tidak membahas cara melokalkan kode berbasis Java atau Kotlin.
Untuk panduan pelokalan lokal string dalam aplikasi Anda, lihat Mendukung Bahasa yang Berbeda.
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.
Topik 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 lokalitas 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 lokalitas tempat Anda tidak memberikan
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 di bawah 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, 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 sekumpulan file resource default
yang berisi semua resource yang dipanggil oleh aplikasi Anda
(tata letak, drawable, animasi, dan sebagainya aktif). Untuk informasi tentang pengujian, lihat
Menguji 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 folderres/anim-<qualifiers>
)res/xml/
(diperlukan jika Anda memiliki folderres/xml-<qualifiers>
)res/raw/
(diperlukan jika Anda memiliki folderres/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 lokalitas 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. 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:
res/values/strings.xml
Berisi teks bahasa Inggris untuk semua string yang digunakan aplikasi tersebut, termasuk teks untuk string bernamatitle
.res/values-fr/strings.xml
Berisi teks bahasa Prancis untuk semua string, termasuktitle
.res/values-ja/strings.xml
Berisi teks bahasa Jepang untuk semua string kecualititle
.
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 fileres/values/strings.xml
. - Jika perangkat disetel ke bahasa Prancis, Android akan memuat
title
dari fileres/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 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 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 menyertakantext_a
dalam bahasa default aplikasi, dalam hal ini bahasa Inggris.res/values-hi/strings.xml
, yang menyertakantext_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. Lihat Cara Android Menemukan Resource yang Paling Cocok untuk deskripsi yang lebih terperinci tentang proses tersebut. Semua penentu akan dijelaskan dan dicantumkan dalam urutan prioritas di Tabel 2 tentang Menyediakan Resource Alternatif.
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 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 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, 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.
Menandai 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 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
Merancang aplikasi Anda agar dapat berfungsi di semua lokalitas
Anda tidak dapat mengasumsikan apa pun tentang perangkat yang digunakan pengguna untuk menjalankan aplikasi Anda. Perangkat mungkin memiliki hardware yang tidak perkirakan sebelumnya, atau mungkin disetel ke lokalitas 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 lokalitas 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 menyusun ulang tata letak agar sesuai dengan bahasa tertentu (misalnya, Jerman),
Anda dapat membuat tata letak alternatif untuk bahasa tersebut (misalnya,
res/layout-de/main.xml
). Namun, melakukan hal 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 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, 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 lokalitas secara manual
Anda dapat mencari lokalitas menggunakan objek Context
yang disediakan oleh Android:
Kotlin
val primaryLocale: Locale = context.resources.configuration.locales[0] val locale: String = primaryLocale.displayName
Java
Locale primaryLocale = context.getResources().getConfiguration().getLocales().get(0); String locale = primaryLocale.getDisplayName();
Gunakan Layanan Terjemahan Aplikasi
Layanan Terjemahan 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 dapat 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 lokalitas kustom
Lokalitas "kustom" adalah kombinasi bahasa/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 Lokalitas Kustom, yang dapat diakses dari tab aplikasi. (Setelah selesai dibuat, beralihlah ke lokalitas kustom dengan menekan dan menahan nama lokalitas tersebut.)
- Mengubah ke lokal kustom dari shell adb, seperti yang dijelaskan di bawah ini.
Saat Anda menyetel emulator ke lokalitas 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 lokalitas di emulator dengan menggunakan shell adb.
- Pilih lokalitas yang ingin Anda uji dan tentukan tag bahasa BCP-47nya,
misalnya, bahasa Prancis Kanada adalah
fr-CA
.
- Luncurkan emulator.
- 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
- 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. Setelah Layar utama muncul kembali, luncurkan ulang aplikasi Anda, dan aplikasi akan diluncurkan dengan lokalitas baru.
Menguji resource default
Berikut ini cara menguji apakah aplikasi menyertakan setiap resource string yang diperlukan atau tidak:
- 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 dalamres/values-es/
, setel lokalitas emulator ke bahasa Spanyol. (Anda dapat menggunakan aplikasi Lokalitas Kustom untuk menyetel emulator ke lokalitas yang tidak didukung.) - Jalankan aplikasi.
- 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.