Migrate to PoEditor API v2

Author: adriangl

CHANGELOG.md

@@ -24,7 +24,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - No new features!
 ### Changed
-- No changed features!
+- Migrate to PoEditor API v2
 ### Deprecated
 - No deprecated features!
 ### Removed

build.gradle.kts

@@ -63,10 +63,12 @@ dependencies {
 
  implementation("com.squareup.moshi:moshi:1.9.2")
  implementation("com.squareup.moshi:moshi-kotlin:1.9.2")
+ implementation("com.squareup.moshi:moshi-adapters:1.9.2")
 
  implementation("com.squareup.retrofit2:retrofit:2.9.0")
  implementation("com.squareup.retrofit2:converter-moshi:2.9.0")
 
+
  implementation("com.squareup.okhttp3:logging-interceptor:4.7.2")
  implementation("com.squareup.okhttp3:okhttp:4.7.2")
 

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

@@ -19,14 +19,15 @@
 package com.hyperdevs.poeditor.gradle
 
 import com.hyperdevs.poeditor.gradle.network.api.PoEditorApi
-import com.hyperdevs.poeditor.gradle.utils.DateJsonAdapter
 import com.hyperdevs.poeditor.gradle.network.PoEditorApiControllerImpl
 import com.hyperdevs.poeditor.gradle.utils.TABLET_REGEX_STRING
 import com.hyperdevs.poeditor.gradle.ktx.downloadUrlToString
+import com.hyperdevs.poeditor.gradle.network.api.ExportType
 import com.hyperdevs.poeditor.gradle.utils.logger
 import com.hyperdevs.poeditor.gradle.xml.AndroidXmlWriter
 import com.hyperdevs.poeditor.gradle.xml.XmlPostProcessor
 import com.squareup.moshi.Moshi
+import com.squareup.moshi.adapters.PoEditorDateJsonAdapter
 import com.squareup.moshi.kotlin.reflect.KotlinJsonAdapterFactory
 import okhttp3.HttpUrl.Companion.toHttpUrl
 import okhttp3.OkHttpClient
@@ -40,11 +41,11 @@ import java.util.concurrent.TimeUnit
  * Main class that does the XML download, parsing and saving from PoEditor files.
  */
 object PoEditorStringsImporter {
- private const val POEDITOR_API_URL = "https://poeditor.com/api/"
+ private const val POEDITOR_API_URL = "https://api.poeditor.com/v2/"
 
  private val moshi = Moshi.Builder()
  .add(KotlinJsonAdapterFactory())
- .add(Date::class.java, DateJsonAdapter())
+ .add(Date::class.java, PoEditorDateJsonAdapter())
  .build()
 
  private const val CONNECT_TIMEOUT_SECONDS = 30L
@@ -98,7 +99,7 @@ object PoEditorStringsImporter {
  val translationFileUrl = poEditorApiController.getTranslationFileUrl(
  projectId = projectId,
  code = languageCode,
- type = "android_strings",
+ type = ExportType.ANDROID_STRINGS,
  tags = tags)
 
  // Download translation File to in-memory string

src/main/kotlin/com/hyperdevs/poeditor/gradle/ktx/DocumentExtensions.kt

@@ -29,11 +29,17 @@ private val DEFAULT_ENCODING = Charsets.UTF_8
 
 /**
  * Converts an XML string to a proper [Document].
+ * If the string is an empty string, it generates a basic <resources> XML.
  */
-fun String.toDocument(): Document =
- DocumentBuilderFactory.newInstance()
+fun String.toStringsXmlDocument(): Document {
+ val xmlString = this.ifBlank {
+ "<resources></resources>"
+ }
+
+ return DocumentBuilderFactory.newInstance()
  .newDocumentBuilder()
- .parse(this.byteInputStream(DEFAULT_ENCODING))
+ .parse(xmlString.byteInputStream(DEFAULT_ENCODING))
+}
 
 /**
  * Converts a [Document] into a formatted [String].

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

@@ -18,6 +18,7 @@
 
 package com.hyperdevs.poeditor.gradle.network
 
+import com.hyperdevs.poeditor.gradle.network.api.ExportType
 import com.hyperdevs.poeditor.gradle.network.api.PoEditorApi
 import com.hyperdevs.poeditor.gradle.network.api.PoEditorResponse
 import com.hyperdevs.poeditor.gradle.network.api.ProjectLanguage
@@ -38,7 +39,7 @@ interface PoEditorApiController {
  */
  fun getTranslationFileUrl(projectId: Int,
  code: String,
- type: String,
+ type: ExportType,
  tags: List<String>?): String
 }
 
@@ -51,27 +52,20 @@ class PoEditorApiControllerImpl(private val apiToken: String,
  val response = poEditorApi.getProjectLanguages(
  apiToken = apiToken,
  id = projectId).execute()
- return response.onSuccessful { it.list }
+ return response.onSuccessful { it.result.languages }
  }
 
- override fun getTranslationFileUrl(projectId: Int, code: String, type: String, tags: List<String>?): String {
+ override fun getTranslationFileUrl(projectId: Int, code: String, type: ExportType, tags: List<String>?): String {
  val response = poEditorApi.getExportFileInfo(
  apiToken = apiToken,
  id = projectId,
- type = type,
+ type = type.toString().toLowerCase(),
  language = code,
- tags = processTags(tags))
+ tags = tags)
  .execute()
- return response.onSuccessful { it.item }
+ return response.onSuccessful { it.result.url }
  }
 
- /**
- * Tags must be in the format: ["tag1", "tag2", ... , "tagN"]
- * Check the documentation for details: https://poeditor.com/api_reference/#export
- */
- private fun processTags(tags: List<String>?): String? =
- tags?.takeIf { it.isNotEmpty() }?.joinToString { "\"$it\"" }?.let { "[$it]" }
-
  private inline fun <T : PoEditorResponse, U> Response<T>.onSuccessful(func: (T) -> U): U {
  if (isSuccessful && body()?.response?.code == "200") {
  body()?.let { return func(it) }

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

@@ -30,20 +30,21 @@ interface PoEditorApi {
  * Returns a list of languages that the current PoEditor project contains.
  */
  @FormUrlEncoded
- @POST("/api/")
+ @POST("languages/list")
  fun getProjectLanguages(@Field("api_token") apiToken: String,
- @Field("action") action: String = "list_languages",
- @Field("id") id: Int): Call<ListProjectLanguagesResponse>
+ @Field("id") id: Int): Call<ListLanguagesResponse>
 
  /**
  * Returns the exportables ready to retrieve from the current PoEditor project.
  */
  @FormUrlEncoded
- @POST("/api/")
+ @POST("projects/export")
  fun getExportFileInfo(@Field("api_token") apiToken: String,
  @Field("id") id: Int,
- @Field("action") action: String = "export",
- @Field("type") type: String,
  @Field("language") language: String,
- @Field("tags") tags: String?): Call<ExportResponse>
+ @Field("type") type: String,
+ @Field("filters") filters: List<String>? = null,
+ @Field("order") order: String? = null,
+ @Field("tags") tags: List<String>? = null,
+ @Field("options") options: Map<String, String>? = null): Call<ExportResponse>
 }

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

@@ -25,29 +25,91 @@ import java.util.Date
  */
 open class PoEditorResponse(open val response: ResponseStatus)
 
+/**
+ * Basic response data.
+ */
+data class ResponseStatus(val status: String,
+ val code: String,
+ val message: String)
+
 /**
  * PoEditor response to "list languages" call.
  */
-data class ListProjectLanguagesResponse(override val response: ResponseStatus,
- val list: List<ProjectLanguage>) : PoEditorResponse(response)
+data class ListLanguagesResponse(override val response: ResponseStatus,
+ val result: ListLanguagesResult) : PoEditorResponse(response)
+
+/**
+ * Result of a "list language" call.
+ */
+data class ListLanguagesResult(val languages: List<ProjectLanguage>)
 
 /**
  * PoEditor response to "export languages" call.
  */
 data class ExportResponse(override val response: ResponseStatus,
- val item: String) : PoEditorResponse(response)
+ val result: ExportResult) : PoEditorResponse(response)
 
 /**
- * Basic response data.
+ * Result of a "list language" call.
  */
-data class ResponseStatus(val status: String,
- val code: String,
- val message: String)
+data class ExportResult(val url: String)
 
 /**
  * Information about a language in PoEditor.
  */
 data class ProjectLanguage(val name: String,
  val code: String,
+ val translations: Int,
  val percentage: Double,
- val updated: Date?)
+ val updated: Date?)
+
+/**
+ * Types of file export allowed in PoEditor.
+ */
+enum class ExportType {
+ PO,
+ POT,
+ MO,
+ XLS,
+ XLSX,
+ CSV,
+ INI,
+ RESW,
+ RESX,
+ ANDROID_STRINGS,
+ APPLE_STRINGS,
+ XLIFF,
+ PROPERTIES,
+ KEY_VALUE_JSON,
+ JSON,
+ YML,
+ XLF,
+ XMB,
+ XTB,
+ ARB,
+ RISE_360_XLIFF;
+
+ companion object {
+ /** Returns the enum value associated to a string value. */
+ fun from(filterString: String) = valueOf(filterString.toUpperCase())
+ }
+}
+
+/**
+ * Filter types to use in file exports.
+ */
+enum class FilterType {
+ TRANSLATED,
+ UNTRANSLATED,
+ FUZZY,
+ NOT_FUZZY,
+ AUTOMATIC,
+ NOT_AUTOMATIC,
+ PROOFREAD,
+ NOT_PROOFREAD;
+
+ companion object {
+ /** Returns the enum value associated to a string value. */
+ fun from(filterString: String) = valueOf(filterString.toUpperCase())
+ }
+}

