Beyond Scanning: Meet the All-in-One AI Document Assistant by Digitify Vision Technology

 

Mastering Per-App Language Preferences: From Android 10 to Android 13+

One of the most requested features by users is the ability to use an app in a language different from the system language. While Android 13 (API 33) introduced "Per-App Language" settings at the system level, implementing this backward-compatibly for older devices like Android 10 (API 29) used to be a challenge involving manual configuration wrapping.

Today, thanks to AppCompat 1.6.0+, we have a unified, standard way to handle this. Here is the modern guide to implementing seamless language switching.

---

The Architecture: How it Works

On Android 13 and above, the system handles the storage and application of your app's locale. On older versions, the AppCompat library manages this behavior by storing your preference in an internal XML file and injecting the resources during the activity lifecycle.

---

Step 1: The Locale Helper Utility

Instead of scattering logic across your app, use a clean LocaleHelper object. This handles the distinction between the system LocaleManager (API 33+) and the library AppCompatDelegate (Legacy).

Kotlin

object LocaleHelper {
    /**
     * Applies the chosen language code (e.g., "en", "hi", "es") 
     */
    fun applyLanguage(context: Context, languageCode: String) {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
            // Android 13+ (System level support)
            val localeManager = context.getSystemService(LocaleManager::class.java)
            localeManager.applicationLocales = LocaleList.forLanguageTags(languageCode)
        } else {
            // API 29-32 (Library level support via AppCompat)
            val appLocale: LocaleListCompat = LocaleListCompat.forLanguageTags(languageCode)
            AppCompatDelegate.setApplicationLocales(appLocale)
        }
    }

    /**
     * Detects the currently active language
     */
    fun getActiveLanguage(context: Context): String {
        val locales = AppCompatDelegate.getApplicationLocales()
        return if (!locales.isEmpty) {
            locales[0]?.language ?: "en"
        } else {
            // Fallback to configuration for first-time launch
            context.resources.configuration.locales[0].language ?: "en"
        }
    }
}

---

Step 2: The Crucial Manifest Requirement

For versions below Android 13, AppCompat needs a way to "remember" the language choice after the app is killed or the device is restarted. You must declare this service inside your <application> tag in AndroidManifest.xml.

Without this, your language settings will reset every time the app closes on API 29.

XML

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

</application>

---

Step 3: Implementation in MainActivity

When using Jetpack Compose or View-based activities, ensure your activity inherits from AppCompatActivity. This is vital because AppCompatActivity contains the logic to intercept and apply the localized resources.

Kotlin

class MainActivity : androidx.appcompat.app.AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        setContent {
            // Detect current language using our Helper
            val currentLanguage = remember { LocaleHelper.getActiveLanguage(this) }

            MainAppScreen(
                currentLanguage = currentLanguage,
                onLanguageChange = { newLang ->
                    // The library handles activity recreation automatically
                    LocaleHelper.applyLanguage(this@MainActivity, newLang)
                }
            )
        }
    }
}

---

Step 4: Enabling System-Level Settings (Android 13+)

To allow users to see your app's language options directly in the Android System Settings, you must provide a locales_config.xml.

1. Create res/xml/locales_config.xml:

   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="hi"/>
      <locale android:name="es"/>
   </locale-config>
   

2. Link it in Manifest:

   XML

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

---

Summary Checklist for Success

• Library Version: Use androidx.appcompat:appcompat:1.6.0 or higher.

• Activity Type: Use AppCompatActivity for full backward compatibility.

• Persistence: Verify the AppLocalesMetadataHolderService is in the Manifest.

• No Manual Recreate: Calling setApplicationLocales() triggers an automatic, optimized activity recreation. You do not need to call recreate() manually.

By following this standard approach, you provide a premium, localized experience for all users—whether they are on the latest Android 16 or a legacy Android 10 device.

Updated answer:

No "Split Brain": You don't have to worry about the DataStore value being different from what the system thinks is active.

• System Integration: On Android 13+, if the user goes to Settings > System > Languages > App Languages, they will see your app listed there with the correct language selected. If they change it there, your app will reflect it automatically on the next launch.

• Consistency: It uses the same mechanism for all versions of Android (via AppCompat), so you don't need different logic for old vs. new devices.

Summary: The "remembering" is now handled by the Android System/AppCompat library itself, triggered by the autoStoreLocales="true" setting in your Manifest.

    <meta-data

        android:name="autoStoreLocales"

        android:value="true" />

    

// Update local state for instant UI feedback
currentLanguage = newLang
// Use LocaleHelper to apply language; AppCompat handles persistence via autoStoreLocales in Manifest
LocaleHelper.applyLanguage(this@MainActivity, newLang)

fun applyLanguage(context: Context, languageCode: String) {
    val appLocale: LocaleListCompat = LocaleListCompat.forLanguageTags(languageCode)
    AppCompatDelegate.setApplicationLocales(appLocale)

} 

References:

https://developer.android.com/guide/topics/resources/localization