document translation medium and other models

KingsMentor · KingsMentor · commit 3b128cef20f1 · 2020-06-30T22:43:59.000-04:00
diff --git a/app/src/main/java/com/example/phrase/MainActivity.kt b/app/src/main/java/com/example/phrase/MainActivity.kt
@@ -28,29 +28,28 @@ class MainActivity : AppCompatActivity() {
 
         val font = Typeface.createFromAsset(assets, "rb.ttf")
         // setting up phrase
-        val p = phrase {
-            mediums = listOf(GoogleTranslate(this@MainActivity, R.raw.credential))
-            options = options {
-                targeting = target.text.toString()
-                preferredSources = listOf("es", "yo")
-                sourceTranslation = listOf(SourceTranslationRule("fr", listOf("en")))
-                behaviour = behaviour {
-                    flags = setOf(Behaviour.BEHAVIOR_TRANSLATE_PREFERRED_OPTION_ONLY)
-                    signatureTypeface = font
-                    signatureColor =
-                        ContextCompat.getColor(this@MainActivity, R.color.white)
-                }
-                actionLabel = { detected ->
-                    "Translate"
-                }
+        val pOptions = options {
+            targeting = target.text.toString()
+            preferredSources = listOf("es", "yo")
+            sourceTranslation = listOf(SourceTranslationRule("fr", listOf("en")))
+            behaviour = behaviour {
+                flags = setOf(Behaviour.BEHAVIOR_TRANSLATE_PREFERRED_OPTION_ONLY)
+                signatureTypeface = font
+                signatureColor =
+                    ContextCompat.getColor(this@MainActivity, R.color.white)
+            }
+            actionLabel = { detected ->
+                "Translate"
+            }
 
-                resultActionLabel = { phraseTranslation ->
-                    "Translated from ${phraseTranslation.detectedSource?.languageName} by "
-                }
+            resultActionLabel = { phraseTranslation ->
+                "Translated from ${phraseTranslation.detectedSource?.languageName} by "
             }
         }
-        p.de
-
+        val phrase = phrase {
+            mediums = listOf(GoogleTranslate(this@MainActivity, R.raw.credential))
+            options = pOptions
+        }
 
         phraseSpannableBuilder =
             object : PhraseSpannableBuilder("", null) {
@@ -70,6 +69,7 @@ class MainActivity : AppCompatActivity() {
 
 
         update_source.setOnClickListener {
+            pOptions.targetLanguageCode = target.text.toString()
             phraseSpannableBuilder.updateSource(source_edit.text.toString())
         }
     }
diff --git a/phrase/src/main/java/xyz/belvi/phrase/helpers/PhraseSpannableBuilder.kt b/phrase/src/main/java/xyz/belvi/phrase/helpers/PhraseSpannableBuilder.kt
@@ -79,12 +79,24 @@ abstract class PhraseSpannableBuilder constructor(
      */
     private fun options() = phraseOptions ?: Phrase.instance().phraseImpl.phraseOptions
 
+    /**
+     * build string to include original text and a translate actionLabel.
+     * Phrase adds translate actionLabel based options provided via phraseOptions.
+     * First, sourceLanguage is detected
+     * then, sourceLanguage is unable to be detected, translation actionLabel is not appended to source (if user doesn't set BEHAVIOR_IGNORE_DETECTION)
+     */
     private fun buildTranslateActionSpan(source: CharSequence) {
         init()
         GlobalScope.launch(Dispatchers.Main) {
             val options = options() ?: return@launch
             val behaviors = options.behavioursOptions.behaviours
-            val detectedMedium =
+
+            /*
+             * detected source language. is sourceLanguage is provided, we want to skip language detection.
+             * if sourceLanguage is not provided and BEHAVIOR_IGNORE_DETECTION is set, phraseDetected is null since we want to skip language detection.
+             * Otherwise,  Phrase.instance().detectLanguage(source.toString()) is executed.
+             */
+            val phraseDetected =
                 sourceLanguage?.let { sourceLanguage ->
                     val languageName =
                         Languages.values().find { it.code == sourceLanguage.toLowerCase() }?.name
@@ -104,18 +116,43 @@ abstract class PhraseSpannableBuilder constructor(
                     }
                 }
 
-            detectedMedium?.let { phraseDetected ->
+            if (options.excludeSources.indexOfFirst {
+                    it.toLowerCase() == (phraseDetected?.languageCode ?: "").toLowerCase()
+                } < 0) {
+
+            }
+            /* with the detected sourceLanguage, check to see if there's any rule that check against translating from the source language at all
+             */
+
+            phraseDetected?.let { detected ->
+                // halt this process if the sourceLangauge is part of the excluded list or it is same with the target langauge,
+                if (detected.languageCode.equals(
+                        options.targetLanguageCode.toLowerCase(),
+                        true
+                    ) || options.excludeSources.indexOfFirst {
+                        it.equals(
+                            detected.languageCode,
+                            true
+                        )
+                    } > 0
+                ) {
+                    actionStatus = ActionStatus.SHOWING_SOURCE
+                    onContentChanged(this@PhraseSpannableBuilder)
+                    return@launch
+                }
 
+                // if options supports translation of only preferred sources, check if sourceLanguage is in preferred list.
                 var allowTranslation =
                     if (options.behavioursOptions.behaviours.translatePreferredSourceOnly()) {
                         options.preferredSources.indexOfFirst {
-                            it.equals(phraseDetected.languageCode, true)
+                            it.equals(detected.languageCode, true)
                         } >= 0
                     } else {
                         true
                     }
+                // check if source langauge is defined in languageTranslation preference
                 allowTranslation =
-                    (options.sourcePreferredTranslation.sourceTranslateRule.filter { it.sourceLanguageCode.toLowerCase() == phraseDetected.languageCode.toLowerCase() }
+                    (options.sourcePreferredTranslation.sourceTranslateRule.filter { it.sourceLanguageCode.toLowerCase() == detected.languageCode.toLowerCase() }
                         .let { sourceOptions ->
                             sourceOptions.find { sourceTranslationOption ->
                                 sourceTranslationOption.targetLanguageCode.indexOfFirst {
@@ -129,36 +166,25 @@ abstract class PhraseSpannableBuilder constructor(
                             }?.let { true }
                                 ?: !options.behavioursOptions.behaviours.translatePreferredSourceOnly()
                         }) || allowTranslation
+                // if source language is neither in sourcePreferredTranslation nor preferredSources and BEHAVIOR_TRANSLATE_PREFERRED_OPTION_ONLY is set, actionLable for translation shouldn't be appended to this string.
                 if (!allowTranslation) {
                     actionStatus = ActionStatus.SHOWING_SOURCE
                     onContentChanged(this@PhraseSpannableBuilder)
                     return@launch
                 }
-
-                if (phraseDetected.languageCode.equals(
-                        options.targetLanguageCode.toLowerCase(),
-                        true
-                    ) || options.excludeSources.indexOfFirst {
-                        it.equals(
-                            phraseDetected.languageCode,
-                            true
-                        )
-                    } > 0
-                ) {
-                    actionStatus = ActionStatus.SHOWING_SOURCE
-                    onContentChanged(this@PhraseSpannableBuilder)
-                    return@launch
-                }
             }
-
-            if (detectedMedium == null && !behaviors.ignoreDetection()) {
+            // another check to ensure nullable phraseDetected is only allowed for BEHAVIOR_IGNORE_DETECTION
+            if (phraseDetected == null && !behaviors.ignoreDetection()) {
                 onContentChanged(this@PhraseSpannableBuilder)
                 return@launch
             }
+            // final check to confirm original text is not empty.
+            // also, actionLabel is appended only if BEHAVIOR_HIDE_TRANSLATE_PROMPT is not set and source is not same with the content of PhraseSpannableBuilder (to avoid text repetition)
             if (!source.isNullOrBlank() && !behaviors.hideTranslatePrompt() && (this@PhraseSpannableBuilder.toString() == source.toString())) {
                 appendln("\n")
                 val start = length
-                append(options.translateText.invoke(detectedMedium))
+                append(options.translateText.invoke(phraseDetected))
+                // add clickableSpan to actionLabel
                 setSpan(
                     SpannablePhraseClickableSpan(),
                     start,
@@ -172,26 +198,35 @@ abstract class PhraseSpannableBuilder constructor(
         }
     }
 
+    /**
+     * build string to include original text and a translated actionLabel and the translated string
+     * Phrase adds translate resultActionLabel based options provided via phraseOptions.
+     * this is called after translation has happened.
+     */
     private fun buildTranslatedPhraseSpan() {
         val options = options() ?: return
         val optionBehavior = options.behavioursOptions.behaviours
         phraseTranslation?.let { phraseTranslation ->
             init()
-            appendln("\n")
+            // if BEHAVIOR_REPLACE_SOURCE_TEXT is set, we want to replace the source text with translation.
             if (optionBehavior.replaceSourceText()) {
                 clear()
             }
+            // resultActionLabel is appeneded to result is BEHAVIOR_HIDE_TRANSLATE_PROMPT is not set.
             if (!optionBehavior.hideTranslatePrompt()) {
                 var start = length
                 append(options.translateFrom.invoke(phraseTranslation))
+                // add clickableSpan to resultActionLabel
                 setSpan(
                     SpannablePhraseClickableSpan(),
                     start,
                     length,
                     Spanned.SPAN_EXCLUSIVE_EXCLUSIVE
                 )
+                // style translation medium name.
                 if (!optionBehavior.hideSignature()) {
                     start = length
+                    appendln("\n")
                     append("${phraseTranslation.translationMediumName}")
                     options.behavioursOptions.signatureTypeFace?.let { typeFace ->
                         setSpan(
@@ -214,8 +249,8 @@ abstract class PhraseSpannableBuilder constructor(
                         )
                     }
                 }
-                appendln("\n")
             }
+            appendln("\n")
             append(phraseTranslation.translation)
             actionStatus = ActionStatus.SHOWING_TRANSLATED
             onContentChanged(this@PhraseSpannableBuilder)
@@ -234,21 +269,30 @@ abstract class PhraseSpannableBuilder constructor(
         append(source)
     }
 
+    /**
+     * customer ClickableSpan impementation to handle click actions on actionLabel and resultActionLabel
+     */
     inner class SpannablePhraseClickableSpan : ClickableSpan() {
         override fun onClick(widget: View) {
             onActionClick(actionStatus)
+            // if text is currently prompting user to translate
             if (actionStatus == ActionStatus.SHOWING_WITH_TRANSLATE_ACTION) {
+                // notify listener of tranalation
                 onPhraseTranslating()
+                // translate text
                 GlobalScope.launch(Dispatchers.Main) {
                     val options = options()
                     phraseTranslation =
                         withContext(Dispatchers.IO) {
                             Phrase.instance().translate(source.toString(), options)
                         }
                 }
+                // build translated string
                 buildTranslatedPhraseSpan()
+                // notify listener of translation
                 onPhraseTranslated(phraseTranslation)
             } else {
+                // resultActionLabel is clicked, show original state of text
                 buildTranslateActionSpan(source)
             }
             widget.invalidate()
diff --git a/phrase/src/main/java/xyz/belvi/phrase/helpers/PhraseTextWatcher.kt b/phrase/src/main/java/xyz/belvi/phrase/helpers/PhraseTextWatcher.kt
@@ -69,8 +69,10 @@ open class PhraseTextWatcher(
     }
 
     override fun onTextChanged(s: CharSequence?, start: Int, before: Int, count: Int) {
+        // we do not want to update source for empty string.
         if (s.isNullOrBlank())
             return
+        // only update source when changes is not same with current content of phraseSpannableBuilder
         if (s.toString() != phraseSpannableBuilder.toString())
             phraseSpannableBuilder.updateSource(s.subSequence(0, s.length), sourceLanguage)
     }
diff --git a/phrase/src/main/java/xyz/belvi/phrase/options/Models.kt b/phrase/src/main/java/xyz/belvi/phrase/options/Models.kt
@@ -7,6 +7,14 @@ import xyz.belvi.phrase.options.Behaviour.Companion.BEHAVIOR_IGNORE_DETECTION
 import xyz.belvi.phrase.options.Behaviour.Companion.BEHAVIOR_REPLACE_SOURCE_TEXT
 import xyz.belvi.phrase.options.Behaviour.Companion.BEHAVIOR_TRANSLATE_PREFERRED_OPTION_ONLY
 
+/**
+ * object return when TranlationMedium.detect() is called.
+ * @param text : original text whose source language was detected
+ * @param languageCode: language code of detected language
+ * @param languageName: language name of detected language
+ * @param detectionMediumName: medium used in detecting text
+ * @param fromCache: there was no new api call made to retrieve this result. It was fetched from cache
+ */
 data class PhraseDetected(
     val text: String,
     val languageCode: String,
@@ -15,24 +23,51 @@ data class PhraseDetected(
     val fromCache: Boolean = false
 )
 
+/**
+ * used by Phrase to handle text Translation
+ * @param translation : translated text
+ * @param detectedSource: PhraseDetected object for the original text
+ * @param fromCache: there was no new api call made to retrieve this result. It was fetched from cache
+ */
 data class PhraseTranslation(
     val translation: String,
     val translationMediumName: String?,
     val detectedSource: PhraseDetected?,
     val fromCache: Boolean = false
 )
 
+/**
+ * for defining behavior and flags for Phraseoptions
+ * @param behaviorSet is a set of @BehaviorFlags
+ */
 class Behaviour(private val behaviorSet: Set<@BehaviorFlags Int> = setOf()) {
 
     companion object {
+        /**
+         *  include this flag if translated text should be replaced by source text
+         */
         const val BEHAVIOR_REPLACE_SOURCE_TEXT: Int = 1
-
+        /**
+         *  include this flag if Phrase should only run translation for languageCode included in PhraseOptions preferredSource and sourceTranslationPreference.
+         */
         const val BEHAVIOR_TRANSLATE_PREFERRED_OPTION_ONLY: Int = 2
 
+        /**
+         *  include this flag if Phrase should ignore language detection before processing translation.
+         *  This is helpful if you already know the source language of the original text (in this case, ensure source language is pass to PhraseSpannableBuilder or
+         *  PhraseTextView.prepare(), depending on the Implementation of Phrase you are using.)
+         *  @see https://github.com/KingsMentor/Phrase documentation.
+         */
         const val BEHAVIOR_IGNORE_DETECTION: Int = 3
 
+        /**
+         *  include this flag if Phrase should not include translationMediumName to resultActionLabel
+         */
         const val BEHAVIOR_HIDE_CREDIT: Int = 4
 
+        /**
+         *  include this flag if Phrase not show actionLabel ot resultActionLabel at all.
+         */
         const val BEHAVIOR_HIDE_TRANSLATE_PROMPT: Int = 5
     }
 
diff --git a/phrase/src/main/java/xyz/belvi/phrase/translateMedium/Languages.kt b/phrase/src/main/java/xyz/belvi/phrase/translateMedium/Languages.kt
@@ -1,5 +1,9 @@
 package xyz.belvi.phrase.translateMedium
 
+/**
+ * source language code.
+ * @see 'https://cloud.google.com/translate/docs/languages' for an updated list.
+ */
 enum class Languages(val code: String) {
     Afrikaans("af"),
     Albanian("sq"),
diff --git a/phrase/src/main/java/xyz/belvi/phrase/translateMedium/TranslationMedium.kt b/phrase/src/main/java/xyz/belvi/phrase/translateMedium/TranslationMedium.kt

Original file line number	Diff line number	Diff line change
`@@ -69,8 +69,10 @@ open class PhraseTextWatcher(`
`69`	`69`	`}`
`70`	`70`
`71`	`71`	`override fun onTextChanged(s: CharSequence?, start: Int, before: Int, count: Int) {`
	`72`	`+ // we do not want to update source for empty string.`
`72`	`73`	`if (s.isNullOrBlank())`
`73`	`74`	`return`
	`75`	`+ // only update source when changes is not same with current content of phraseSpannableBuilder`
`74`	`76`	`if (s.toString() != phraseSpannableBuilder.toString())`
`75`	`77`	`phraseSpannableBuilder.updateSource(s.subSequence(0, s.length), sourceLanguage)`
`76`	`78`	`}`