@capawesome/capacitor-app-language 0.0.1

package/CapawesomeCapacitorAppLanguage.podspec

@@ -0,0 +1,17 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'CapawesomeCapacitorAppLanguage'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license']
+  s.homepage = package['repository']['url']
+  s.author = package['author']
+  s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
+  s.source_files = 'ios/Plugin/**/*.{swift,h,m,c,cc,mm,cpp}'
+  s.ios.deployment_target = '15.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.1'
+end

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robin Genz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Package.swift

@@ -0,0 +1,28 @@
+// swift-tools-version: 5.9
+import PackageDescription
+
+let package = Package(
+    name: "CapawesomeCapacitorAppLanguage",
+    platforms: [.iOS(.v15)],
+    products: [
+        .library(
+            name: "CapawesomeCapacitorAppLanguage",
+            targets: ["AppLanguagePlugin"])
+    ],
+    dependencies: [
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
+    ],
+    targets: [
+        .target(
+            name: "AppLanguagePlugin",
+            dependencies: [
+                .product(name: "Capacitor", package: "capacitor-swift-pm"),
+                .product(name: "Cordova", package: "capacitor-swift-pm")
+            ],
+            path: "ios/Plugin"),
+        .testTarget(
+            name: "AppLanguagePluginTests",
+            dependencies: ["AppLanguagePlugin"],
+            path: "ios/PluginTests")
+    ]
+)

package/README.md

