[Android] Add comments and explanations

[Nicolas Pomepuy]

vlc-android | branch: master | Nicolas Pomepuy <nicolas at videolabs.io> | Fri Oct 15 07:38:33 2021 +0200| [002bf553a55cff32de42384d9ef9a489c4d89571] | committer: Nicolas Pomepuy

Add comments and explanations

> https://code.videolan.org/videolan/vlc-android/commit/002bf553a55cff32de42384d9ef9a489c4d89571
---

 .../src/org/videolan/vlc/gui/video/VideoPlayerActivity.kt   |  1 +
 .../vlc-android/src/org/videolan/vlc/util/LocaleUtil.kt     | 13 +++++++++++++
 2 files changed, 14 insertions(+)

diff --git a/application/vlc-android/src/org/videolan/vlc/gui/video/VideoPlayerActivity.kt b/application/vlc-android/src/org/videolan/vlc/gui/video/VideoPlayerActivity.kt
index 5cfd0abe0..5c1e6db63 100644
--- a/application/vlc-android/src/org/videolan/vlc/gui/video/VideoPlayerActivity.kt
+++ b/application/vlc-android/src/org/videolan/vlc/gui/video/VideoPlayerActivity.kt
@@ -1257,6 +1257,7 @@ open class VideoPlayerActivity : AppCompatActivity(), PlaybackService.Callback,
                                 var preferredTrack = 0
                                 val preferredAudioLang = settings.getString(AUDIO_PREFERRED_LANGUAGE, "")
                                 if (!preferredAudioLang.isNullOrEmpty()) {
+                                    /** ⚠️limitation: See [LocaleUtil] header comment */
                                     val allTracks = getCurrentMediaTracks()
                                     service.audioTracks?.iterator()?.let { audioTracks ->
                                         while (audioTracks.hasNext()) {
diff --git a/application/vlc-android/src/org/videolan/vlc/util/LocaleUtil.kt b/application/vlc-android/src/org/videolan/vlc/util/LocaleUtil.kt
index 5ed0e639e..9bfebdd7e 100644
--- a/application/vlc-android/src/org/videolan/vlc/util/LocaleUtil.kt
+++ b/application/vlc-android/src/org/videolan/vlc/util/LocaleUtil.kt
@@ -28,10 +28,23 @@ import com.squareup.moshi.Json
 import com.squareup.moshi.JsonAdapter
 import com.squareup.moshi.Moshi
 import com.squareup.moshi.Types
+import org.videolan.libvlc.interfaces.IMedia
+import org.videolan.libvlc.MediaPlayer
 import org.videolan.resources.AppContextProvider
 import org.videolan.tools.firstLetterUppercase
 import java.util.*
 
+/**
+ * This is a temporary workaround to translate [IMedia.Track.language] sent by libvlc as a string to a real locale.
+ * libvlc 4 should expose the ISO 639 code of the track and therefore [LocaleUtil] and vlc_locales.json could be removed then
+ *
+ * ⚠️ Current limitation: as the language is only exposed in [IMedia.Track.language] that can be retrieved from a media,
+ * external tracks (as subtitle from files) won't be checked during the playback. This is because the tracks retrieved from the
+ * [MediaPlayer] only have a description and no language. So we have to compare them to the tracks from the media that doesn't
+ * include the external tracks.
+ *
+ * FIXME Remove this when libvlc exposes a track locale ISO code
+ */
 object LocaleUtil {
 
     /**