src/main/kotlin/com/hyperdevs/poeditor/gradle/utils/DateJsonAdapter.kt

@@ -19,14 +19,13 @@
 package com.hyperdevs.poeditor.gradle.xml
 
 import com.hyperdevs.poeditor.gradle.ktx.toAndroidXmlString
-import com.hyperdevs.poeditor.gradle.ktx.toDocument
+import com.hyperdevs.poeditor.gradle.ktx.toStringsXmlDocument
 import com.hyperdevs.poeditor.gradle.ktx.unescapeHtmlTags
 import com.hyperdevs.poeditor.gradle.utils.ALL_REGEX_STRING
 import org.w3c.dom.Document
 import org.w3c.dom.Element
 import org.w3c.dom.Node
 import org.w3c.dom.NodeList
-import javax.xml.parsers.DocumentBuilderFactory
 
 /**
  * Class that handles XML transformation.
@@ -61,7 +60,7 @@ class XmlPostProcessor {
  */
  fun formatTranslationXml(translationFileXmlString: String): String {
  // Parse line by line by traversing the original file using DOM
- val translationFileXmlDocument = translationFileXmlString.toDocument()
+ val translationFileXmlDocument = translationFileXmlString.toStringsXmlDocument()
 
  formatTranslationXmlDocument(translationFileXmlDocument, translationFileXmlDocument.childNodes)
 
@@ -101,9 +100,7 @@ class XmlPostProcessor {
  */
  fun splitTranslationXml(translationXmlString: String,
  fileSplitRegexStringList: List<String>): Map<String, Document> {
- val translationFileRecords = DocumentBuilderFactory.newInstance()
- .newDocumentBuilder()
- .parse(translationXmlString.byteInputStream(DEFAULT_ENCODING))
+ val translationFileRecords = translationXmlString.toStringsXmlDocument()
 
  return fileSplitRegexStringList
  .map { regex ->
@@ -115,9 +112,7 @@ class XmlPostProcessor {
  .mapValues { (regexString, nodes) ->
  val regex = Regex(regexString)
  val xmlString = "<resources></resources>"
- val xmlRecords = DocumentBuilderFactory.newInstance()
- .newDocumentBuilder()
- .parse(xmlString.byteInputStream(DEFAULT_ENCODING))
+ val xmlRecords = xmlString.toStringsXmlDocument()
  nodes.forEach { node ->
  node.parentNode.removeChild(node)
  val copiedNode = (node.cloneNode(true) as Element).apply {