@@ -0,0 +1,269 @@
+# @capawesome/capacitor-app-language
+
+Capacitor plugin to manage the app's own language override, independent of the device language.
+
+<div class="capawesome-z29o10a">
+  <a href="https://cloud.capawesome.io/" target="_blank">
+    <img alt="Deliver Live Updates to your Capacitor app with Capawesome Cloud" src="https://cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png?t=1" />
+  </a>
+</div>
+
+## Features
+
+- 🌐 **Language override**: Set the app's language independently of the device language (Android).
+- 🔎 **Read language**: Read the app's current language override.
+- ♻️ **Reset**: Clear the override so the app follows the device language again (Android).
+- ⚙️ **Settings**: Deep-link to the app's system settings page where the user can change the app language.
+- 📦 **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
+- 🔁 **Up-to-date**: Always supports the latest Capacitor version.
+- 🔗 **Compatibility**: Works alongside the [Localization](https://capawesome.io/plugins/localization/) plugin, which reads the user's localization preferences.
+
+Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!
+
+## Newsletter
+
+Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
+
+## Compatibility
+
+| Plugin Version | Capacitor Version | Status         |
+| -------------- | ----------------- | -------------- |
+| 0.x.x          | >=8.x.x           | Active support |
+
+## Installation
+
+You can use our **AI-Assisted Setup** to install the plugin.
+Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:
+
+```bash
+npx skills add capawesome-team/skills --skill capacitor-plugins
+```
+
+Then use the following prompt:
+
+```
+ Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-app-language` plugin in my project.
+```
+
+If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:
+
+```bash
+npm install @capawesome/capacitor-app-language
+npx cap sync
+```
+
+This plugin only affects **natively rendered** strings (e.g. permission dialogs, notifications, or plugin-presented sheets). The language of your web UI should be handled by your app's i18n library.
+
+### Android
+
+#### Variables
+
+This plugin will use the following project variables (defined in your app's `variables.gradle` file):
+
+- `$androidxAppCompatVersion` version of `androidx.appcompat:appcompat` (default: `1.7.1`)
+
+#### Locale Configuration
+
+To integrate the app language into the system settings (Android 13+), declare the supported locales in a `res/xml/locales_config.xml` file and reference it from the `<application>` tag in your `AndroidManifest.xml`:
+
+```xml
+<!-- res/xml/locales_config.xml -->
+<?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="de" />
+</locale-config>
+```
+
+```xml
+<application
+    ...
+    android:localeConfig="@xml/locales_config">
+```
+
+To persist the selected language across app restarts on Android 12 and below, add the following `<service>` inside the `<application>` tag of your `AndroidManifest.xml`:
+
+```xml
+<service
+    android:name="androidx.appcompat.app.AppLocalesMetadataHolderService"
+    android:enabled="false"
+    android:exported="false">
+    <meta-data
+        android:name="autoStoreLocales"
+        android:value="true" />
+</service>
+```
+
+> [!NOTE]
+> Setting the language recreates the current activity, which reloads the web view.
+
+### iOS
+
+On iOS, the app language can only be changed by the **user** in the system settings. The `setLanguage(...)` and `resetLanguage(...)` methods are therefore not available. Use `openSettings(...)` to deep-link the user to the app's settings page.
+
+The per-app language row is only shown in the system settings if the app bundle provides **more than one** localization. Declare the supported localizations in the `Info.plist` file of your app:
+
+```xml
+<key>CFBundleLocalizations</key>
+<array>
+    <string>en</string>
+    <string>de</string>
+</array>
+```
+
+## Configuration
+
+No configuration required for this plugin.
+
+## Usage
+
+```typescript
+import { AppLanguage } from '@capawesome/capacitor-app-language';
+
+const getLanguage = async () => {
+  const { languageTag } = await AppLanguage.getLanguage();
+  return languageTag;
+};
+
+const setLanguage = async () => {
+  await AppLanguage.setLanguage({ languageTag: 'de-DE' });
+};
+
+const resetLanguage = async () => {
+  await AppLanguage.resetLanguage();
+};
+
+const openSettings = async () => {
+  await AppLanguage.openSettings();
+};
+```
+
+## API
+
+<docgen-index>
+
+* [`getLanguage()`](#getlanguage)
+* [`openSettings()`](#opensettings)
+* [`resetLanguage()`](#resetlanguage)
+* [`setLanguage(...)`](#setlanguage)
+* [Interfaces](#interfaces)
+
+</docgen-index>
+
+<docgen-api>
+<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
+
+### getLanguage()
+
+```typescript
+getLanguage() => Promise<GetLanguageResult>
+```
+
+Get the app's current language override.
+
+The language override is independent of the device language and only
+affects natively rendered strings (e.g. permission dialogs).
+
+**Returns:** <code>Promise&lt;<a href="#getlanguageresult">GetLanguageResult</a>&gt;</code>
+
+**Since:** 0.1.0
+
+--------------------
+
+
+### openSettings()
+
+```typescript
+openSettings() => Promise<void>
+```
+
+Open the app's settings page in the system settings.
+
+On iOS, this is where the user can change the app's language (the language
+row is only shown if the app bundle provides more than one localization).
+
+**Since:** 0.1.0
+
+--------------------
+
+
+### resetLanguage()
+
+```typescript
+resetLanguage() => Promise<void>
+```
+
+Reset the app's language override so the app follows the device language
+again.
+
+Resetting the language recreates the current activity, which reloads the
+web view.
+
+Only available on Android.
+
+**Since:** 0.1.0
+
+--------------------
+
+
+### setLanguage(...)
+
+```typescript
+setLanguage(options: SetLanguageOptions) => Promise<void>
+```
+
+Set the app's language override.
+
+Setting the language recreates the current activity, which reloads the
+web view.
+
+On iOS, the language can only be changed by the user in the system
+settings (see the `openSettings(...)` method).
+
+Only available on Android.
+
+| Param         | Type                                                              |
+| ------------- | ----------------------------------------------------------------- |
+| **`options`** | <code><a href="#setlanguageoptions">SetLanguageOptions</a></code> |
+
+**Since:** 0.1.0
+
+--------------------
+
+
+### Interfaces
+
+
+#### GetLanguageResult
+
+| Prop              | Type                        | Description                                                                                                                           | Since |
+| ----------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| **`languageTag`** | <code>string \| null</code> | The BCP 47 language tag of the app's language override. Returns `null` if no override is set and the app follows the device language. | 0.1.0 |
+
+
+#### SetLanguageOptions
+
+| Prop              | Type                | Description                                                    | Since |
+| ----------------- | ------------------- | -------------------------------------------------------------- | ----- |
+| **`languageTag`** | <code>string</code> | The BCP 47 language tag to set as the app's language override. | 0.1.0 |
+
+</docgen-api>
+
+## Platform Behavior
+
+Setting the app language programmatically is only supported on Android. On iOS, the language can only be changed by the user in the system settings.
+
+| Method             | Android | iOS              | Web              |
+| ------------------ | ------- | ---------------- | ---------------- |
+| `getLanguage()`    | ✅      | ✅               | ❌ Unimplemented |
+| `setLanguage(...)` | ✅      | ❌ Unimplemented | ❌ Unimplemented |
+| `resetLanguage()`  | ✅      | ❌ Unimplemented | ❌ Unimplemented |
+| `openSettings()`   | ✅      | ✅               | ❌ Unimplemented |
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-language/CHANGELOG.md).
+
+## License
+
+See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/app-language/LICENSE).

package/android/build.gradle

@@ -0,0 +1,58 @@
+ext {
+    junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+}
+
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+    }
+}
+
+apply plugin: 'com.android.library'
+
+android {
+    namespace = "io.capawesome.capacitorjs.plugins.applanguage"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
+    defaultConfig {
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
+        versionCode 1
+        versionName "1.0"
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+    }
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+        }
+    }
+    lintOptions {
+        abortOnError = false
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
+    }
+}
+
+repositories {
+    google()
+    mavenCentral()
+}
+
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    testImplementation "junit:junit:$junitVersion"
+    androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
+    androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/java/io/capawesome/capacitorjs/plugins/applanguage/AppLanguage.java

@@ -0,0 +1,65 @@
+package io.capawesome.capacitorjs.plugins.applanguage;
+
+import android.app.Activity;
+import android.content.Context;
+import android.content.Intent;
+import android.net.Uri;
+import android.os.Build;
+import android.provider.Settings;
+import androidx.annotation.NonNull;
+import androidx.appcompat.app.AppCompatDelegate;
+import androidx.core.os.LocaleListCompat;
+import io.capawesome.capacitorjs.plugins.applanguage.classes.options.SetLanguageOptions;
+import io.capawesome.capacitorjs.plugins.applanguage.classes.results.GetLanguageResult;
+import io.capawesome.capacitorjs.plugins.applanguage.interfaces.EmptyCallback;
+import io.capawesome.capacitorjs.plugins.applanguage.interfaces.NonEmptyResultCallback;
+
+public class AppLanguage {
+
+    @NonNull
+    private final AppLanguagePlugin plugin;
+
+    public AppLanguage(@NonNull AppLanguagePlugin plugin) {
+        this.plugin = plugin;
+    }
+
+    public void getLanguage(@NonNull NonEmptyResultCallback<GetLanguageResult> callback) {
+        LocaleListCompat locales = AppCompatDelegate.getApplicationLocales();
+        String languageTag = locales.isEmpty() ? null : locales.get(0).toLanguageTag();
+        callback.success(new GetLanguageResult(languageTag));
+    }
+
+    public void openSettings(@NonNull EmptyCallback callback) {
+        Context context = plugin.getContext();
+        Uri uri = Uri.fromParts("package", context.getPackageName(), null);
+        Intent intent;
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
+            intent = new Intent(Settings.ACTION_APP_LOCALE_SETTINGS);
+        } else {
+            intent = new Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS);
+        }
+        intent.setData(uri);
+        intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
+        context.startActivity(intent);
+        callback.success();
+    }
+
+    public void resetLanguage(@NonNull EmptyCallback callback) {
+        setApplicationLocales(LocaleListCompat.getEmptyLocaleList());
+        callback.success();
+    }
+
+    public void setLanguage(@NonNull SetLanguageOptions options, @NonNull EmptyCallback callback) {
+        setApplicationLocales(LocaleListCompat.forLanguageTags(options.getLanguageTag()));
+        callback.success();
+    }
+
+    private void setApplicationLocales(@NonNull LocaleListCompat locales) {
+        Activity activity = plugin.getActivity();
+        if (activity == null) {
+            AppCompatDelegate.setApplicationLocales(locales);
+        } else {
+            activity.runOnUiThread(() -> AppCompatDelegate.setApplicationLocales(locales));
+        }
+    }
+}

package/android/src/main/java/io/capawesome/capacitorjs/plugins/applanguage/AppLanguagePlugin.java

@@ -0,0 +1,136 @@
+package io.capawesome.capacitorjs.plugins.applanguage;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+import com.getcapacitor.Logger;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+import io.capawesome.capacitorjs.plugins.applanguage.classes.CustomException;
+import io.capawesome.capacitorjs.plugins.applanguage.classes.options.SetLanguageOptions;
+import io.capawesome.capacitorjs.plugins.applanguage.classes.results.GetLanguageResult;
+import io.capawesome.capacitorjs.plugins.applanguage.interfaces.EmptyCallback;
+import io.capawesome.capacitorjs.plugins.applanguage.interfaces.NonEmptyResultCallback;
+import io.capawesome.capacitorjs.plugins.applanguage.interfaces.Result;
+
+@CapacitorPlugin(name = "AppLanguage")
+public class AppLanguagePlugin extends Plugin {
+
+    public static final String TAG = "AppLanguage";
+
+    private static final String ERROR_UNKNOWN_ERROR = "An unknown error occurred.";
+
+    private AppLanguage implementation;
+
+    @Override
+    public void load() {
+        implementation = new AppLanguage(this);
+    }
+
+    @PluginMethod
+    public void getLanguage(PluginCall call) {
+        try {
+            NonEmptyResultCallback<GetLanguageResult> callback = new NonEmptyResultCallback<>() {
+                @Override
+                public void success(@NonNull GetLanguageResult result) {
+                    resolveCall(call, result);
+                }
+
+                @Override
+                public void error(@NonNull Exception exception) {
+                    rejectCall(call, exception);
+                }
+            };
+            implementation.getLanguage(callback);
+        } catch (Exception exception) {
+            rejectCall(call, exception);
+        }
+    }
+
+    @PluginMethod
+    public void openSettings(PluginCall call) {
+        try {
+            EmptyCallback callback = new EmptyCallback() {
+                @Override
+                public void success() {
+                    resolveCall(call);
+                }
+
+                @Override
+                public void error(@NonNull Exception exception) {
+                    rejectCall(call, exception);
+                }
+            };
+            implementation.openSettings(callback);
+        } catch (Exception exception) {
+            rejectCall(call, exception);
+        }
+    }
+
+    @PluginMethod
+    public void resetLanguage(PluginCall call) {
+        try {
+            EmptyCallback callback = new EmptyCallback() {
+                @Override
+                public void success() {
+                    resolveCall(call);
+                }
+
+                @Override
+                public void error(@NonNull Exception exception) {
+                    rejectCall(call, exception);
+                }
+            };
+            implementation.resetLanguage(callback);
+        } catch (Exception exception) {
+            rejectCall(call, exception);
+        }
+    }
+
+    @PluginMethod
+    public void setLanguage(PluginCall call) {
+        try {
+            SetLanguageOptions options = new SetLanguageOptions(call);
+            EmptyCallback callback = new EmptyCallback() {
+                @Override
+                public void success() {
+                    resolveCall(call);
+                }
+
+                @Override
+                public void error(@NonNull Exception exception) {
+                    rejectCall(call, exception);
+                }
+            };
+            implementation.setLanguage(options, callback);
+        } catch (Exception exception) {
+            rejectCall(call, exception);
+        }
+    }
+
+    private void rejectCall(@NonNull PluginCall call, @NonNull Exception exception) {
+        String message = exception.getMessage();
+        if (message == null) {
+            message = ERROR_UNKNOWN_ERROR;
+        }
+        String code = null;
+        if (exception instanceof CustomException) {
+            code = ((CustomException) exception).getCode();
+        }
+        Logger.error(TAG, message, exception);
+        call.reject(message, code);
+    }
+
+    private void resolveCall(@NonNull PluginCall call) {
+        call.resolve();
+    }
+
+    private void resolveCall(@NonNull PluginCall call, @Nullable Result result) {
+        if (result == null) {
+            call.resolve();
+        } else {
+            call.resolve(result.toJSObject());
+        }
+    }
+}

package/android/src/main/java/io/capawesome/capacitorjs/plugins/applanguage/classes/CustomException.java

@@ -0,0 +1,20 @@
+package io.capawesome.capacitorjs.plugins.applanguage.classes;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+
+public class CustomException extends Exception {
+
+    @Nullable
+    private final String code;
+
+    public CustomException(@Nullable String code, @NonNull String message) {
+        super(message);
+        this.code = code;
+    }
+
+    @Nullable
+    public String getCode() {
+        return code;
+    }
+}

package/android/src/main/java/io/capawesome/capacitorjs/plugins/applanguage/classes/CustomExceptions.java

@@ -0,0 +1,10 @@
+package io.capawesome.capacitorjs.plugins.applanguage.classes;
+
+public class CustomExceptions {
+
+    public static final CustomException LANGUAGE_TAG_INVALID = new CustomException(
+        null,
+        "languageTag must be a valid BCP 47 language tag."
+    );
+    public static final CustomException LANGUAGE_TAG_MISSING = new CustomException(null, "languageTag must be provided.");
+}

package/android/src/main/java/io/capawesome/capacitorjs/plugins/applanguage/classes/options/SetLanguageOptions.java

@@ -0,0 +1,33 @@
+package io.capawesome.capacitorjs.plugins.applanguage.classes.options;
+
+import androidx.annotation.NonNull;
+import com.getcapacitor.PluginCall;
+import io.capawesome.capacitorjs.plugins.applanguage.classes.CustomExceptions;
+import java.util.Locale;
+
+public class SetLanguageOptions {
+
+    @NonNull
+    private final String languageTag;
+
+    public SetLanguageOptions(@NonNull PluginCall call) throws Exception {
+        this.languageTag = SetLanguageOptions.getLanguageTagFromCall(call);
+    }
+
+    @NonNull
+    public String getLanguageTag() {
+        return languageTag;
+    }
+
+    @NonNull
+    private static String getLanguageTagFromCall(@NonNull PluginCall call) throws Exception {
+        String languageTag = call.getString("languageTag");
+        if (languageTag == null || languageTag.trim().isEmpty()) {
+            throw CustomExceptions.LANGUAGE_TAG_MISSING;
+        }
+        if (Locale.forLanguageTag(languageTag).getLanguage().isEmpty()) {
+            throw CustomExceptions.LANGUAGE_TAG_INVALID;
+        }
+        return languageTag;
+    }
+}