Preferensi bahasa per aplikasi

Dalam banyak kasus, pengguna multibahasa menyetel bahasa sistemnya ke satu bahasa, seperti bahasa Inggris, tetapi mereka ingin memilih bahasa lain untuk aplikasi tertentu, seperti Belanda, Mandarin, atau Hindi. Untuk membantu aplikasi memberikan pengalaman yang lebih baik bagi pengguna ini, Android 13 memperkenalkan fitur berikut untuk aplikasi yang mendukung beberapa bahasa:

• Setelan sistem yang memungkinkan pengguna memilih bahasa pilihan untuk setiap aplikasi di lokasi terpusat.

  Aplikasi harus mendeklarasikan atribut android:localeConfig dalam manifes aplikasi untuk memberi tahu sistem bahwa aplikasi mendukung beberapa bahasa. Untuk mempelajari lebih lanjut, lihat petunjuk untuk membuat file resource dan mendeklarasikannya di file manifes aplikasi.

• API yang memungkinkan aplikasi untuk menyetel bahasa lain saat runtime untuk digunakan di antarmuka pengguna.

  Aplikasi yang menggunakan pemilih bahasa kustom dalam aplikasi harus menggunakan API baru ini untuk memastikan bahwa pengguna memiliki pengalaman pengguna yang konsisten, di mana pun mereka memilih preferensi bahasa mereka. API baru ini tidak hanya membantu Anda mengurangi jumlah kode boilerplate, tetapi juga mendukung APK terpisah dan Auto Backup untuk Aplikasi guna menyimpan setelan bahasa pengguna tingkat aplikasi.

  Untuk kompatibilitas mundur dengan versi Android sebelumnya, API juga tersedia di AndroidX. Sebaiknya gunakan Appcompat 1.6.0-alpha04 atau versi lebih tinggi.

Aplikasi yang tidak mendukung beberapa bahasa tidak akan terpengaruh oleh perubahan ini.

Ringkasan penerapan fitur ini

Tabel berikut menunjukkan penerapan yang direkomendasikan berdasarkan kasus penggunaan yang berbeda.

Kasus penggunaan	Penerapan yang direkomendasikan
Aplikasi Anda tidak memiliki pemilih bahasa dalam aplikasi	Gunakan atribut android:localeConfig di manifes aplikasi Anda untuk menambahkan bahasa aplikasi ke setelan ponsel. Secara opsional, jika Anda ingin menambahkan pemilih bahasa dalam aplikasi: gunakan library AndroidX dan pilih implementasi API kami untuk mendukung kompatibilitas mundur melalui autoStoreLocales.
Aplikasi Anda sudah memiliki pemilih bahasa dalam aplikasi	Gunakan atribut android:localeConfig di manifes aplikasi Anda untuk menambahkan bahasa aplikasi ke setelan ponsel. Migrasikan logika kustom aplikasi Anda untuk menggunakan API baru guna memastikan pengguna melihat pengalaman yang konsisten. Tangani corner case berikut: Panggil AppCompatDelegate.setApplicationLocales() saat pertama kali aplikasi dijalankan di perangkat yang menjalankan Android 13. Panggil AppCompatDelegate.setApplicationLocales() untuk memberikan lokalitas yang diminta pengguna dan sudah ada sebelumnya ke sistem untuk kasus berikut: Jika Anda mengikutsertakan aplikasi ke penyimpanan otomatis untuk Android 12 (API level 32) dan versi lebih lama Jika aplikasi Anda perlu memigrasikan data dari lokasi penyimpanan cadangan khusus

Setelan sistem untuk pengguna

Android 13 menambahkan lokasi terpusat di setelan ponsel untuk menyetel preferensi bahasa per aplikasi. Untuk memastikan bahasa aplikasi dapat dikonfigurasi di setelan sistem di perangkat yang menjalankan Android 13, buat file XML locales_config dan tambahkan manifes aplikasi Anda menggunakan atribut android:localeConfig. Menghapus entri manifes android:localeConfig yang menandakan bahwa pengguna tidak seharusnya dapat menyetel bahasa aplikasi Anda, terlepas dari bahasa sistem mereka dalam setelan ponsel.

