From f7b17640f2125fbb1c9f337edbdc2d2bd623ee98 Mon Sep 17 00:00:00 2001
From: Darcy Wong <darcy_wong@sil.org>
Date: Thu, 6 Aug 2020 11:25:25 +0700
Subject: [PATCH] chore(android): Include XML comments for additional context

---
 .../kMAPro/src/main/res/values/strings.xml    | 111 +++++++++++++--
 .../KMEA/app/src/main/res/values/strings.xml  | 129 +++++++++++++++---
 2 files changed, 211 insertions(+), 29 deletions(-)

diff --git a/android/KMAPro/kMAPro/src/main/res/values/strings.xml b/android/KMAPro/kMAPro/src/main/res/values/strings.xml
index 5285e7d34a..5474d4b7da 100644
--- a/android/KMAPro/kMAPro/src/main/res/values/strings.xml
+++ b/android/KMAPro/kMAPro/src/main/res/values/strings.xml
@@ -3,87 +3,172 @@
 
   <string name="app_name" translatable="false">Keyman</string>
 
-  <!-- Menu Actions -->
+  <!-- Context: Menu Action -->
   <string name="action_share" comment="Menu action to send text content to another app">Share</string>
+
+  <!-- Context: Menu Action -->
   <string name="action_web" comment="Menu action to open Keyman browser">Web Browser</string>
+
+  <!-- Context: Menu Action -->
   <string name="action_text_size" comment="Menu action to adjust text size">Text Size</string>
+
+  <!-- Context: Menu Action -->
   <string name="action_overflow" comment="Show additional menu items">More</string>
+
+  <!-- Context: Menu Action -->
   <string name="action_clear_text" comment="Menu action to erase text">Clear Text</string>
+
+  <!-- Context: Menu Action -->
   <string name="action_info" comment="Menu action to display Keyman help page">Info</string>
+
+  <!-- Context: Menu Action -->
   <string name="action_settings" comment="Menu action to open Settings menu">Settings</string>
+
+  <!-- Context: Menu Action -->
   <string name="action_install_updates" comment="Menu notification that keyboard or dictionary updates available">Install Updates</string>
 
+
+  <!-- Context: Title -->
   <string name="title_version" comment="Title of Keyman for Android version">Version: %1$s</string>
 
