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 Playres/layout/
: direktori wajib berisi file XML yang menentukan tata letak defaultres/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 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:
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
.
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 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. 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:
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();
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:
- Pilih lokalitas yang ingin Anda uji dan tentukan tag bahasa BCP-47nya,
seperti
fr-CA
untuk bahasa Prancis Kanada.
- 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 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:
- 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 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.