Skip to content

feat: regional locale handling + android improvements #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Anty0 merged 6 commits into from
Jan 9, 2026
Merged

feat: regional locale handling + android improvements #11

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
934759d
feat: regional locales handling + support manifest
Anty0 Dec 16, 2025
284fc13
feat: loading multiple languages into memory
Anty0 Dec 16, 2025
6f6c6fd
feat: preload all languages
Anty0 Dec 16, 2025
fb0f7b7
feat: auto translate keys during Android layout inflation
Anty0 Dec 18, 2025
4891717
feat: default language
Anty0 Dec 18, 2025
59235ae
feat: progressive language fallback
Anty0 Dec 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions compose/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,7 @@ fun LocaleSwitcher() {
}.collectAsState(initial = tolgee.getLocale())

Row {
Text(text = stringResource(tolgee, R.string.selected_locale, currentLocale.language))
Text(text = stringResource(tolgee, R.string.selected_locale, currentLocale.toTag("-")))
Button(onClick = { tolgee.setLocale("en") }) {
Text("English")
}
Expand All @@ -188,7 +188,7 @@ fun LocaleAwareComponent() {
}.collectAsState(initial = tolgee.getLocale())

// Your UI that depends on the current locale
Text(text = currentLocale.language)
Text(text = currentLocale.toTag("-"))
}
```

Expand Down
21 changes: 21 additions & 0 deletions core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -161,6 +161,27 @@ 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-Hans-CN") is not available in your project:
1. Tolgee first tries to find the exact locale match
2. If not found, tries intermediate variations (e.g., "zh-Hans-CN" → "zh-Hans")
3. Then tries the base language (e.g., "zh-Hans" → "zh")
4. If still not found, uses the default language (e.g., "en")

This progressive fallback follows BCP 47 locale tag structure.

#### Preloading Translations

```kotlin
Expand Down
36 changes: 35 additions & 1 deletion core/api/android/core.api
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,9 @@ 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;
public fun setLocale (Ljava/util/Locale;)Ljava/util/Locale;
public final fun t (Ljava/lang/String;)Ljava/lang/String;
Expand Down Expand Up @@ -45,8 +47,12 @@ public final class io/tolgee/Tolgee$Config {
public final fun component1 ()Ljava/util/Locale;
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
Expand All @@ -55,20 +61,30 @@ public final class io/tolgee/Tolgee$Config {

public final class io/tolgee/Tolgee$Config$Builder {
public fun <init> ()V
public final fun availableLocaleTags (Ljava/util/List;)Lio/tolgee/Tolgee$Config$Builder;
public final fun availableLocaleTags ([Ljava/lang/String;)Lio/tolgee/Tolgee$Config$Builder;
public final fun availableLocales (Ljava/util/List;)Lio/tolgee/Tolgee$Config$Builder;
public final fun availableLocales ([Ljava/util/Locale;)Lio/tolgee/Tolgee$Config$Builder;
public final fun build ()Lio/tolgee/Tolgee$Config;
public final fun contentDelivery (Lio/tolgee/Tolgee$Config$ContentDelivery;)Lio/tolgee/Tolgee$Config$Builder;
public final fun contentDelivery (Ljava/lang/String;)Lio/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;
public final fun locale (Ljava/util/Locale;)Lio/tolgee/Tolgee$Config$Builder;
public final fun network (Lio/tolgee/Tolgee$Config$Network;)Lio/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
}
Expand All @@ -83,8 +99,12 @@ public final class io/tolgee/Tolgee$Config$ContentDelivery {
public final fun component2 ()Lkotlin/jvm/functions/Function1;
public final fun component3 ()Lio/tolgee/storage/TolgeeStorageProvider;
public final fun component4 ()Lio/tolgee/Tolgee$Formatter;
public final fun component5 ()Ljava/lang/String;
public final fun component6 ()Ljava/lang/Integer;
public fun equals (Ljava/lang/Object;)Z
public final fun getFormatter ()Lio/tolgee/Tolgee$Formatter;
public final fun getManifestPath ()Ljava/lang/String;
public final fun getMaxLocalesInMemory ()Ljava/lang/Integer;
public final fun getPath ()Lkotlin/jvm/functions/Function1;
public final fun getStorage ()Lio/tolgee/storage/TolgeeStorageProvider;
public final fun getUrl ()Ljava/lang/String;
Expand All @@ -97,11 +117,17 @@ public final class io/tolgee/Tolgee$Config$ContentDelivery$Builder {
public final fun build ()Lio/tolgee/Tolgee$Config$ContentDelivery;
public final fun formatter (Lio/tolgee/Tolgee$Formatter;)Lio/tolgee/Tolgee$Config$ContentDelivery$Builder;
public final fun getFormatter ()Lio/tolgee/Tolgee$Formatter;
public final fun getManifestPath ()Ljava/lang/String;
public final fun getMaxLocalesInMemory ()Ljava/lang/Integer;
public final fun getPath ()Lkotlin/jvm/functions/Function1;
public final fun getStorage ()Lio/tolgee/storage/TolgeeStorageProvider;
public final fun getUrl ()Ljava/lang/String;
public final fun manifestPath (Ljava/lang/String;)Lio/tolgee/Tolgee$Config$ContentDelivery$Builder;
public final fun maxLocalesInMemory (Ljava/lang/Integer;)Lio/tolgee/Tolgee$Config$ContentDelivery$Builder;
public final fun path (Lkotlin/jvm/functions/Function1;)Lio/tolgee/Tolgee$Config$ContentDelivery$Builder;
public final fun setFormatter (Lio/tolgee/Tolgee$Formatter;)V
public final fun setManifestPath (Ljava/lang/String;)V
public final fun setMaxLocalesInMemory (Ljava/lang/Integer;)V
public final fun setPath (Lkotlin/jvm/functions/Function1;)V
public final fun setStorage (Lio/tolgee/storage/TolgeeStorageProvider;)V
public final fun setUrl (Ljava/lang/String;)V
Expand Down Expand Up @@ -163,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;
Expand Down Expand Up @@ -190,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;
Expand Down
26 changes: 26 additions & 0 deletions core/api/jvm/core.api
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,9 @@ 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;
public fun setLocale (Ljava/util/Locale;)Ljava/util/Locale;
public final fun t (Ljava/lang/String;)Ljava/lang/String;
Expand Down Expand Up @@ -45,8 +47,12 @@ public final class io/tolgee/Tolgee$Config {
public final fun component1 ()Ljava/util/Locale;
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
Expand All @@ -55,20 +61,30 @@ public final class io/tolgee/Tolgee$Config {

public final class io/tolgee/Tolgee$Config$Builder {
public fun <init> ()V
public final fun availableLocaleTags (Ljava/util/List;)Lio/tolgee/Tolgee$Config$Builder;
public final fun availableLocaleTags ([Ljava/lang/String;)Lio/tolgee/Tolgee$Config$Builder;
public final fun availableLocales (Ljava/util/List;)Lio/tolgee/Tolgee$Config$Builder;
public final fun availableLocales ([Ljava/util/Locale;)Lio/tolgee/Tolgee$Config$Builder;
public final fun build ()Lio/tolgee/Tolgee$Config;
public final fun contentDelivery (Lio/tolgee/Tolgee$Config$ContentDelivery;)Lio/tolgee/Tolgee$Config$Builder;
public final fun contentDelivery (Ljava/lang/String;)Lio/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;
public final fun locale (Ljava/util/Locale;)Lio/tolgee/Tolgee$Config$Builder;
public final fun network (Lio/tolgee/Tolgee$Config$Network;)Lio/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
}
Expand All @@ -83,8 +99,12 @@ public final class io/tolgee/Tolgee$Config$ContentDelivery {
public final fun component2 ()Lkotlin/jvm/functions/Function1;
public final fun component3 ()Lio/tolgee/storage/TolgeeStorageProvider;
public final fun component4 ()Lio/tolgee/Tolgee$Formatter;
public final fun component5 ()Ljava/lang/String;
public final fun component6 ()Ljava/lang/Integer;
public fun equals (Ljava/lang/Object;)Z
public final fun getFormatter ()Lio/tolgee/Tolgee$Formatter;
public final fun getManifestPath ()Ljava/lang/String;
public final fun getMaxLocalesInMemory ()Ljava/lang/Integer;
public final fun getPath ()Lkotlin/jvm/functions/Function1;
public final fun getStorage ()Lio/tolgee/storage/TolgeeStorageProvider;
public final fun getUrl ()Ljava/lang/String;
Expand All @@ -97,11 +117,17 @@ public final class io/tolgee/Tolgee$Config$ContentDelivery$Builder {
public final fun build ()Lio/tolgee/Tolgee$Config$ContentDelivery;
public final fun formatter (Lio/tolgee/Tolgee$Formatter;)Lio/tolgee/Tolgee$Config$ContentDelivery$Builder;
public final fun getFormatter ()Lio/tolgee/Tolgee$Formatter;
public final fun getManifestPath ()Ljava/lang/String;
public final fun getMaxLocalesInMemory ()Ljava/lang/Integer;
public final fun getPath ()Lkotlin/jvm/functions/Function1;
public final fun getStorage ()Lio/tolgee/storage/TolgeeStorageProvider;
public final fun getUrl ()Ljava/lang/String;
public final fun manifestPath (Ljava/lang/String;)Lio/tolgee/Tolgee$Config$ContentDelivery$Builder;
public final fun maxLocalesInMemory (Ljava/lang/Integer;)Lio/tolgee/Tolgee$Config$ContentDelivery$Builder;
public final fun path (Lkotlin/jvm/functions/Function1;)Lio/tolgee/Tolgee$Config$ContentDelivery$Builder;
public final fun setFormatter (Lio/tolgee/Tolgee$Formatter;)V
public final fun setManifestPath (Ljava/lang/String;)V
public final fun setMaxLocalesInMemory (Ljava/lang/Integer;)V
public final fun setPath (Lkotlin/jvm/functions/Function1;)V
public final fun setStorage (Lio/tolgee/storage/TolgeeStorageProvider;)V
public final fun setUrl (Ljava/lang/String;)V
Expand Down
74 changes: 74 additions & 0 deletions core/src/androidMain/kotlin/io/tolgee/TolgeeAndroid.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
package io.tolgee

import android.app.Activity
import android.content.Context
import android.content.res.Resources
import android.view.View
import androidx.annotation.AnyRes
import androidx.annotation.ArrayRes
import androidx.annotation.PluralsRes
Expand Down Expand Up @@ -216,6 +218,78 @@ data class TolgeeAndroid internal constructor(
preload()
}

/**
* Preloads all available languages and their translations into memory.
*
* This is a convenience method that launches a coroutine in the provided [LifecycleOwner]'s
* lifecycle scope and calls the suspend [preloadAll] function.
*
* This method loads translations for all locales defined in the manifest or configuration.
* Translations are loaded into the LRU cache according to the configured cache size limit
* (see [Config.ContentDelivery.maxLocalesInMemory]).
*
* Use cases:
* - Applications that support frequent locale switching
* - Offline-first applications that want to cache multiple languages
* - Improving performance by preloading translations at app startup
*
* @param lifecycleOwner any [LifecycleOwner] to launch the coroutine from, e.g. Activity or Fragment
* @see preloadAll For the base suspend function
* @see preload For loading only the current locale
*/
fun preloadAll(lifecycleOwner: LifecycleOwner) = lifecycleOwner.lifecycleScope.launch {
preloadAll()
}

/**
* Re-translates all views in the given view hierarchy that were automatically
* translated during layout inflation.
*
* This method walks the view hierarchy and re-applies translations to any views
* that have stored resource IDs from the [TolgeeLayoutInflaterFactory].
*
* Use this after language changes if you prefer not to recreate the Activity.
* It provides a smoother UX than `Activity.recreate()` by avoiding the full
* Activity lifecycle restart.
*
* Example usage:
* ```kotlin
* lifecycleScope.launch {
* tolgee.changeFlow.collect {
* tolgee.retranslate(this@MainActivity)
* }
* }
* ```
*
* @param rootView The root view to start re-translation from (typically content view)
* @see retranslate(Activity) For a convenience method that finds the content view automatically
*/
fun retranslate(rootView: View) {
TolgeeLayoutInflaterFactory.retranslateViewHierarchy(rootView, this)
}

/**
* Re-translates all views in the Activity's content view.
*
* This is a convenience method that automatically finds the Activity's content view
* (android.R.id.content) and re-translates all views in that hierarchy.
*
* Example usage:
* ```kotlin
* lifecycleScope.launch {
* tolgee.changeFlow.collect {
* tolgee.retranslate(this@MainActivity)
* }
* }
* ```
*
* @param activity The activity whose views should be re-translated
* @see retranslate(View) For the base method that accepts a root view
*/
fun retranslate(activity: Activity) {
activity.findViewById<View>(android.R.id.content)?.let { retranslate(it) }
}

/**
* A companion object for utility functions related to string resources and key retrieval.
*/
Expand Down
Loading
Loading