Initial commit

2025-09-05 18:55:17 +08:00 · 2023-10-13 17:42:25 +08:00
commit 78217514bf
41 changed files with 2571 additions and 0 deletions
--- a/docs/changelog-zh-CN.md
+++ b/docs/changelog-zh-CN.md
@@ -0,0 +1,5 @@
+# 更新日志
+
+## 1.0.0 | 2023.10.13
+
+- 首个版本提交至 Maven
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0 | 2023.10.13
+
+- The first version is submitted to Maven
--- a/docs/guide-zh-CN.md
+++ b/docs/guide-zh-CN.md
@@ -0,0 +1,169 @@
+# Flexi Locale 使用文档
+
+在开始使用之前，建议你仔细阅读此文档，以便你能更好地了解它的作用方式与功能。
+
+如果你的项目依然在使用 Groovy DSL 进行管理，推荐迁移到 Kotlin DSL。
+
+在 Groovy DSL 中使用此插件发生的任何问题，我们都将不再负责排查和修复，并且在后期版本可能会完全不再支持 Groovy DSL。
+
+注意：此文档中将不再详细介绍在 Groovy DSL 中的使用方法。
+
+## 快速开始
+
+我们推荐使用 [SweetDependency](https://github.com/HighCapable/SweetDependency) 来自动管理依赖版本。
+
+以下是使用 `SweetDependency` 的装载方式。
+
+> 配置文件
+
+```yaml
+plugins:
+  com.highcapable.flexilocale:
+    alias: flexi-locale
+    version: +
+```
+
+> build.gradle.kts
+
+```kotlin
+plugins {
+    // 装载方式 1
+    autowire(libs.plugins.flexi.locale)
+    // 装载方式 2
+    autowire("flexi-locale")
+}
+```
+
+以下是传统的装载方式。
+
+打开你需要集成 `FlexiLocale` 插件项目的 `build.gradle.kts`。
+
+> 示例如下
+
+```kotlin
+plugins {
+    id("com.highcapable.flexilocale") version "<version>"
+}
+```
+
+请将上述代码中的 `<version>` 替换为 [Release](https://github.com/BetterAndroid/FlexiLocale/releases) 中的最新版本， 请注意不要在后方加入 apply false。
+
+上述配置完成后，运行一次 Gradle Sync。
+
+不出意外的情况下，你将会得到自动生成的 `AppLocale` 类，`Locale` 前方的名称为你的项目名称，默认应该为 `App`。
+
+## 功能配置
+
+你可以对 `FlexiLocale` 进行配置来实现自定义和个性化功能。
+
+`FlexiLocale` 为你提供了相对丰富的可自定义功能，下面是这些功能的说明与配置方法。
+
+请在你的 `build.gradle.kts` 中添加 `flexiLocale` 方法块以开始配置 `FlexiLocale`。
+
+`FlexiLocale` 依附于 `android` 方法块生成。
+
+> 示例如下
+
+```kotlin
+android {
+    flexiLocale {
+        // 启用 FlexiLocale，设置为 false 将禁用所有功能
+        isEnable = true
+        // 自定义生成的目录路径
+        // 你可以填写相对于当前项目的路径
+        // 默认为 "build/generated/flexi-locale"
+        // 建议将生成的代码放置于 "build" 目录下，因为生成的代码不建议去修改它
+        generateDirPath = "build/generated/flexi-locale"
+        // 自定义生成的包名
+        // Android 项目默认使用 "android" 配置方法块中的 "namespace"
+        // 你可以不进行设置，包名在一般情况下会自动进行匹配
+        packageName = "com.example.mydemo"
+        // 自定义生成的类名
+        // 默认使用当前项目的名称 + "Locale"
+        // 你可以不进行设置，类名在一般情况下会自动进行匹配
+        className = "MyDemo"
+        // 是否启用受限访问功能
+        // 默认不启用，启用后将为生成的类和方法添加 "internal" 修饰符
+        // 如果你的项目为工具库或依赖，通常情况下建议启用
+        // 启用后可以防止其他开发者在引用你的库时调用到你的项目国际化字符串调用类发生问题
+        isEnableRestrictedAccess = false
+    }
+}
+```
+
+如需在 Groovy DSL 中使用，请将所有变量的 `=` 改为空格，并删除 `Enable` 前方的 `is` 并将 `E` 小写即可。
+
+## 使用示例
+
+`FlexiLocale` 会自动扫描当前项目 `res/values` 目录中所有包含 `<string>...</string>` 的 XML 文件。
+
+假设这是你当前项目的 `strings.xml`，分为 `default` 和 `zh-rCN` 两个目录。
+
+> values/strings.xml
+
+```xml
+<resources>
+    <string name="app_name">My App</string>
+    <string name="say_hello">Hello %1$s</string>
+</resources>
+```
+
+> values-zh-rCN/strings.xml
+
+```xml
+<resources>
+    <string name="app_name">我的应用</string>
+    <string name="say_hello">你好 %1$s</string>
+</resources>
+```
+
+我们建议在 `Application` 中装载 `AppLocale`，这样你就可以在应用的任何地方进行调用。
+
+> 示例如下
+
+```kotlin
+lateinit var locale: AppLocale
+
+class App : Application() {
+
+    override fun onCreate() {
+        locale = AppLocale.attach(this)
+    }
+}
+```
+
+下面，你就可以直接去使用这些字符串了。
+
+> 示例如下
+
+```kotlin
+class MainActivity : Activity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        // 将设置标题为：
+        // default: My App
+        // zh-rCN: 我的应用
+        actionBar.title = locale.appName
+        // 将设置文本为：
+        // default: Hello John
+        // zh-rCN: 你好 John
+        findViewById<TextView>(R.id.hello_text).text = locale.sayHello("John")
+    }
+}
+```
+
+Java 的使用方式只需要将调用的字符串方法名前加入 `get` 即可。
+
+需要注意的是，当你修改了 `strings.xml` 等资源文件，你需要重新运行一次 Gradle Sync 以得到最新的生成结果。
+
+### 动态刷新
+
+如果用户动态地修改了系统语言，你可以使用 `AppLocale` 中的 `attach { dynamicResources }` 方法设置动态资源实例。
+
+如果你是使用 `Context` 装载的 `AppLocale`，那么你无需进行任何操作。
+
+请注意，如果 `Activity` 未自动重新启动，请在 `Activity` 中手动调用 `recreate` 才能看到语言改变后的结果。
+
+## 问题反馈
+
+如果你在使用 `FlexiLocale` 的过程中遇到了任何问题，你都可以随时在 GitHub 开启一个 `issues` 向我们反馈。
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -0,0 +1,176 @@
+# 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](https://github.com/HighCapable/SweetDependency) to autowire dependencies versions.
+
+The following is the loading method using `SweetDependency`.
+
+> Configuration File
+
+```yaml
+plugins:
+  com.highcapable.flexilocale:
+    alias: flexi-locale
+    version: +
+```
+
+> build.gradle.kts
+
+```kotlin
+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
+
+```kotlin
+plugins {
+    id("com.highcapable.flexilocale") version "<version>"
+}
+```
+
+Please replace `<version>` in the above code with the latest version in [Release](https://github.com/BetterAndroid/FlexiLocale/releases).
+
+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
+
+```kotlin
+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
+```xml
+<resources>
+    <string name="app_name">My App</string>
+    <string name="say_hello">Hello %1$s</string>
+</resources>
+```
+
+> values-zh-rCN/strings.xml
+
+```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
+
+```kotlin
+lateinit var locale: AppLocale
+
+class App : Application() {
+
+    override fun onCreate() {
+        locale = AppLocale.attach(this)
+    }
+}
+```
+
+Next, you can use these strings directly.
+
+> The following example
+
+```kotlin
+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.