Added in API level 33

LocaleManager

open class LocaleManager
kotlin.Any
   ↳ android.app.LocaleManager

This class gives access to system locale services. These services allow applications to control granular locale settings (such as per-app locales) or override their list of supported locales while running.

Third party applications should treat this as a write-side surface, and continue reading locales via their in-process LocaleLists.

Summary

Public methods
open LocaleList

Returns the UI locales for the calling app.
open LocaleList
getApplicationLocales(appPackageName: String)

Returns the current UI locales for a specified app (described by package name).
open LocaleConfig?

Returns the override LocaleConfig for the calling app.
open LocaleList

Returns the current system locales, ignoring app-specific overrides.
open Unit

Sets the UI locales for the calling app.
open Unit

Sets the override LocaleConfig for the calling app.

Public methods

getApplicationLocales

Added in API level 33
open fun getApplicationLocales(): LocaleList

Returns the UI locales for the calling app.

Returns a LocaleList#getEmptyLocaleList() if no app-specific locales are set.

Return
LocaleList This value cannot be null.

getApplicationLocales

Added in API level 33
open fun getApplicationLocales(appPackageName: String): LocaleList

Returns the current UI locales for a specified app (described by package name).

Returns a LocaleList#getEmptyLocaleList() if no app-specific locales are set.

This API can be used by an app's installer (per android.content.pm.InstallSourceInfo#getInstallingPackageName) to retrieve the app's locales.

This API can be used by the current input method to retrieve locales of another packages. All other cases require android.Manifest.permission#READ_APP_SPECIFIC_LOCALES. Apps should generally retrieve their own locales via their in-process LocaleLists, or by calling getApplicationLocales().

Parameters
appPackageName String: the package name of the app for which to retrieve the locales. This value cannot be null.
Return
LocaleList This value cannot be null.

getOverrideLocaleConfig

Added in API level 34
open fun getOverrideLocaleConfig(): LocaleConfig?

Returns the override LocaleConfig for the calling app.

Return
LocaleConfig? the override LocaleConfig, or null if the LocaleConfig isn't overridden.

getSystemLocales

Added in API level 33
open fun getSystemLocales(): LocaleList

Returns the current system locales, ignoring app-specific overrides.

Note: Apps should generally access the user's locale preferences as indicated in their in-process LocaleLists. However, in case an app-specific locale is set, this method helps cater to rare use-cases which might require specifically knowing the system locale.

Note: This API is not user-aware. It returns the system locales for the foreground user.

Return
LocaleList This value cannot be null.

setApplicationLocales

Added in API level 33
open fun setApplicationLocales(locales: LocaleList): Unit

Sets the UI locales for the calling app.

Pass a LocaleList#getEmptyLocaleList() to reset to the system locale.

Note: Changes to app locales will result in a configuration change (and potentially an Activity lifecycle event) being applied to the calling application. For more information, see the section on handling configuration changes. The set locales are persisted; they are backed up if the user has enabled Backup & Restore.

Note: Users' locale preferences are passed to applications by creating a union of any app-specific locales and system locales, with the app-specific locales appearing first. Language resources are then chosen per usual (as described in the section on locale resolution).

Parameters
locales LocaleList: the desired locales for the calling app. This value cannot be null.

setOverrideLocaleConfig

Added in API level 34
open fun setOverrideLocaleConfig(localeConfig: LocaleConfig?): Unit

Sets the override LocaleConfig for the calling app.

Note: Only the app itself with the same user can override its own LocaleConfig.

Note: This function takes in a LocaleConfig which is intended to override the original config in the application's resources. This LocaleConfig will become the override config, and stored in a system file for future access.

Note: Using this function, applications can update their list of supported locales while running, without an update of the application's software. For more information, see the section on dynamic updates for an app's localeConfig.

Applications can remove the override LocaleConfig with a null object.

Parameters
localeConfig LocaleConfig?: the desired LocaleConfig for the calling app. This value may be null.