diff --git a/README.md b/README.md index ba99781..7b6da7e 100644 --- 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 configuration +- [Discussions](../../discussions) for project roadmap, enhancement ideas, and sharing uses +- [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 - + android:localeConfig="@xml/locale_config" - - - + + ``` -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/android_locales.txt b/docs/android_locales.txt similarity index 97% rename from android_locales.txt rename to docs/android_locales.txt index e632397..a542336 100644 --- a/android_locales.txt +++ b/docs/android_locales.txt @@ -96,4 +96,7 @@ lo lt lt-rLT lv -lv-rLV \ No newline at end of file +lv-rLV +zh +zh-CN +zh-rTW \ No newline at end of file diff --git a/java_locales.txt b/docs/java_locales.txt similarity index 100% rename from java_locales.txt rename to docs/java_locales.txt diff --git a/src/main/kotlin/com/mermake/locale_resource_generator/tasks/GenerateSupportedLocalesTask.kt b/src/main/kotlin/com/mermake/locale_resource_generator/tasks/GenerateSupportedLocalesTask.kt index cf0da2c..0436d7b 100644 --- a/src/main/kotlin/com/mermake/locale_resource_generator/tasks/GenerateSupportedLocalesTask.kt +++ b/src/main/kotlin/com/mermake/locale_resource_generator/tasks/GenerateSupportedLocalesTask.kt @@ -44,7 +44,7 @@ abstract class GenerateSupportedLocalesTask : DefaultTask() { supportedLanguageTags: List, ): FileSpec { val classKdoc = - """Generated class containing the locales supported by your project in the form of list and maps. + """Generated class containing the locales configured in project in the form of list and maps. |Language tags and their corresponding names (endonyms and exonyms) are retrievable through public functions. """.trimMargin() @@ -139,7 +139,7 @@ abstract class GenerateSupportedLocalesTask : DefaultTask() { private fun buildTagsAccessor(property: PropertySpec) = FunSpec.builder("getTags") - .addKdoc("@returns List of language tags supported by your project.") + .addKdoc("@returns List of language tags configured in your project.") .addStatement("return %N", property) .build() diff --git a/src/test/groovy/com/mermake/locale_resource_generator/data/Intermediates.groovy b/src/test/groovy/com/mermake/locale_resource_generator/data/Intermediates.groovy index fd95d0d..88a5105 100644 --- a/src/test/groovy/com/mermake/locale_resource_generator/data/Intermediates.groovy +++ b/src/test/groovy/com/mermake/locale_resource_generator/data/Intermediates.groovy @@ -57,6 +57,7 @@ class Intermediates { "de-LI,Deutsch (Liechtenstein)", "el,Ελληνικά", "el-GR,Ελληνικά (Ελλάδα)", + "en,English", "en-AU,English (Australia)", "en-CA,English (Canada)", "en-GB,English (United Kingdom)", diff --git a/src/test/groovy/com/mermake/locale_resource_generator/data/Tags.groovy b/src/test/groovy/com/mermake/locale_resource_generator/data/Tags.groovy index 0b4b44d..abb3cc1 100644 --- a/src/test/groovy/com/mermake/locale_resource_generator/data/Tags.groovy +++ b/src/test/groovy/com/mermake/locale_resource_generator/data/Tags.groovy @@ -29,7 +29,7 @@ class Tags { "da", "da-rDK", "de", "de-rAT", "de-rCH", "de-rDE", "de-rLI", "el", "el-rGR", - "en-rAU", "en-rCA", "en-rGB", "en-rIE", "en-rIN", "en-rNZ", "en-rSG", "en-rUS", "en-rZA", + "en", "en-rAU", "en-rCA", "en-rGB", "en-rIE", "en-rIN", "en-rNZ", "en-rSG", "en-rUS", "en-rZA", "es", "es-rCO", "es-rCR", "es-rEC", "es-rES", "es-rGT", "es-rHN", "es-rMX", "es-rNI", "es-rPA", "es-rPE", "es-rSV", "es-rUS", "et", "eu", @@ -76,7 +76,7 @@ class Tags { "b+da", "b+da+DK", "b+de", "b+de+AT", "b+de+CH", "b+de+DE", "b+de+LI", "b+el", "b+el+GR", - "b+en+AU", "b+en+CA", "b+en+GB", "b+en+IE", "b+en+IN", "b+en+NZ", "b+en+SG", "b+en+US", "b+en+ZA", + "b+en", "b+en+AU", "b+en+CA", "b+en+GB", "b+en+IE", "b+en+IN", "b+en+NZ", "b+en+SG", "b+en+US", "b+en+ZA", "b+es", "b+es+CO", "b+es+CR", "b+es+EC", "b+es+ES", "b+es+GT", "b+es+HN", "b+es+MX", "b+es+NI", "b+es+PA", "b+es+PE", "b+es+SV", "b+es+US", "b+et", "b+eu", diff --git a/src/test/groovy/com/mermake/locale_resource_generator/data/Xml.groovy b/src/test/groovy/com/mermake/locale_resource_generator/data/Xml.groovy index 9f7651a..04df544 100644 --- a/src/test/groovy/com/mermake/locale_resource_generator/data/Xml.groovy +++ b/src/test/groovy/com/mermake/locale_resource_generator/data/Xml.groovy @@ -80,6 +80,8 @@ class Xml { '', '', '', + '', + '', '', '', '',