Added the possibility to define the order of an export. (#58)

Co-authored-by: Martin Breuer <martin.breuer@sennder.com>

Author: WarrenFaith

CHANGELOG.md

@@ -23,6 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 ### Added
 - Add configuration support to define custom resource file names. _Thanks to [@gustavaa](https://github.com/gustavaa) for the contribution!_
+- Add configuration support to define how to order the export.
 ### Changed
 - No changed features!
 ### Deprecated

README.md

@@ -91,6 +91,7 @@ Attribute                          | Description
 ```minimumTranslationPercentage``` | (Since 2.3.0) (Optional) The minimum accepted percentage of translated strings per language. Languages with fewer translated strings will not be fetched. Defaults to no minimum, allowing all languages to be fetched.
 ```filters```                      | (Since 2.4.0) (Optional) List of PoEditor filters to use during download. Defaults to empty list. Accepted values are defined by the POEditor API.
 ```resFileName``` | (Since 3.1.0) (Optional) Sets the file name for the imported string resource XML files. Defaults to `strings`.
+```order```                        | (Since 3.1.0) (Optional) Defines how to order the export. Accepted values are defined by the POEditor API.
 
 After the configuration is done, just run the new ```importPoEditorStrings``` task via Android Studio or command line:
 

src/main/kotlin/com/hyperdevs/poeditor/gradle/Main.kt

@@ -19,6 +19,7 @@
 package com.hyperdevs.poeditor.gradle
 
 import com.hyperdevs.poeditor.gradle.network.api.FilterType
+import com.hyperdevs.poeditor.gradle.network.api.OrderType
 import io.github.cdimascio.dotenv.Dotenv
 
 /**
@@ -41,6 +42,7 @@ fun main() {
         ?.map { it.trim() }
         ?.map { FilterType.from(it) }
         ?: emptyList()
+    val order = OrderType.from(dotenv.get("ORDER", OrderType.NONE.name))
     val tags = dotenv.get("TAGS", "")
         .takeIf { it.isNotBlank() }
         ?.split(",")
@@ -62,6 +64,7 @@ fun main() {
         defaultLanguage,
         resDirPath,
         filters,
+        order,
         tags,
         languageValuesOverridePathMap,
         minimumTranslationPercentage,

src/main/kotlin/com/hyperdevs/poeditor/gradle/PoEditorPlugin.kt

@@ -25,6 +25,7 @@ import com.android.build.gradle.LibraryExtension
 import com.android.build.gradle.LibraryPlugin
 import com.android.build.gradle.internal.dsl.BaseAppModuleExtension
 import com.hyperdevs.poeditor.gradle.ktx.registerNewTask
+import com.hyperdevs.poeditor.gradle.network.api.OrderType
 import com.hyperdevs.poeditor.gradle.tasks.ImportPoEditorStringsTask
 import com.hyperdevs.poeditor.gradle.utils.*
 import org.gradle.api.NamedDomainObjectContainer
@@ -53,6 +54,7 @@ class PoEditorPlugin : Plugin<Project> {
                 defaultLang.convention("en")
                 defaultResPath.convention(mainResourceDirectory.asFile.absolutePath)
                 filters.convention(emptyList())
+                order.convention(OrderType.NONE.name.toLowerCase())
                 tags.convention(emptyList())
                 languageValuesOverridePathMap.convention(emptyMap())
                 minimumTranslationPercentage.convention(-1)

src/main/kotlin/com/hyperdevs/poeditor/gradle/PoEditorPluginExtension.kt

@@ -96,6 +96,15 @@ open class PoEditorPluginExtension @Inject constructor(objects: ObjectFactory, p
     @get:Input
     val filters: ListProperty<String> = objects.listProperty(String::class.java)
 
+    /**
+     * Defines the order for the export. If set to "terms" it will be ordered alphabetically by the terms.
+     *
+     * Defaults to "none" meaning no order will be applied.
+     */
+    @get:Optional
+    @get:Input
+    val order: Property<String> = objects.property(String::class.java)
+
     /**
      * Tags to filter downloaded strings with, previously declared in PoEditor.
      *

src/main/kotlin/com/hyperdevs/poeditor/gradle/PoEditorStringsImporter.kt

@@ -22,6 +22,7 @@ import com.hyperdevs.poeditor.gradle.ktx.downloadUrlToString
 import com.hyperdevs.poeditor.gradle.network.PoEditorApiControllerImpl
 import com.hyperdevs.poeditor.gradle.network.api.ExportType
 import com.hyperdevs.poeditor.gradle.network.api.FilterType
+import com.hyperdevs.poeditor.gradle.network.api.OrderType
 import com.hyperdevs.poeditor.gradle.network.api.PoEditorApi
 import com.hyperdevs.poeditor.gradle.network.api.ProjectLanguage
 import com.hyperdevs.poeditor.gradle.utils.TABLET_REGEX_STRING
@@ -87,6 +88,7 @@ object PoEditorStringsImporter {
                               defaultLang: String,
                               resDirPath: String,
                               filters: List<FilterType>,
+                              order: OrderType,
                               tags: List<String>,
                               languageValuesOverridePathMap: Map<String, String>,
                               minimumTranslationPercentage: Int,
@@ -128,6 +130,7 @@ object PoEditorStringsImporter {
                     code = languageCode,
                     type = ExportType.ANDROID_STRINGS,
                     filters = filters,
+                    order = order,
                     tags = tags)
 
                 // Download translation File to in-memory string

src/main/kotlin/com/hyperdevs/poeditor/gradle/network/PoEditorApiController.kt

@@ -34,10 +34,12 @@ interface PoEditorApiController {
      * Retrieves the translation file URL for a given project, language code, and export type.
      * Also supports a list of tags to filter.
      */
+    @Suppress("LongParameterList")
     fun getTranslationFileUrl(projectId: Int,
                               code: String,
                               type: ExportType,
                               filters: List<FilterType>?,
+                              order: OrderType,
                               tags: List<String>?): String
 }
 
@@ -53,17 +55,20 @@ class PoEditorApiControllerImpl(private val apiToken: String,
         return response.onSuccessful { it.result.languages }
     }
 
+    @Suppress("LongParameterList")
     override fun getTranslationFileUrl(projectId: Int,
                                        code: String,
                                        type: ExportType,
                                        filters: List<FilterType>?,
+                                       order: OrderType,
                                        tags: List<String>?): String {
         val response = poEditorApi.getExportFileInfo(
             apiToken = apiToken,
             id = projectId,
             type = type.toString().toLowerCase(),
             filters = filters?.map { it.name.toLowerCase() },
             language = code,
+            order = order.name.toLowerCase(),
             tags = tags)
             .execute()
         return response.onSuccessful { it.result.url }

src/main/kotlin/com/hyperdevs/poeditor/gradle/network/api/PoEditorApiModels.kt

@@ -128,3 +128,23 @@ enum class FilterType {
             }
     }
 }
