@capacitor-trancee/app-language

Per-app language preferences

Reference

Android

Per-app language preferences

iOS

How to support per-app language settings in your app

Install

npm install @capacitor-trancee/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>

Called when the user's preferred language changes.

Only available for Web.

| Param | Type | | ------------------ | --------------------------------------------------------------------------- | | eventName | 'languageChanged' | | listenerFunc | LanguageChangedListener |

Returns: Promise<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 |