capacitor-app-language

@capacitor-community/app-language

Per-app language preferences

https://developer.android.com/guide/topics/resources/app-languages

Install

npm install @capacitor-community/app-language
npx cap sync

API

• initialize(...)
• getApplicationLocales()
• setApplicationLocales(...)
• resetApplicationLocales()
• getSystemLocales()
• getOverrideLocaleConfig()
• setOverrideLocaleConfig(...)
• openSettings()
• addListener('languageChanged', ...)
• removeAllListeners()
• Interfaces
• Type Aliases
• Enums

initialize(...)

initialize(options?: InitializeOptions | undefined) => Promise<void>

Initializes the plugin and injects dependencies.

Only available for Web.

Param	Type
options	InitializeOptions

Since: 1.1.0

getApplicationLocales()

getApplicationLocales() => Promise<LocalesResult>

Returns the UI locales for the calling app.

Returns: Promise<LocalesResult>

Since: 1.0.0

setApplicationLocales(...)

setApplicationLocales(options: LocalesOptions) => Promise<void>

Sets the UI locales for the calling app.

Note: Pass an empty locales list to reset to the system locale.

Only available for Android.

Param	Type
options	LocalesOptions

Since: 1.0.0

resetApplicationLocales()

resetApplicationLocales() => Promise<void>

Resets the app locale to the system locale.

Only available for Android.

Since: 1.0.0

getSystemLocales()

getSystemLocales() => Promise<LocalesResult>

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

Returns: Promise<LocalesResult>

Since: 1.0.0

getOverrideLocaleConfig()

getOverrideLocaleConfig() => Promise<LocaleConfigResult>

Returns the override LocaleConfig for the calling app.

Only available for Android (>= 34) and later.

Returns: Promise<LocaleConfigResult>

Since: 1.0.0

setOverrideLocaleConfig(...)

setOverrideLocaleConfig(options: LocaleConfigOptions) => Promise<void>

Sets the override LocaleConfig for the calling app.

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

Only available for Android (>= 34) and later.

Param	Type
options	LocalesOptions

Since: 1.0.0

openSettings()

openSettings() => Promise<void>

Shows settings to allow configuration of per application locale.

Only available for iOS and Android (>= 33) and later.

Since: 1.0.0

addListener('languageChanged', ...)

addListener(eventName: 'languageChanged', listenerFunc: LanguageChangedListener) => Promise<PluginListenerHandle> & PluginListenerHandle

Called when the user's preferred language changes.

Only available for Web.

Param	Type
eventName	'languageChanged'
listenerFunc	LanguageChangedListener

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

Since: 1.1.0

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Only available for Web.

Since: 1.1.0

Interfaces

InitializeOptions

Prop	Type	Description	Since
i18n	I18n	The instance of i18n. Only available for Web.	1.1.0

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

LanguageChangedEvent

Prop	Type	Description	Since
locales	string[]	Returns an array of strings representing the user's preferred languages.	1.1.0

Type Aliases

LocalesResult

{ /** * Returns the locales supported by the specified application. * * @since 1.0.0 */ locales?: string[]; }

LocalesOptions

{ /** * The list of locales. * * @since 1.0.0 */ locales?: string[]; }

LocaleConfigResult

LocalesResult | { /** * Get the status of reading the resource file where the LocaleConfig was stored. * * @since 1.0.0 */ status: Status; }

LocaleConfigOptions

LocalesOptions

LanguageChangedListener

Callback to receive when the user's preferred language changes.

(event: LanguageChangedEvent): void

Enums

Status

Members	Value	Description	Since
SUCCESS	0	Succeeded reading the LocaleConfig structure stored in an XML file.	1.0.0
NOT_SPECIFIED	1	No android:localeConfig tag on pointing to an XML file that stores the LocaleConfig.	1.0.0
PARSING_FAILED	2	Malformed input in the XML file where the LocaleConfig was stored.	1.0.0