-  <!-- &#8230; is the ellipsis character "..." -->
+
+  <!-- Context: Textfield prompt (&#8230; is the ellipsis character "...") -->
   <string name="textview_hint" comment="Prompt to start typing">Start typing here&#8230;</string>
 
-  <!-- Splash screen (version/copyright info currently disabled -->
+  <!-- Context: Splash screen (version/copyright info currently disabled -->
   <string name="splash_blank" translatable="false" comment="Blank text while version info on splash page is disabled"></string>
+
+  <!-- Context: Splash screen (version/copyright info currently disabled -->
   <string name="splash_copyright" translatable="false" comment="Placeholder for copyright text while version info on splash page is disabled">Copyright &#169; 1992-</string>
 
-  <!-- Text Size dialog -->
+
+  <!-- Context: Text Size dialog -->
   <string name="text_size" comment="Current text size (number)">Text Size: %1$d</string>
+
+  <!-- Context: Text Size dialog -->
   <string name="ic_text_size_up" comment="Make text bigger">Text size up</string>
+
+  <!-- Context: Text Size dialog -->
   <string name="ic_text_size_down" comment="Make text smaller">Text size down</string>
 
-  <!-- Clear Text dialog -->
+
+  <!-- Context: Clear Text dialog -->
   <string name="all_text_will_be_cleared" comment="Erase all the text">\nAll text will be cleared\n</string>
 
-  <!-- Info screen reuses title_version -->
 
-  <!-- Get Started menu strings -->
+  <!-- Context: Get Started menu -->
   <string name="get_started" comment="Menu for getting started">Get Started</string>
+
+  <!-- Context: Get Started menu -->
   <string name="add_a_keyboard" comment="Menu item to add a keyboard">Add a keyboard for your language</string>
+
+  <!-- Context: Get Started menu -->
   <string name="enable_system_keyboard" comment="Menu item to enable Keyman as system keyboard">Enable Keyman as system-wide keyboard</string>
+
+  <!-- Context: Get Started menu -->
   <string name="set_keyman_as_default" comment="Menu item to set Keyman as default system keyboard">Set Keyman as default keyboard</string>
+
+  <!-- Context: Get Started menu -->
   <string name="more_info" comment="Open the Keyman for Android help page">More info</string>
+
+  <!-- Context: Get Started menu -->
   <string name="show_get_started" comment="Show the &quot;Get Started&quot; menu on startup">Show \"%1$s\" on startup</string>
 
 
-  <!-- Keyman Settings menu strings -->
+  <!-- Context: Keyman Settings menu -->
   <string name="keyman_settings" comment="Settings menu title">Settings</string>
+
+  <!-- Context: Keyman Settings menu -->
   <plurals name="installed_languages">
     <item quantity="zero">Installed languages</item>
     <item quantity="other">Installed languages (%1$d)</item>
   </plurals>
+
+  <!-- Context: Keyman Settings menu -->
   <string name="install_keyboard_or_dictionary" comment="Menu item to install keyboard or dictionary">Install Keyboard or Dictionary</string>
+
+  <!-- Context: Keyman Settings menu -->
   <string name="show_banner" comment="text suggestions banner">Always show banner</string>
+
+  <!-- Context: Keyman Settings menu -->
   <string name="show_banner_on" comment="Description when toggle is on">To be implemented</string>
+
+  <!-- Context: Keyman Settings menu -->
   <string name="show_banner_off" comment="Description when toggle is off">When off, only shown when predictive text is enabled</string>
 
-  <!-- reuse show_get_started string in Settings menu -->
 
-  <!-- Keyman Settings "Install Keyboard or Dictionary" menu strings -->
+  <!-- Context: Keyman Settings "Install Keyboard or Dictionary" menu -->
   <string name="install_from_keyman_dot_com" comment="Install package from Keyman server">Install from keyman.com</string>
+
+  <!-- Context: Keyman Settings "Install Keyboard or Dictionary" menu -->
   <string name="install_from_local_file" comment="Install package file from local device">Install from local file</string>
+
+  <!-- Context: Keyman Settings "Install Keyboard or Dictionary" menu -->
   <string name="install_from_other_device" comment="Scan QR Code">Install from other device</string>
+
+  <!-- Context: Keyman Settings "Install Keyboard or Dictionary" menu -->
   <string name="add_language_to_installed_keyboard" comment="Install another language from a keyboard package">Add language to installed keyboard</string>
+
+  <!-- Context: Keyman Settings "Install Keyboard or Dictionary" menu -->
   <string name="add_language_subtext" comment="Additional information for adding another language">(from keyboard package)</string>
 
-  <!-- Select Package and Select Language menu strings -->
+
+  <!-- Context: Select Package and Select Language menu -->
   <string name="title_select_keyboard_package_list" comment="Select a keyboard package to add a language">Select Keyboard Package</string>
+
+  <!-- Context: Select Package and Select Language menu -->
   <string name="title_select_language_for_package" comment="Select a language name from the keyboard package">Select language for %1$s</string>
+
+  <!-- Context: Select Package and Select Language menu -->
   <string name="added_language_to_keyboard" comment="Notification that a language name is added to a keyboard">Added language %1$s to %2$s</string>
+
+  <!-- Context: Select Package and Select Language menu -->
   <string name="all_languages_installed" comment="Text when all languages from a keyboard package have been installed">All languages already installed</string>
 
-  <!-- Web Browser strings -->
+
+  <!-- Context: Keyman Web Browser -->
   <string name="hint_text" comment="Prompt to type in the browser search bar">Search or type URL</string>
+
+  <!-- Context: Keyman Web Browser -->
   <string name="title_bookmarks" comment="Title for bookmarks">Bookmarks</string>
+
+  <!-- Context: Keyman Web Browser -->
   <string name="no_bookmarks" comment="Text when bookmark list is empty">No Bookmarks</string>
+
+  <!-- Context: Keyman Web Browser -->
   <string name="add_bookmark" comment="Confirmation to add bookmark">Add Bookmark</string>
+
+  <!-- Context: Keyman Web Browser -->
   <string name="hint_title" comment="Page title for saved bookmark">Title</string>
+
+  <!-- Context: Keyman Web Browser -->
   <string name="hint_url" comment="Page URL for saved bookmark">Url</string>
 
-  <!-- KMP Package strings -->
+  <!-- Context: KMP Package strings -->
   <string name="title_package_failed_to_install" comment="Error dialog title when package failed to install">Package %1$s failed to install</string>
+
+  <!-- Context: KMP Package strings -->
   <string name="downloading_keyboard_package" comment="Confirmation to download keyboard package filename">Downloading keyboard package\n%1$s&#8230;</string>
+
+  <!-- Context: KMP Package strings -->
   <string name="failed_to_extract" comment="Notification that keyboard package failed to unzip">Failed to extract</string>
+
+  <!-- Context: KMP Package strings -->
   <string name="install_keyboard_package" comment="Title to install keyboard package">Install Keyboard Package %1$s</string>
+
+  <!-- Context: KMP Package strings -->
   <string name="install_predictive_text_package" comment="Title to install dictionary package">Install Predictive Text Package %1$s</string>
+
+  <!-- Context: KMP Package strings -->
   <string name="no_new_touch_keyboards_to_install" comment="Notification when no touch-optimized keyboards can be installed">No new touch-optimized keyboards to install</string>
+
+  <!-- Context: KMP Package strings -->
   <string name="no_new_predictive_text_to_install" comment="Notification when no dictionaries can be installed">No new predictive text to install</string>
+
+  <!-- Context: KMP Package strings -->
   <string name="no_targets_to_install" comment="Notification when a package doesn't contain keyboards or dictionaries">No keyboards or predictive text to install</string>
+
+  <!-- Context: KMP Package strings -->
   <string name="invalid_metadata" comment="kmp.json metadata file is invalid or missing in package">Invalid/Missing metadata in package</string>
 
 </resources>
diff --git a/android/KMEA/app/src/main/res/values/strings.xml b/android/KMEA/app/src/main/res/values/strings.xml
index 8f36d987c2..7f6ccb2251 100644
--- a/android/KMEA/app/src/main/res/values/strings.xml
+++ b/android/KMEA/app/src/main/res/values/strings.xml
@@ -7,95 +7,192 @@
     <!-- Application name (Keyman Engine for Android) -->
     <string name="app_name" translatable="false">KMEA</string>
     
-    <!-- Title for lists-->
+    <!-- Context: Title for list -->
     <plurals name="title_keyboards">
       <item quantity="one">Keyboard</item>
       <item quantity="other">Keyboards</item>
     </plurals>
+
+    <!-- Context: Title for list -->
     <string name="title_add_keyboard" comment="Add a new keyboard">Add New Keyboard</string>
+
+    <!-- Context: Title for list -->
     <string name="title_languages_settings" comment="List of installed languages">Installed Languages</string>
+
+    <!-- Context: Title for list -->
     <string name="title_language_settings" comment="Keyman Settings for a language">%1$s Settings</string>
 
-    <!-- Button labels -->
+
+    <!-- Context: Button label -->
     <string name="label_add" comment="Button to add an item">Add</string>
+
+    <!-- Context: Button label -->
     <string name="label_cancel" comment="Button to cancel an action">Cancel</string>
+
+    <!-- Context: Button label -->
     <string name="label_close" comment="Close a dialog">Close</string>
+
+    <!-- Context: Button label -->
     <string name="label_close_keyman" comment="Close the Keyman application">Close Keyman</string>
+
+    <!-- Context: Button label -->
     <string name="label_download" comment="Button to confirm downloading an item">Download</string>
+
+    <!-- Context: Button label -->
     <string name="label_install" comment="Confirmation to install a package">Install</string>
+
+    <!-- Context: Button label -->
     <string name="label_later" comment="Do an action at a later time">Later</string>
+
+    <!-- Context: Button label -->
     <string name="label_ok" comment="Button to acknowledge a dialog">OK</string>
+
+    <!-- Context: Button label -->
     <string name="label_update" comment="Dialog button to update a resource">Update</string>
 
-    <!-- Keyboard Updates -->
+
+    <!-- Context: Keyboard Updates -->
     <string name="cannot_connect" comment="Error message when network connection fails">\nCannot connect to Keyman server!\n</string>
+
+    <!-- Context: Keyboard Updates -->
     <string name="confirm_delete_keyboard" comment="Confirmation to delete a keyboard">Would you like to delete this keyboard?</string>
+
+    <!-- Context: Keyboard Updates -->
     <string name="confirm_download_keyboard" comment="Confirmation to download a keyboard update">Would you like to download the latest version of this keyboard?</string>
+
+    <!-- Context: Keyboard Updates -->
     <string name="confirm_update" comment="Confirmation to update several resources">Would you like to update keyboards and dictionaries now?</string>
+
+    <!-- Context: Keyboard Updates -->
     <string name="keyboard_updates_channel">Resource Updates</string>
+
+    <!-- Context: Keyboard Updates -->
     <string name="keyboard_updates_available" comment="Notification when resource updates are available">Resource Updates Available</string>
+
+    <!-- Context: Keyboard Updates -->
     <string name="update_available" comment="Currently installed version of a resource with an available update">%1$s (Update Available)</string>
+
+    <!-- Context: Keyboard Updates -->
     <string name="keyboard_update_message" comment="language name: keyboard name">
       Updates available for keyboard %1$s: %2$s </string>
+
+    <!-- Context: Keyboard Updates -->
     <string name="dictionary_update_message">Updates available for dictionary %1$s: %2$s </string>
 
-    <!-- Keyboard Info and Keyboard Settings -->
+
+    <!-- Context: Keyboard Info and Keyboard Settings -->
     <string name="keyboard_version" comment="Label for keyboard version">Keyboard version</string>
+
+    <!-- Context: Keyboard Info and Keyboard Settings -->
     <string name="help_link" comment="Label for help link">Help link</string>
+
+    <!-- Context: Keyboard Info and Keyboard Settings -->
     <string name="uninstall_keyboard" comment="Label for uninstalling keyboard">Uninstall keyboard</string>
+
+    <!-- Context: Keyboard Info and Keyboard Settings -->
     <string name="keyboard_picker_new_keyboard" comment="Mark a language name that's newly installed in keyboard list">[new] %1$s</string>
+
+    <!-- Context: Keyboard Info and Keyboard Settings -->
     <string name="keyboard_qr_code" comment="QR Code description">
       Scan this code to load this\nkeyboard on another device</string>
 
-    <!-- Model Updates -->
+
+    <!-- Context: Model Updates -->
     <string name="confirm_download_model" comment="Confirmation to download a dictionary update">Would you like to download the latest version of this dictionary?</string>
+
+    <!-- Context: Model Updates -->
     <string name="catalog_unavailable" comment="Notification that the cloud resource catalog can't be updated">The resource catalog is unavailable</string>
 
-  <!-- Background download messages-->
+
+    <!-- Context: Background download messages-->
     <string name="catalog_download_start_in_background" comment="Notification that the resource catalog update will begin">Catalog update started in background</string>
+
+    <!-- Context: Background download messages-->
     <string name="catalog_download_is_running_in_background" comment="Notification that the resource catalog update is still downloading">
       The catalog is still downloading; please try again in a moment!</string>
+
+    <!-- Context: Background download messages-->
     <string name="progress_message_catalog_download_is_running" comment="Progress notification that the resource catalog update is still running ">The catalog is still downloading!</string>
+
+    <!-- Context: Background download messages-->
     <string name="keyboard_download_start_in_background" comment="Notification that a keyboard download has started">Downloading keyboard started in Background</string>
+
+    <!-- Context: Background download messages-->
     <string name="keyboard_download_is_running_in_background" comment="Notification that a keyboard download is still running">The selected keyboard is already downloading; please try again in a moment!</string>
+
+    <!-- Context: Background download messages-->
     <string name="keyboard_download_finished" comment="Notification that a keyboard download has finished">Keyboard download is finished!</string>
+
+    <!-- Context: Background download messages-->
     <string name="dictionary_download_start_in_background" comment="Notification that a dictionary download has started">Downloading dictionary started in Background</string>
+
+    <!-- Context: Background download messages-->
     <string name="dictionary_download_is_running_in_background" comment="Notification that a dictionary download is still running">The selected dictionary is already downloading; please try again in a moment!</string>
+
+    <!-- Context: Background download messages-->
     <string name="dictionary_download_finished" comment="Notification that a dictionary download has finished">Dictionary download is finished.</string>
 
-  <!-- General Updates -->
+
+    <!-- Context: General Updates -->
     <string name="update_check_unavailable" comment="Error message when a Keyman server can't be reached">Failed to access server!</string>
+
+    <!-- Context: General Updates -->
     <string name="update_check_current" comment="Notification that all resources are up to date">"All resources are up to date!"</string>
 
-    <!-- Model Info -->
+
+    <!-- Context: Model Info -->
     <string name="model_version" comment="Title for a dictionary version">Dictionary version</string>
+
+    <!-- Context: Model Info -->
     <string name="uninstall_model" comment="Label to uninstall a dictionary">Uninstall dictionary</string>
+
+    <!-- Context: Model Info -->
     <string name="confirm_delete_model" comment="Confirmation to delete a dictionary">Would you like to delete this dictionary?</string>
 
-    <!-- Language Settings menu strings -->
+
+    <!-- Context: Language Settings menu strings -->
     <string name="enable_corrections" comment="Enable corrections from the suggestion banner">Enable corrections</string>
+
+    <!-- Context: Language Settings menu strings -->
     <string name="enable_predictions" comment="Enable predictions from the suggestion banner">Enable predictions</string>
+
+    <!-- Context: Language Settings menu strings -->
     <string name="model_label">Dictionary</string>
+
+    <!-- Context: Language Settings menu strings -->
     <string name="model_info_header" comment="Dictionary name">Dictionary: %1$s</string>
+
+    <!-- Context: Language Settings menu strings -->
     <string name="model_picker_header" comment="Dictionaries for a specified language">%1$s dictionaries</string>
+
+    <!-- Context: Language Settings menu strings -->
     <string name="manage_dictionary" comment="Placeholder for future feature" translatable="false">Manage dictionary</string>
+
+    <!-- Context: Language Settings menu strings -->
     <string name="model_install_toast" comment="Notification when a dictionary is installed">Dictionary installed</string>
+
+    <!-- Context: Language Settings menu strings -->
     <plurals name="keyboard_count">
       <item quantity="one">(%1$d keyboard)</item>
       <item quantity="other">(%1$d keyboards)</item>
     </plurals>
 
-    <!-- Content descriptions -->
+
+    <!-- Context: Content descriptions -->
     <string name="image_button" translatable="false">Image Button</string>
+
+    <!-- Context: Content descriptions -->
     <string name="image_view" translatable="false">Image View</string>
-    
-    <!-- Popup menu labels -->
+
+
+    <!-- Context: Popup menu labels -->
     <string name="label_delete" comment="Confirmation to delete an item">Delete</string>
-    
-    <!-- Shared preferences name -->
+
+
+    <!-- Context: Shared preferences name -->
     <string name="kma_prefs_name" translatable="false">KMAPreferences</string>
-    
-    <!-- Other strings -->
+
+    <!-- Context: Other strings -->
     <string name="help_bubble_text">Tap here to change keyboard</string>
 
 </resources>