guide.md

Flexi Locale Documentation

Before you start using it, it is recommended that you read this document carefully so that you can better understand how it works and its functions.

If your project is still managed using Groovy DSL, it is recommended to migrate to Kotlin DSL.

We will no longer be responsible for troubleshooting and fixing any issues that occur with this plugin in Groovy DSL, and Groovy DSL support may be dropped entirely in later releases.

Note: Usage in the Groovy DSL will not be detailed in this document.

Quick Start

We recommend using SweetDependency to autowire dependencies versions.

The following is the loading method using SweetDependency.

Configuration File

plugins:
  com.highcapable.flexilocale:
    alias: flexi-locale
    version: +

build.gradle.kts

plugins {
    // Loading method 1
    autowire(libs.plugins.flexi.locale)
    // Loading method 2
    autowire("flexi-locale")
}

The following is the traditional loading method.

Open the build.gradle.kts project where you need to integrate the FlexiLocale plugin.

The following example

plugins {
    id("com.highcapable.flexilocale") version "<version>"
}

Please replace <version> in the above code with the latest version in Release.

Please be careful not to add apply false at the end.

After the above configuration is completed, run Gradle Sync once.

If nothing else goes wrong, you will get the automatically generated AppLocale class, the name in front of Locale is your project name, and the default should be App.

Function Configuration

You can configure FlexiLocale to achieve customization and personalization.

FlexiLocale provides you with a relatively rich set of customizable functions.

The following is the description and configuration method of these functions.

Please add the flexiLocale method block to your build.gradle.kts to start configuring FlexiLocale.

FlexiLocale depends on the android method block generation.

The following example

android {
    flexiLocale {
        // Enable FlexiLocale, setting to false will disable all functionality
        isEnable = true
        // Customize the generated directory path
        // You can fill in the path relative to the current project
        // Default is "build/generated/flexi-locale"
        // It is recommended to place the generated code in the "build" directory, because the generated code is not recommended to be modified
        generateDirPath = "build/generated/flexi-locale"
        // Customize the generated package name
        // Android projects use the "namespace" in the "android" configuration method block by default
        // You don't need to set it, the package name will be automatically matched under normal circumstances
        packageName = "com.example.mydemo"
        // Customize the generated class name
        // By default, the name of the current project + "Locale" is used
        // You don't need to set it, the class name will be automatically matched under normal circumstances
        className = "MyDemo"
        // Whether to enable restricted access function
        // Not enabled by default. When enabled, the "internal" modifier will be added to the generated classes and methods
        // If your project is a tool library or dependency, it is usually recommended to enable it
        // Once enabled, it can prevent other developers from calling your project's i18ns string calling classes when they reference your library
        isEnableRestrictedAccess = false
    }
}

If you want to use it in Groovy DSL, please change the = of all variables to spaces, delete the is in front of Enable and lowercase E.

Usage Example

FlexiLocale will automatically scan all XML files containing <string>...</string> in the res/values directory of the current project.

Assume this is the strings.xml of your current project, divided into two directories: default and zh-rCN.

values/strings.xml

<resources>
    <string name="app_name">My App</string>
    <string name="say_hello">Hello %1$s</string>
</resources>

values-zh-rCN/strings.xml

<resources>
    <string name="app_name">我的应用</string>
    <string name="say_hello">你好 %1$s</string>
</resources>

We recommend loading AppLocale in Application so you can call it from anywhere in your application.

The following example

lateinit var locale: AppLocale

class App : Application() {

    override fun onCreate() {
        locale = AppLocale.attach(this)
    }
}

Next, you can use these strings directly.

The following example

class MainActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        // Will set the title to:
        // default: My App
        // zh-rCN: 我的应用
        actionBar.title = locale.appName
        // Will set the text to:
        // default: Hello John
        // zh-rCN: 你好 John
        findViewById<TextView>(R.id.hello_text).text = locale.sayHello("John")
    }
}

To use Java, you only need to add get before the name of the string method to be called.

It should be noted that when you modify resource files such as strings.xml, you need to re-run Gradle Sync to get the latest generation results.

Dynamic Refresh

If the user dynamically changes the system language, you can use the attach { dynamicResources } method in AppLocale to set a dynamic resources instance.

If you loaded AppLocale using Context, then you don't need to do anything.

Please note that if the Activity is not restarted automatically, please manually call recreate in the Activity to see the results of the language change.

Feedback

If you encounter any problems while using FlexiLocale, you can always open an issues on GitHub to give us feedback.