Inheriting your app's language preference

Introduction

The Zendesk SDK automatically follows your app's language settings using standard Android APIs. You don't need to do any SDK-specific localization work to make the SDK UI appear in the language your app has selected. The SDK reads the locale specified in Android's per-app language preferences and renders its UI in that language.

SDK strings are available in 43 languages. To override individual SDK strings, see Localizing the UI.

Setting the app locale

To render your app and the SDK in a specific language, set the app's locale with AppCompatDelegate.setApplicationLocales(...):

import androidx.appcompat.app.AppCompatDelegate
import androidx.core.os.LocaleListCompat

// Set the app locale to French
AppCompatDelegate.setApplicationLocales(LocaleListCompat.forLanguageTags("fr"))

To revert to the system default locale, pass an empty locale list:

AppCompatDelegate.setApplicationLocales(LocaleListCompat.getEmptyLocaleList())

How activity recreation affects the SDK

On API level 32 or lower, the AppCompat locale API automatically recreates only AppCompatActivity instances after a locale change. Activities that subclass Activity or ComponentActivity are not recreated automatically.

This limitation does not affect the SDK. The Zendesk SDK always opens its UI in its own AppCompatActivity based MessagingActivity. After a locale change, Android recreates this activity and applies the new language.

On API level 33 or higher, the platform's per-app language API handles recreation for all activity types.

Supporting the system Settings language option (API 33 or higher)

On Android 13 or later (API level 33 or higher), users can change an app's language from system settings. To make this option available for your app, declare a locale configuration in your AndroidManifest.xml:

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

Then create res/xml/locales_config.xml listing the languages your app supports:

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

Generating the locale configuration automatically with Android Gradle Plugin 8.1 or later

Instead of maintaining locales_config.xml manually, Android Gradle Plugin 8.1 and above can generate it automatically from your app's values-* resource folders. Enable it in your module's build.gradle or build.gradle.kts:

androidResources {
    generateLocaleConfig = true
}

When enabled, AGP generates the locale configuration from the values-* directories in your app (for example, values-fr, values-es) and adds it to the manifest for you.

When a user changes the language from system settings on API level 33 or higher, the SDK follows that selection automatically.

Persisting the locale across app restarts (API 32 and below)

On API level 32 or lower, there is no system per-app language setting, so your app must remember the locale the user selected with setApplicationLocales(...). To have AndroidX persist and restore the locale automatically across process restarts, add the AppLocalesMetadataHolderService to your AndroidManifest.xml:

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

With autoStoreLocales set to true, the AppCompat locale API stores the selected locale and reapplies it the next time your app starts. After a restart, the SDK opens in the user's chosen language.

Tip: If you prefer to manage persistence yourself (for example, to synchronize the locale with your own backend-side user preference), leave autoStoreLocales as false and call AppCompatDelegate.setApplicationLocales(...) yourself on app start with the stored value.

FAQ

Q: What happens if the app's language isn't one of the SDK's supported languages?
A: If the locale your app selects isn't in the list of SDK-supported languages, the SDK falls back to the default language (English) for its UI strings. The rest of your app continues to render the selected locale, but the SDK UI renders in English.