Added in API level 33

LocaleManager


public class LocaleManager
extends Object

java.lang.Object
   ↳ 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

LocaleList getApplicationLocales()

Returns the UI locales for the calling app.

LocaleList getApplicationLocales(String appPackageName)

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

LocaleConfig getOverrideLocaleConfig()

Returns the override LocaleConfig for the calling app.

LocaleList getSystemLocales()

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

void setApplicationLocales(LocaleList locales)

Sets the UI locales for the calling app.

void setOverrideLocaleConfig(LocaleConfig localeConfig)

Sets the override LocaleConfig for the calling app.

Inherited methods

Public methods

getApplicationLocales

Added in API level 33
public LocaleList getApplicationLocales ()

Returns the UI locales for the calling app.

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

Returns
LocaleList This value cannot be null.

getApplicationLocales

Added in API level 33
public LocaleList getApplicationLocales (String appPackageName)

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 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.

Returns
LocaleList This value cannot be null.

getOverrideLocaleConfig

Added in API level 34
public LocaleConfig getOverrideLocaleConfig ()

Returns the override LocaleConfig for the calling app.

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

getSystemLocales

Added in API level 33
public LocaleList getSystemLocales ()

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.

Returns
LocaleList This value cannot be null.

setApplicationLocales

Added in API level 33
public void setApplicationLocales (LocaleList locales)

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
public void setOverrideLocaleConfig (LocaleConfig localeConfig)

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.