Localization Library

Header image Android library for in-app language changes support in your application

Feature

  • In-app language changing
  • Default language when first launch
  • Work with string resource in XML and programmatically
  • RTL language support
  • Align on platform behavior

Demo

Try it at Google Play

Download

Since version 1.2.9 will move from JCenter to MavenCentral

// build.gradle (project)
allprojects {
    repositories {
        mavenCentral()
        /* ... */
    }
}
Groovy

Gradle

implementation 'com.akexorcist:localization:1.2.10'
Groovy

(Optional) You can exclude androidx.appcompat:appcompat, if your project does not use AppCompat.

implementation ('com.akexorcist:localization:1.2.10') {
    exclude group: 'androidx.core', module: 'core'
}
Groovy

Usage

Custom application class which extends from LocalizationApplication is require.

class MainApplication: LocalizationApplication() {
    /* ... */
    override fun getDefaultLanguage() = Locale.ENGLISH
}
Kotlin

Either not, using LocalizationApplicationDelegate with additional code as below

class MainApplication: Application() {
    private val localizationDelegate = LocalizationApplicationDelegate()
    
    override fun attachBaseContext(base: Context) {
        localizationDelegate.setDefaultLanguage(base, Locale.ENGLISH)
        super.attachBaseContext(localizationDelegate.attachBaseContext(base))
    }
    
    override fun onConfigurationChanged(newConfig: Configuration) {
        super.onConfigurationChanged(newConfig)
        localizationDelegate.onConfigurationChanged(this)
    }
    
    override fun getApplicationContext(): Context {
        return localizationDelegate.getApplicationContext(super.getApplicationContext())
    }
    
    override fun getResources(): Resources {
        return localizationDelegate.getResources(baseContext, super.getResources())
    }
}
Kotlin

For the activities, extends from LocalizationActivity.

class MainActivity: LocalizationActivity() {
    /* ... */
}
Kotlin

Or using LocalizationActivityDelegate with additional code

open class CustomActivity : Activity(), OnLocaleChangedListener {
    private val localizationDelegate = LocalizationActivityDelegate(this)

    public override fun onCreate(savedInstanceState: Bundle?) {
        localizationDelegate.addOnLocaleChangedListener(this)
        localizationDelegate.onCreate()
        super.onCreate(savedInstanceState)
    }

    public override fun onResume() {
        super.onResume()
        localizationDelegate.onResume(this)
    }

    override fun attachBaseContext(newBase: Context) {
        applyOverrideConfiguration(localizationDelegate.updateConfigurationLocale(newBase))
        super.attachBaseContext(newBase)
    }

    override fun getApplicationContext(): Context {
        return localizationDelegate.getApplicationContext(super.getApplicationContext())
    }

    override fun getResources(): Resources {
        return localizationDelegate.getResources(super.getResources())
    }

    fun setLanguage(language: String?) {
        localizationDelegate.setLanguage(this, language!!)
    }

    fun setLanguage(locale: Locale?) {
        localizationDelegate.setLanguage(this, locale!!)
    }

    val currentLanguage: Locale
        get() = localizationDelegate.getLanguage(this)

    // Just override method locale change event
    override fun onBeforeLocaleChanged() {}
    override fun onAfterLocaleChanged() {}
}
Kotlin

Then prepare your multilingual content in string resource.

Multilingual Content

Public method on LocalizationActivity

It have only 4 public methods.

fun setLanguage(language: String)
fun setLanguage(language: String, country: Strinng)
fun setLanguage(locale: Locale)
fun getCurrentLanguage(): String
Kotlin

setLanguage Set the language that you need to change.

For example

setLanguage("th")                             // Language : Thailand
setLanguage("th", "TH")                       // Language : Thailand, Country : Thai
setLanguage(Locale("th", "TH"))               // Language : Thailand, Country : Thai
setLanguage("en")                             // Language : English
setLanguage("en", "GB")                       // Language : English,  Country : Great Britain
setLanguage("en", "US")                       // Language : English,  Country : United States
setLanguage(Locale("en", "US"))               // Language : English,  Country : United States
setLanguage(Locale.KOREA)                     // Language : Korean,   Country : Korea
setLanguage(Locale.KOREAN)                    // Language : Korean
setLanguage(Locale.CANADA_FRENCH)             // Language : French,   Country : Canada
Kotlin

getLanguage Get current language as string locale.

And 2 optional override methods.

fun onBeforeLocaleChanged()
fun onAfterLocaleChanged()
Kotlin

This override method will be useful when you need to know when language has changed.

Back Stack 1

When setLanguage was called. Current active activity will be recreated to apply the new language.

Back Stack 2

Previous activities in back stack does not change to new language immediately. Until it back to active activity again.

Back Stack 3

Back Stack 4

Back Stack 5

Action Bar or Toolbar's title

You have to call setTitle(resId) or getActionBar().setTitle(resId) in onCreate(onSavedInstanceState: Bundle) to apply the new language.

class MainActivity: LocalizationActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        /* ... */
        setTitle(R.string.main_activity_title)
    }
}
Kotlin

Handle state changes

Activity will be recreate when language has changed as common behavior for configuration changes in Android. Any Activities or Fragments which hold the data should handle the state changes.

Change the language in Fragment

Language in fragment will depends on activity. So no need for additional code in Fragment.

Service

For normally usage, just extends from LocalizationService

class SimpleService : LocalizationService() {
    /* ... */
}
Kotlin

Or using LocalizationServiceDelegate with additional code

abstract class CustomService : Service() {
    private val localizationDelegate: LocalizationServiceDelegate by lazy {
        LocalizationServiceDelegate(this)
    }

    override fun getBaseContext(): Context {
        return localizationDelegate.getBaseContext(super.getBaseContext())
    }

    override fun getApplicationContext(): Context {
        return localizationDelegate.getApplicationContext(super.getApplicationContext())
    }

    override fun getResources(): Resources {
        return localizationDelegate.getResources(super.getResources())
    }
}
Kotlin

BroadcastReceiver

BroadcastReceiver is abstract class. So we cannot create LocalizationBroadcastReceiver fot you.

In this case, you need to convert the context in onReceive(context: Context, intent: Intent) to localized context with Context.toLocalizedContext() before using.

class SimpleBroadcastReceiver : BroadcastReceiver() {
    override fun onReceive(context: Context, intent: Intent) {
        val localizedContext = context.toLocalizedContext()
        /* ... */
    }
}
Kotlin

Language resources optimization in Android App Bundle

Change the language by library can cause a crash to your app when you publishing your app with Android App Bundle with language resources optimization enabled.

To fix this, Using the Additional Languages API in Play Core library to download the additional language before.

For more information about Additional Language API : https://android-developers.googleblog.com/2019/03/the-latest-android-app-bundle-updates.html

If you don't want to implement this feature in your code, just ignore the language resources optimization by adding the Android App Bundle configuration in your app's build.gradle

android {
    /* ... */ 
    bundle { 
        language { 
            enableSplit = false 
        } 
    } 
}
Groovy

ProGuard

Normally, there's no require the ProGuard rules for this library.

But if you want to exclude this library from obfuscate and shrinking. You also can add these code to proguard-rules.pro

-keep class com.akexorcist.localizationactivity.** { *; }
-dontwarn com.akexorcist.localizationactivity.**

GitHub

https://github.com/akexorcist/Localization