+
+/**
+ * Order types to use in file exports.
+ */
+enum class OrderType {
+    NONE,
+    TERMS;
+
+    companion object {
+        /** Returns the enum value associated to a string value. */
+        fun from(value: String) =
+            try {
+                valueOf(value.toUpperCase())
+            } catch (e: Exception) {
+                val message = "Value \"$value\" is not a valid ${this::class.java.declaringClass.simpleName}; " +
+                              "allowed values are: ${values().joinToString(", ") { "\"${it.name.toLowerCase()}\"" }}"
+                throw IllegalArgumentException(message)
+            }
+    }
+}

src/main/kotlin/com/hyperdevs/poeditor/gradle/tasks/ImportPoEditorStringsTask.kt

@@ -21,6 +21,7 @@ package com.hyperdevs.poeditor.gradle.tasks
 import com.hyperdevs.poeditor.gradle.PoEditorPluginExtension
 import com.hyperdevs.poeditor.gradle.PoEditorStringsImporter
 import com.hyperdevs.poeditor.gradle.network.api.FilterType
+import com.hyperdevs.poeditor.gradle.network.api.OrderType
 import com.hyperdevs.poeditor.gradle.utils.DEFAULT_PLUGIN_NAME
 import com.hyperdevs.poeditor.gradle.utils.POEDITOR_CONFIG_NAME
 import org.gradle.api.DefaultTask
@@ -47,6 +48,7 @@ abstract class ImportPoEditorStringsTask
         val defaultLang: String
         val defaultResPath: String
         val filters: List<FilterType>
+        val order: OrderType
         val tags: List<String>
         val languageOverridePathMap: Map<String, String>
         val minimumTranslationPercentage: Int
@@ -58,6 +60,7 @@ abstract class ImportPoEditorStringsTask
             defaultLang = extension.defaultLang.get()
             defaultResPath = extension.defaultResPath.get()
             filters = extension.filters.get().map { FilterType.from(it) }
+            order = OrderType.from(extension.order.get())
             tags = extension.tags.get()
             languageOverridePathMap = extension.languageValuesOverridePathMap.get()
             minimumTranslationPercentage = extension.minimumTranslationPercentage.get()
@@ -77,6 +80,7 @@ abstract class ImportPoEditorStringsTask
             defaultLang,
             defaultResPath,
             filters,
+            order,
             tags,
             languageOverridePathMap,
             minimumTranslationPercentage,