0.1.1 - doc updates, plugin tests, etc. (#6)

Work for release 0.1.1 - Mostly cosmetic cleanup of plugin tasks to improve functional organization, readability, and logging - Unit test validation added for plugin and all individual tasks - Java/Android locales lists added as docs as user information - Update README with more streamlined instructions, linked to wiki for more info Related work on Github - PR tests workflow added to validate changes before merging - Add deeper config details and locale information to wiki - Add roadmap to Discussions
aormsby · Aug 4, 2024 · 9ee8efc · 9ee8efc
1 parent b544f61
commit 9ee8efc
Show file tree

Hide file tree

Showing 19 changed files with 2,017 additions and 146 deletions.
diff --git a/.idea/uiDesigner.xml b/.idea/uiDesigner.xml
diff --git a/README.md b/README.md
@@ -1,24 +1,29 @@
 # Android Locale Resource Generator
 
 A Gradle plugin for Android projects to automate locale configuration and provide supporting source/resource files.
-Built with Android Gradle Plugin (AGP) 7.4.0
+Built with Android Gradle Plugin (AGP) 7.5.0
 
-## Primary Function
+## Functionality
 
-This plugin was built mostly to generate `locale-config.xml` file to support [per-app language settings](https://developer.android.com/guide/topics/resources/app-languages) for Android API 33+. Instead of remembering to modify files each time you add support for a locale, you just add the locale _once_ into your build.gradle file and let this plugin generate the xml resources you need for locale support.
+- Generates `locale-config.xml` file for Android [per-app language settings](https://developer.android.com/guide/topics/resources/app-languages)
+- Generates `SupportedLocales` Kotlin class for in-app access to your configured locales
+- Includes pseudolocale support when pseudolocales enabled for build variant
 
-**Bonus:** The plugin automatically includes pseudolocale options if you have them enabled for a build variant.
+## Community and Docs
 
-## Secondary Functions
+- [Wiki](../../wiki) for more details on language tag support and plugin configuration
+- [Discussions](../../discussions) for project roadmap, ideas, Q&A, and polls
+- [Issues](../../issues) for found bugs and reporting specific locale issues
 
-A `SupportedLocales.kt` source file is generated with maps of the locales your app is set to support. It includes language tags, langauge names (both exonyms and endonyms provided), and functions to get them. This data is intended to assist with building an in-app language selector, but I'd love to hear about other uses.
+## Setup
 
-## How to Use
+### Plugin Dependency Management
 
 ```kotlin
-// settings.gradle.kts (project settings)
+// File - settings.gradle.kts (project settings)
+
 dependencyResolutionManagement {
-    // should already have this section, don't modify
+    // don't modify
 }
 
 // add this if you don't have it
@@ -30,22 +35,24 @@ pluginManagement {
 }
 ```
 
-The `resourceConfigurations` property below is a list of explicitly configured resource types to be added to your project. Often, it's used to prevent building your project with extra resources you don't need (like tons of locale resources you don't support coming from dependencies you didn't know hda them.)
+### Project Locale Configuration
+
+The `resourceConfigurations` property is a list of explicitly configured resource types to be added to your project. Often, it's used to prevent building your project with extra resources you don't need (like locale resources you don't support coming from project dependencies)
 
-Since it's good practice to specify resources in use, this plugin utilizes the same `resourceConfigurations` list in during generation. Just add your supported locales into this list, and the plugin will handle the rest!
+Since it's good practice to specify resources in use, this plugin utilizes the same `resourceConfigurations` list to guide its resource generation. Add your supported locales into this list, and the plugin will handle the rest!
 
 ```kotlin
-// build.gradle.kts (application level)
+// File -  build.gradle.kts (app module)
+
 plugins {
     //...
-    id("com.mermake.locale-resource-generator") version "0.1" // check release page for latest version
+    id("com.mermake.locale-resource-generator") version "{{latest}}"
 }
 
 android {
     //...
     defaultConfig {
         //...
-
         resourceConfigurations.addAll(
             listOf(
                 "en",
@@ -60,16 +67,17 @@ android {
     }
 }
 ```
-> Notice the different formats of the language tags below. They're not _quite_ Unicode tags, but it's okay. Android recognizes both the `xx-rXX` and `bxx+XX+` formats ([more info on locale resolution here](https://developer.android.com/guide/topics/resources/multilingual-support#postN)). This is important to know since some language tags like `de-DE` would cause a build failure and the `b+` format is required. ([BCP-47 spec](https://cldr.unicode.org/development/development-process/design-proposals/bcp47-syntax-mapping)) In any case, the plugin converts everything to Unicode-friendly tags since that what we need in the manifest and source code anyway.
+> See the wiki page on [Locales and Android Support](../../wiki/Locales-and-Android-Support) for details on supported language tags.
+
+### Manifest Configuration
 
 ```xml
 <!-- AndroidManifest.xml -->
 <application>
-    <!-- Include this line in your application tag. The file is generated when you build and resolves without issue. -->
+    <!-- Include this line in your application tag. The file is generated when you build or run the locale config task. -->
     android:localeConfig="@xml/locale_config"
-
-
-    <!-- Add this for supporting lower than API 33 (see linked Android docs for more details) -->
+
+    <!-- Add this for supporting lower than API 33 (see Android docs for more info) -->
     <service
             android:name="androidx.appcompat.app.AppLocalesMetadataHolderService"
             android:enabled="false"
@@ -81,16 +89,9 @@ android {
 </application>
 ```
 
-The plugin runs automatically as part of your normal builds. You can also run individual tasks:
-- `generateLocaleConfig[Debug|Release|etc]` - generates `locale_config.xml` file for per-app language support
-
-## Glossary
-
-- **Endonym** - A name used by a group or category of people to refer to themselves or their language, as opposed to a name given to them by other groups.
-    - In Germany (Deutcshland), the 'German' language is written as 'Deutsche'
-    - In Japan (日本), the 'Japanese' language is written as '日本語'
-
+## Gradle Tasks
 
-- **Exonym** - Opposite of exonym. A name used to refer to a language or people that is not what they use to refer to themsleves their own language. Many languages have different names for each language.
-    - 'French' in Japanese is 'フランス語'
-    - 'French' in German is 'Französisch'
+The plugin runs its tasks automatically before the `preBuild` step of your normal builds. A variant task is configured for each of your project's build variants. (debug, release, wumbo, etc.)
+- `generateLocaleConfig[Variant]` - generates `locale_config.xml` resource file
+- `generateSupportedLocales[Variant]` - generates `SupportedLocales.kt` class
+- `soakConfiguredLocales[Variant]` - creates the intermediate files with supported locale information that is used in the other tasks
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -2,47 +2,67 @@ import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
 
 plugins {
     kotlin("jvm") version "1.7.20"
-    `kotlin-dsl`    // gradle manages version for compatibility
     id("com.gradle.plugin-publish") version "1.1.0"
-    signing
+    `kotlin-dsl`    // gradle kotlin dsl, syntax allows gradle to manage version for compatibility
+    signing         // gradle signing plugin
+    groovy          // for testing with Spock
 }
 
-group = "com.mermake"
-version = "0.1"
-
 repositories {
-    mavenCentral()
     google()
+    gradlePluginPortal()
 }
 
 dependencies {
     implementation("com.android.tools.build:gradle:7.4.0")
-    implementation("org.redundent:kotlin-xml-builder:1.8.0")
-    implementation("com.squareup:kotlinpoet:1.12.0") {
+    implementation("org.redundent:kotlin-xml-builder:1.8.0")    // todo: 1.9.0
+    implementation("com.squareup:kotlinpoet:1.12.0") {  // todo: 1.17.0
         exclude(module = "kotlin-reflect")
     }
+
+    testImplementation(gradleTestKit())
+    testImplementation(platform("org.spockframework:spock-bom:2.3-groovy-3.0"))
+    testImplementation("org.spockframework:spock-core")
+    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
 }
 
 tasks.withType<KotlinCompile>().configureEach {
     kotlinOptions.apiVersion = "1.7"
-    kotlinOptions.jvmTarget = "11"
+    kotlinOptions.jvmTarget = "11"  //  todo: test java 8 for broader backwards compatibility
 }
 
+tasks.withType<Test>().configureEach {
+    useJUnitPlatform()
+}
+
+group = "com.mermake"
+version = "0.1.1"
+
 gradlePlugin {
     plugins {
         register("localeResourceGeneratorPlugin") {
             id = "com.mermake.locale-resource-generator"
             displayName = "Locale Resource Generator"
-            description = "Automatically generates locale_config.xml for per-app language support on Android 13 and higher. " +
-                    "Also generates map of supported locales/languages for use in a runtime language picker."
             implementationClass = "com.mermake.locale_resource_generator.LocaleResourceGeneratorPlugin"
+            description =
+                "Automatically generates locale_config.xml for per-app language support on Android 13 and higher. " +
+                        "Also generates map of supported locales/languages for use in a runtime language picker."
         }
     }
 }
 
 pluginBundle {
-    // TODO: update with mermake group info when available (date very much tbd)
     website = "https://adamormsby.com"
     vcsUrl = "https://github.com/aormsby/android-locale-resource-generator"
-    tags = listOf("android", "android 13", "localization", "locale config", "language support", "automation")
+    tags = listOf(
+        "android",
+        "android plugin",
+        "android 13",
+        "tiramisu",
+        "localization",
+        "internationalization",
+        "locale config",
+        "language support",
+        "automation"
+    )
 }