Penting: Jika Anda mengalami perilaku yang tidak diharapkan saat menguji fitur ini, periksa masalah umum saat ini terkait UI setelan ponsel untuk mengetahui kemungkinan penyebabnya.

Menggunakan android:localeConfig untuk menambahkan bahasa yang didukung ke setelan ponsel

Untuk menambahkan bahasa yang didukung aplikasi Anda ke setelan ponsel pengguna:

1. Buat file bernama res/xml/locales_config.xml, lalu tentukan bahasa aplikasi Anda sebagai berikut:

   <?xml version="1.0" encoding="utf-8"?>
   <locale-config xmlns:android="http://schemas.android.com/apk/res/android">
      <locale android:name="ja"/>
      <locale android:name="fr"/>
      <locale android:name="en"/>
   </locale-config>
   

2. Di manifes, tambahkan baris yang menunjuk ke file baru ini:

   <manifest
       ...
       <application
           ...
           android:localeConfig="@xml/locales_config">
       </application>
   </manifest>
   

Cara pengguna memilih bahasa aplikasi di setelan sistem

Pengguna dapat memilih bahasa pilihan mereka untuk setiap aplikasi melalui setelan sistem baru. Pengguna dapat mengakses setelan ini dengan dua cara berbeda:

• Akses melalui setelan Sistem

  Setelan > Sistem > Bahasa & Input > Bahasa Aplikasi > (pilih aplikasi)

• Akses melalui setelan Aplikasi

  Setelan > Aplikasi > (pilih aplikasi) > Bahasa

Masalah umum

Ada beberapa masalah umum yang perlu diingat saat Anda menguji aplikasi.

• Ada masalah umum pada AGP 7.3.0-alpha07 yang dapat menyebabkan penautan resource gagal dengan android:localeConfig. Untuk mengatasi hal ini, gunakan versi AGP yang lebih lama. Masalah ini akan diatasi dalam rilis mendatang.

Menangani pemilih bahasa dalam aplikasi

Untuk aplikasi yang telah memiliki pemilih bahasa dalam aplikasi atau ingin menggunakannya, gunakan API baru, bukan logika aplikasi kustom, untuk menangani setelan dan mendapatkan bahasa pilihan pengguna untuk aplikasi Anda.

Untuk kompatibilitas mundur dengan versi Android sebelumnya, sebaiknya gunakan support library AndroidX saat menerapkan pemilih bahasa dalam aplikasi. Namun, Anda juga dapat menerapkan API framework secara langsung jika perlu.

Implementasi menggunakan support library AndroidX

Gunakan metode setApplicationLocales() di Appcompat 1.6.0-alpha04 atau versi lebih baru.

Misalnya, untuk menyetel bahasa pilihan pengguna, Anda akan meminta pengguna untuk memilih lokalitas dalam pemilih bahasa, lalu menyetel nilai tersebut dalam sistem:

Kotlin

val appLocale: LocaleListCompat = LocaleListCompat.forLanguageTags("xx-YY")
// Call this on the main thread as it may require Activity.restart()
AppCompatDelegate.setApplicationLocales(appLocale)

Java

LocaleListCompat appLocale = LocaleListCompat.forLanguageTags("xx-YY");
// Call this on the main thread as it may require Activity.restart()
AppCompatDelegate.setApplicationLocales(appLocale);

Mendukung Android 12 dan versi lebih lama

Untuk mendukung perangkat yang menjalankan Android 12 (API level 32) dan versi lebih lama, beri tahu AndroidX untuk menangani penyimpanan lokalitas dengan menetapkan nilai autoStoreLocales ke true dan android:enabled ke false dalam entri manifes untuk layanan AppLocalesMetadataHolderService aplikasi Anda, seperti yang ditunjukkan dalam cuplikan kode berikut:

<application
  ...
  <service
    android:name="androidx.appcompat.app.AppLocalesMetadataHolderService"
    android:enabled="false"
    android:exported="false">
    <meta-data
      android:name="autoStoreLocales"
      android:value="true" />
  </service>
  ...
</application>

Perhatikan bahwa menyetel nilai autoStoreLocales ke true akan menyebabkan pembacaan blocking di thread utama dan dapat menyebabkan pelanggaran StrictMode diskRead dan diskWrite jika Anda melakukan logging pada pelanggaran thread. Lihat AppCompatDelegate.setApplicationLocales() untuk mengetahui informasi selengkapnya.

Penanganan penyimpanan kustom

Menghapus entri manifes atau menetapkan autoStoreLocales ke false menandakan bahwa Anda menangani penyimpanan Anda sendiri. Dalam hal ini, Anda harus menyediakan lokalitas yang disimpan sebelum onCreate dalam siklus proses aktivitas dan panggilan gate ke AppCompatDelegate.setApplicationLocales() di Android 12 (API level 32) atau versi lebih rendah.

Jika aplikasi Anda memiliki lokasi penyimpanan lokalitas kustom, sebaiknya gunakan pengalihan satu kali antara solusi penyimpanan lokalitas kustom dan autoStoreLocales sehingga pengguna dapat terus menikmati aplikasi Anda dalam bahasa yang mereka inginkan. Hal ini terutama berlaku jika aplikasi Anda pertama kali dijalankan setelah perangkat diupgrade ke Android 13. Dalam hal ini, Anda dapat memberikan lokalitas yang diminta oleh pengguna yang sudah ada sebelumnya dengan mengambil lokalitas dari penyimpanan kustom Anda dan meneruskan lokalitas ke AppCompatDelegate.setApplicationLocales().

Implementasi menggunakan API framework Android

Meskipun kami sangat menyarankan Anda menggunakan support library AndroidX untuk menerapkan pemilih bahasa dalam aplikasi, Anda juga dapat menggunakan metode setApplicationLocales() dan getApplicationLocales() dalam framework Android untuk perangkat yang menjalankan Android 13.

Misalnya, untuk menyetel bahasa pilihan pengguna, Anda akan meminta pengguna untuk memilih lokalitas dalam pemilih bahasa, lalu menyetel nilai tersebut dalam sistem:

// 1. Inside an activity, in-app language picker gets an input locale "xx-YY"
// 2. App calls the API to set its locale
mContext.getSystemService(LocaleManager.class
    ).setApplicationLocales(newLocaleList(Locale.forLanguageTag("xx-YY")));
// 3. The system updates the locale and restarts the app, including any configuration updates
// 4. The app is now displayed in "xx-YY" language

Agar bahasa pilihan pengguna saat ini ditampilkan di pemilih bahasa, aplikasi Anda dapat memperoleh kembali nilai dari sistem:

// 1. App calls the API to get the preferred locale
LocaleList currentAppLocales =
    mContext.getSystemService(LocaleManager.class).getApplicationLocales();
// 2. App uses the returned LocaleList to display languages to the user

Praktik terbaik tambahan

Perhatikan praktik terbaik berikut.

Mempertimbangkan bahasa saat memanggil intent di aplikasi lain

Intent yang berfokus pada bahasa dapat memungkinkan Anda menentukan bahasa yang ingin digunakan oleh aplikasi yang dipanggil. Salah satu contohnya adalah fitur EXTRA_LANGUAGE Speech Recognizer API.

Mempertimbangkan header Terima Bahasa untuk tab Kustom Chrome

Pertimbangkan untuk menambahkan Header Terima Bahasa melalui Browser.EXTRA_HEADERS untuk membuka halaman web dalam bahasa aplikasi Anda saat memanggil tab Kustom Chrome.