feat: default language

Author: Anty0

core/README.md

@@ -161,6 +161,24 @@ Tolgee.init {
 }
 ```
 
+#### Default Language Fallback
+
+Configure a default language to use when the user's locale is not available:
+
+```kotlin
+Tolgee.init {
+    contentDelivery {
+        url = "https://cdn.tolg.ee/your-cdn-url-prefix"
+    }
+    defaultLanguage("en") // Fallback to English when user's locale is unavailable
+}
+```
+
+When a user's locale (e.g., "zh-CN") is not available in your project:
+1. Tolgee first tries to find the exact locale match
+2. If not found, tries the base language (e.g., "zh-CN" → "zh")
+3. If still not found, uses the default language (e.g., "en")
+
 #### Preloading Translations
 
 ```kotlin

core/api/android/core.api

@@ -13,6 +13,7 @@ public class io/tolgee/Tolgee {
 	public static final fun new (Lio/tolgee/Tolgee$Config;)Lio/tolgee/TolgeeAndroid;
 	public static final fun new (Lkotlin/jvm/functions/Function1;)Lio/tolgee/TolgeeAndroid;
 	public fun preload (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public fun preloadAll (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public final fun removeChangeListener (Lio/tolgee/Tolgee$ChangeListener;)Z
 	protected final fun resolveLocale (Ljava/util/Locale;)Ljava/util/Locale;
 	public fun setLocale (Ljava/lang/String;)Ljava/util/Locale;
@@ -47,9 +48,11 @@ public final class io/tolgee/Tolgee$Config {
 	public final fun component2 ()Lio/tolgee/Tolgee$Config$Network;
 	public final fun component3 ()Lio/tolgee/Tolgee$Config$ContentDelivery;
 	public final fun component4 ()Ljava/util/List;
+	public final fun component5 ()Ljava/util/Locale;
 	public fun equals (Ljava/lang/Object;)Z
 	public final fun getAvailableLocales ()Ljava/util/List;
 	public final fun getContentDelivery ()Lio/tolgee/Tolgee$Config$ContentDelivery;
+	public final fun getDefaultLanguage ()Ljava/util/Locale;
 	public final fun getLocale ()Ljava/util/Locale;
 	public final fun getNetwork ()Lio/tolgee/Tolgee$Config$Network;
 	public fun hashCode ()I
@@ -68,8 +71,11 @@ public final class io/tolgee/Tolgee$Config$Builder {
 	public final fun contentDelivery (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)Lio/tolgee/Tolgee$Config$Builder;
 	public final fun contentDelivery (Lkotlin/jvm/functions/Function1;)Lio/tolgee/Tolgee$Config$Builder;
 	public static synthetic fun contentDelivery$default (Lio/tolgee/Tolgee$Config$Builder;Ljava/lang/String;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lio/tolgee/Tolgee$Config$Builder;
+	public final fun defaultLanguage (Ljava/lang/String;)Lio/tolgee/Tolgee$Config$Builder;
+	public final fun defaultLanguage (Ljava/util/Locale;)Lio/tolgee/Tolgee$Config$Builder;
 	public final fun getAvailableLocales ()Ljava/util/List;
 	public final fun getContentDelivery ()Lio/tolgee/Tolgee$Config$ContentDelivery;
+	public final fun getDefaultLanguage ()Ljava/util/Locale;
 	public final fun getLocale ()Ljava/util/Locale;
 	public final fun getNetwork ()Lio/tolgee/Tolgee$Config$Network;
 	public final fun locale (Ljava/lang/String;)Lio/tolgee/Tolgee$Config$Builder;
@@ -78,6 +84,7 @@ public final class io/tolgee/Tolgee$Config$Builder {
 	public final fun network (Lkotlin/jvm/functions/Function1;)Lio/tolgee/Tolgee$Config$Builder;
 	public final fun setAvailableLocales (Ljava/util/List;)V
 	public final fun setContentDelivery (Lio/tolgee/Tolgee$Config$ContentDelivery;)V
+	public final fun setDefaultLanguage (Ljava/util/Locale;)V
 	public final fun setLocale (Ljava/util/Locale;)V
 	public final fun setNetwork (Lio/tolgee/Tolgee$Config$Network;)V
 }
@@ -182,6 +189,9 @@ public final class io/tolgee/TolgeeAndroid : io/tolgee/Tolgee {
 	public fun getConfig ()Lio/tolgee/Tolgee$Config;
 	public fun hashCode ()I
 	public final fun preload (Landroidx/lifecycle/LifecycleOwner;)Lkotlinx/coroutines/Job;
+	public final fun preloadAll (Landroidx/lifecycle/LifecycleOwner;)Lkotlinx/coroutines/Job;
+	public final fun retranslate (Landroid/app/Activity;)V
+	public final fun retranslate (Landroid/view/View;)V
 	public final fun t (Landroid/content/Context;I)Ljava/lang/String;
 	public final fun t (Landroid/content/Context;I[Ljava/lang/Object;)Ljava/lang/String;
 	public final fun t (Landroid/content/res/Resources;I)Ljava/lang/String;
@@ -209,9 +219,14 @@ public final class io/tolgee/TolgeeAndroid$Companion {
 
 public final class io/tolgee/TolgeeContextWrapper : android/content/ContextWrapper {
 	public static final field Companion Lio/tolgee/TolgeeContextWrapper$Companion;
-	public fun <init> (Landroid/content/Context;Lio/tolgee/Tolgee;)V
+	public fun <init> (Landroid/content/Context;Lio/tolgee/Tolgee;ZZZ)V
+	public synthetic fun <init> (Landroid/content/Context;Lio/tolgee/Tolgee;ZZZILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun getArgumentLayoutInflater ()Z
 	public final fun getBase ()Landroid/content/Context;
+	public final fun getInterceptGetString ()Z
+	public final fun getInterceptGetText ()Z
 	public fun getResources ()Landroid/content/res/Resources;
+	public fun getSystemService (Ljava/lang/String;)Ljava/lang/Object;
 	public final fun getTolgee ()Lio/tolgee/Tolgee;
 	public static final fun wrap (Landroid/content/Context;)Landroid/content/ContextWrapper;
 	public static final fun wrap (Landroid/content/Context;Lio/tolgee/Tolgee;)Landroid/content/ContextWrapper;

core/api/jvm/core.api

@@ -13,6 +13,7 @@ public class io/tolgee/Tolgee {
 	public static final fun new (Lio/tolgee/Tolgee$Config;)Lio/tolgee/common/PlatformTolgee;
 	public static final fun new (Lkotlin/jvm/functions/Function1;)Lio/tolgee/common/PlatformTolgee;
 	public fun preload (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
+	public fun preloadAll (Lkotlin/coroutines/Continuation;)Ljava/lang/Object;
 	public final fun removeChangeListener (Lio/tolgee/Tolgee$ChangeListener;)Z
 	protected final fun resolveLocale (Ljava/util/Locale;)Ljava/util/Locale;
 	public fun setLocale (Ljava/lang/String;)Ljava/util/Locale;
@@ -47,9 +48,11 @@ public final class io/tolgee/Tolgee$Config {
 	public final fun component2 ()Lio/tolgee/Tolgee$Config$Network;
 	public final fun component3 ()Lio/tolgee/Tolgee$Config$ContentDelivery;
 	public final fun component4 ()Ljava/util/List;
+	public final fun component5 ()Ljava/util/Locale;
 	public fun equals (Ljava/lang/Object;)Z
 	public final fun getAvailableLocales ()Ljava/util/List;
 	public final fun getContentDelivery ()Lio/tolgee/Tolgee$Config$ContentDelivery;
+	public final fun getDefaultLanguage ()Ljava/util/Locale;
 	public final fun getLocale ()Ljava/util/Locale;
 	public final fun getNetwork ()Lio/tolgee/Tolgee$Config$Network;
 	public fun hashCode ()I
@@ -68,8 +71,11 @@ public final class io/tolgee/Tolgee$Config$Builder {
 	public final fun contentDelivery (Ljava/lang/String;Lkotlin/jvm/functions/Function1;)Lio/tolgee/Tolgee$Config$Builder;
 	public final fun contentDelivery (Lkotlin/jvm/functions/Function1;)Lio/tolgee/Tolgee$Config$Builder;
 	public static synthetic fun contentDelivery$default (Lio/tolgee/Tolgee$Config$Builder;Ljava/lang/String;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)Lio/tolgee/Tolgee$Config$Builder;
+	public final fun defaultLanguage (Ljava/lang/String;)Lio/tolgee/Tolgee$Config$Builder;
+	public final fun defaultLanguage (Ljava/util/Locale;)Lio/tolgee/Tolgee$Config$Builder;
 	public final fun getAvailableLocales ()Ljava/util/List;
 	public final fun getContentDelivery ()Lio/tolgee/Tolgee$Config$ContentDelivery;
+	public final fun getDefaultLanguage ()Ljava/util/Locale;
 	public final fun getLocale ()Ljava/util/Locale;
 	public final fun getNetwork ()Lio/tolgee/Tolgee$Config$Network;
 	public final fun locale (Ljava/lang/String;)Lio/tolgee/Tolgee$Config$Builder;
@@ -78,6 +84,7 @@ public final class io/tolgee/Tolgee$Config$Builder {
 	public final fun network (Lkotlin/jvm/functions/Function1;)Lio/tolgee/Tolgee$Config$Builder;
 	public final fun setAvailableLocales (Ljava/util/List;)V
 	public final fun setContentDelivery (Lio/tolgee/Tolgee$Config$ContentDelivery;)V
+	public final fun setDefaultLanguage (Ljava/util/Locale;)V
 	public final fun setLocale (Ljava/util/Locale;)V
 	public final fun setNetwork (Lio/tolgee/Tolgee$Config$Network;)V
 }

core/src/commonMain/kotlin/io/tolgee/Tolgee.kt

@@ -165,6 +165,7 @@ open class Tolgee(
      * Resolution strategy:
      * 1. If the exact locale is available, return it (e.g., "en-US" → "en-US")
      * 2. Otherwise, try to find an exact match for the base language (e.g., "en-US" → "en")
+     * 3. If still not found, use the default language if configured
      *
      * Available locales are determined from:
      * 1. `config.availableLocales` (if manually specified)
@@ -194,13 +195,21 @@ open class Tolgee(
 
         // Fallback: Look for exact base language match only
         // Find exact match for base language (e.g., "en" without region/script)
-        return availableLocales.firstOrNull { availableLocale ->
+        val baseLanguageMatch = availableLocales.firstOrNull { availableLocale ->
             // Match only if:
             // 1. The language matches
             // 2. It's a base language (no region/script), checked by comparing tag to language
             availableLocale.language == locale.language &&
             availableLocale.toTag("-") == availableLocale.language
         }
+
+        if (baseLanguageMatch != null) {
+            return baseLanguageMatch
+        }
+
+        // Final fallback: Use default language if configured, otherwise null
+        // We assume the default language is available
+        return config.defaultLanguage
     }
 
     /**
@@ -462,6 +471,7 @@ open class Tolgee(
         val network: Network,
         val contentDelivery: ContentDelivery,
         val availableLocales: List<Locale>?,
+        val defaultLanguage: Locale?,
     ) {
 
         /**
@@ -493,6 +503,21 @@ open class Tolgee(
              */
             var availableLocales: List<Locale>? = null
 
+            /**
+             * The default language to use as a final fallback when the requested locale
+             * and its base language are not available. This ensures that users with
+             * unsupported languages receive translations from the CDN (in the default language)
+             * instead of falling back to native bundled translations.
+             *
+             * Example: If a user has locale "zh-CN" and it's not available, but "en" is set
+             * as the default language, the app will fetch and display English translations
+             * from the CDN rather than using bundled translations.
+             *
+             * If null (default), the fallback chain ends with returning null from resolveLocale(),
+             * which eventually leads to using TranslationEmpty and bundled translations.
+             */
+            var defaultLanguage: Locale? = null
+
             /**
              * Represents the network configuration used within the `Builder`.
              * This property defines the HTTP client and coroutine context used for executing network operations.
@@ -568,6 +593,21 @@ open class Tolgee(
              */
             fun availableLocaleTags(vararg localeTags: String) = availableLocales(localeTags.map(::forLocaleTag))
 
+            /**
+             * Sets the default language to use as a final fallback when the requested locale is not available.
+             *
+             * @param locale The locale to use as the default fallback language.
+             */
+            fun defaultLanguage(locale: Locale) = apply {
+                this.defaultLanguage = locale
+            }
+
+            /**
+             * Sets the default language to use as a final fallback when the requested locale is not available.
+             *
+             * @param localeTag A locale string in the format of a language tag (e.g., "en", "fr", "es").
+             */
+            fun defaultLanguage(localeTag: String) = defaultLanguage(forLocaleTag(localeTag))
 
             /**
              * Configures the network settings for the builder.
@@ -641,6 +681,7 @@ open class Tolgee(
                 availableLocales = availableLocales,
                 network = network,
                 contentDelivery = contentDelivery,
+                defaultLanguage = defaultLanguage,
             )
         }
 

demo/exampleandroid/src/main/java/io/tolgee/demo/exampleandroid/MyApplication.kt

@@ -15,6 +15,7 @@ class MyApplication : Application() {
         storage = TolgeeStorageProviderAndroid(this@MyApplication, BuildConfig.VERSION_CODE)
         availableLocaleTags("cs", "en", "fr", "sv")
       }
+      defaultLanguage("en")
     }
   }
 }