Android Developers Blog: Per-App Language Preferences - Part 1

Platform Android Studio Google Play Jetpack Kotlin Docs News

Platform Android Studio Google Play Jetpack Kotlin Docs News

Android Developers Blog

The latest Android and Google Play news for app and game developers.

Per-App Language Preferences - Part 1

22 ноября 2022

Posted by Neelansh Sahai Android Developer Relations Engineer (on Twitter and LinkedIn)

What if you have a set of users who are quite fluent in English, Hindi, and Spanish, and they have a news app on their phones and prefer to read the news in Hindi? For their texting app, they prefer Spanish as they have some friends and family who they text with in Spanish. But for ease of access, they still prefer their device to be in English. Now there are many such use-cases where the users might want their app languages to be different from their system language. Interesting! Starting with Android 13, we have included one of the most-requested features from users, Per-App Language Preferences. It lets users switch app languages from System settings, providing users with better control over their language choices for different apps, irrespective of the system language.

A cellphone screen displaying App language preferences in system settings for the YouTube app

Build for your multilingual users This blog focuses on how to integrate the Per-App Language Preferences API in your app to provide your users the flexibility to choose different languages for different apps.1. Users can change the language settings from system settings by selecting: Settings → System → Languages & Input → App Languages → [Select the desired App] → [Select the desired Language]

NOTE: Only those apps that have opted in for the feature by specifying the locale_config.xml file (more on this below), will appear in system settings.

A cellphone screen demonstrating finding the language settings from system settings by selecting Settings → System → Languages & Input → App Languages → [Select the desired App] → [Select the desired Language]

2. If your app already has an in-app language picker, you can integrate the Per-App Language Preferences API to leverage the full platform support. For pre-Android 13 users, the system settings won’t be visible, but developers can still provide an in-app language picker.

A cellphone screen demonstrating integrating the Per-App Language prefences API for an app which already has an in-app language picker

How to integrate this feature in your app?

There are 5 steps that need to be followed while working on the Per-App Language Preferences feature, listed here →

1. Create locale_config.xml file

Create a new file in values/xml/ directory and name it as locale_config.xml. This file should contain a list of all the locales that are supported by the app. The list element should be a string containing a locale tag.

NOTE: The locale tags must follow the BCP47 syntax, which is usually {language subtag}–{script subtag}–{country subtag}. Anything other than that will be filtered out by the system and won't be visible in the system settings.

locale_config.xml

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

<locale android:name="en"/>

<locale android:name="ja-JP"/>

<locale android:name="zh-Hans-MO"/>

<locale android:name="zh-Hant-TW"/>
...
</locale-config>

2. Add the locale_config in the AndroidManifest.xml
locale_config.xmlAndroidManifest.xml
AndroidManifest.xml

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

3. Add the libraries

Use the latest version of AppCompat Library

build.gradle (app)

def latestAppCompatVersion = “1.6.0-rc01”

dependencies {
...
implementation "androidx.appcompat:appcompat:$latestAppCompatVersion"
implementation "androidx.appcompat:appcompat-resources:$latestAppCompatVersion"
...
}

4. Use AndroidX APIs

Use the APIs in your code to set and get the app locales.

MainActivity.kt

val appLocale: LocaleListCompat = LocaleListCompat.forLanguageTags("xx-YY")

// Call this on the main thread as it may require Activity.restart()
AppCompatDelegate.setApplicationLocales(appLocale)

// Call this to get the selected locale and display it in your App
val selectedLocale = AppCompatDelegate.getApplicationLocales()[0]

NOTE: These APIs are also backward compatible, so even if the app is being used on Android 12 or lower, the APIs would still behave the same, and no additional checks for OS versions are required in your code.

5. Delegate storage to AndroidX

Let AndroidX handle the locale storage so that the user's preference persists.

AndroidManifest.xml

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

Steps 3, 4, & 5 above demonstrate the minimum components needed to create an in-app language picker.

And with this, your app can now support locale switching.

Additional things to take care of while migrating to the API

Earlier, developers had to handle the user's preferences on their own, either by using SharedPreferences, storing the data on a server, or other app logic. With the new APIs, there is no need to handle this separately. So when you are using these APIs, AndroidX is already taking care of the storage part, but what happens when the app is opened for the first time after a user updates their device to Android 13 or higher?

In this case, the system won’t be aware of the user’s preferences for the app language and thus it will map the app to the default system language. To avoid this, developers need to add some one-time migration logic so that their users don’t have to set the language again when they update the app.

Here is an example of the migration that can be done if you were using SharedPreferences earlier to store the user’s language preference.

// Specify the constants to be used in the below code snippets

companion object {

// Constants for SharedPreference File
const val PREFERENCE_NAME = "shared_preference"
const val PREFERENCE_MODE = Context.MODE_PRIVATE

// Constants for SharedPreference Keys
const val FIRST_TIME_MIGRATION = "first_time_migration"
const val SELECTED_LANGUAGE = "selected_language"

// Constants for SharedPreference Values
const val STATUS_DONE = "status_done"
}

// Utility method to put a string in a SharedPreference
private fun putString(key: String, value: String) {
val editor = getSharedPreferences(PREFERENCE_NAME, PREFERENCE_MODE).edit()
editor.putString(key, value)
editor.apply()
}

// Utility method to get a string from a SharedPreference
private fun getString(key: String): String? {
val preference = getSharedPreferences(PREFERENCE_NAME, PREFERENCE_MODE)
return preference.getString(key, null)
}

// Check if the migration has already been done or not
if (getString(FIRST_TIME_MIGRATION) != STATUS_DONE) {

   // Fetch the selected language from wherever it was stored. In this case it’s SharedPref
   // In this case let’s assume that it was stored in a key named SELECTED_LANGUAGE
getString(SELECTED_LANGUAGE)?.let { it →

      // Set this locale using the AndroidX library that will handle the storage itself
val localeList = LocaleListCompat.forLanguageTags(it)
AppCompatDelegate.setApplicationLocales(localeList)

      // Set the migration flag to ensure that this is executed only once
putString(FIRST_TIME_MIGRATION, STATUS_DONE)
}
}

What flexibility does the feature provide to the users and developers?

Here are a few things that might prove to be beneficial for you users.

All devices running Android 13 or higher will have a common place for users to discover and change the language of their apps.
Although the system settings are limited to the devices running Android 13 or higher, the AndroidX APIs are backwards compatible. Thus, there is no requirement to add OS Version checks in your code while building for your multilingual users.
Developers do not need to handle configuration changes separately or worry about storing the user's selected language every time. The API handles configuration changes and stores the language preferences for you.
Works with other Android features like Backup and restore. If a user switches to a new device and restores the previously backed up data, your app will retain the user’s last preferred language, thus providing your users with a better and more seamless experience.

Recap

With that, most parts of the feature are covered. So let’s have a quick recap on what we discussed in today’s read.

A quick read on what Per-App Language Preferences offer to multilingual users and app developers.
What end users will see on their devices.
How to migrate your app to the Per-App Language Preferences APIs.
A few things that need to be taken care of while migrating to the APIs to ensure a better user experience.
Lastly, the benefits that end users and developers can leverage from this feature.

References

Per-App Language Preferences
Sample App ( Compose )
Sample App ( Views )
Per-App Language Preferences (YouTube Video)
Per-App Language Preferences - Part 2