From 2bb3141b12fae4f7b79213d6e871f1b7b0b18f3a Mon Sep 17 00:00:00 2001
From: LisoUseInAIKyrios <118716522+LisoUseInAIKyrios@users.noreply.github.com>
Date: Fri, 5 Apr 2024 01:14:19 +0400
Subject: [PATCH] chore: Add comments for translations

---
 .../resources/addresources/values/strings.xml | 102 +++++++++++-------
 1 file changed, 64 insertions(+), 38 deletions(-)

diff --git a/src/main/resources/addresources/values/strings.xml b/src/main/resources/addresources/values/strings.xml
index 53571b78..a96bf59e 100644
--- a/src/main/resources/addresources/values/strings.xml
+++ b/src/main/resources/addresources/values/strings.xml
@@ -1,3 +1,31 @@
+<!--
+
+# General guidelines and information for translating
+
+## Strings parameters can be reordered to allow more flexible translations if the grammar should be changed.
+
+    For example, the patches string:
+        <string name="revanced_patches_string">You will arrive at %1$s in %2$s hours from now</string>
+    Could be translated to another language using a rearranged grammar:
+        <string name="revanced_patches_string">You will arrive %2$s hours from now at %1$s</string>
+
+     For Manager strings:
+        You will arrive at ${destination} in ${count} hours from now
+     Could be rearranged by changing the order of the ${} parameters:
+        You will arrive ${count} hours from now at ${destination}
+
+    Reordering is particularly relevant when translating into right to left languages, or for any language with grammar that is noticeably different from English.
+
+## Single and double quotation marks must be escaped for patch strings (Manager does not require escaping any quotes).
+
+    All _patches_ single and double quotation marks must be escaped as \"  or \'
+    Forgetting to do this will cause that string to appear in app with no quotation characters.
+
+    Correct:
+        <string name="revanced_string">You\'re correct. This is the \"correct\" way and this text will as expected in the app</string>
+    Not correct:
+        <string name="revanced_string">You're not correct. This is not the "correct" way and this text will not appear as expected the in app</string>
+-->
 <resources>
     <app id="shared">
         <patch id="misc.settings.BaseSettingsResourcePatch">
@@ -197,8 +225,7 @@
             <string name="revanced_hide_keyword_content_search_summary_on">Search results are filtered by keywords</string>
             <string name="revanced_hide_keyword_content_search_summary_off">Search results are not filtered by keywords</string>
             <string name="revanced_hide_keyword_content_phrases_title">Keywords to hide</string>
-            <!-- For localization it is preferred, but not required, if 'LeBlanc' is replaced with a localized name 
-                 or familiar product name that has upper case letters in the middle of the word.
+            <!-- For localization it is preferred, but not required, if 'LeBlanc' is replaced with a localized name or a familiar word that has upper case letters in the middle of the word.
                  This is because keywords can be in any language, and showing an example in the localized script helps convey this. -->
             <string name="revanced_hide_keyword_content_phrases_summary">Keywords and phrases to hide, separated by new lines\n\nWords with uppercase letters in the middle must be entered with the casing (ie: iPhone, TikTok, LeBlanc)</string>
             <string name="revanced_hide_keyword_content_about_title">About keyword filtering</string>
@@ -352,8 +379,7 @@
             <string name="revanced_hide_playlist_button_summary_on">Save to playlist button is hidden</string>
             <string name="revanced_hide_playlist_button_summary_off">Save to playlist button is shown</string>
             <!-- 'Shop' should be translated with the same localized wording that YouTube displays.
-                 Shop button appears only for some videos in certain regions.
-                 Translate the button name normally if this menu is never shown. -->
+                 Shop button appears only for some videos in certain regions. Translate the button name normally if this menu is never shown. -->
             <string name="revanced_hide_shop_button_title">Hide Shop</string>
             <string name="revanced_hide_shop_button_summary_on">Shop button is hidden</string>
             <string name="revanced_hide_shop_button_summary_off">Shop button is shown</string>
@@ -364,8 +390,7 @@
             <string name="revanced_hide_autoplay_button_summary_off">Autoplay button is shown</string>
         </patch>
         <patch id="layout.buttons.captions.HideCaptionsButtonPatch">
-            <!-- This button does not display any text, but 'captions' should be translated using
-                 the same wording used as the translation of 'revanced_hide_player_flyout_captions_title' -->
+            <!-- This button does not display any text, but 'captions' should be translated using the same wording used as the translation of 'revanced_hide_player_flyout_captions_title' -->
             <string name="revanced_hide_captions_button_title">Hide captions button</string>
             <string name="revanced_hide_captions_button_summary_on">Captions button is hidden</string>
             <string name="revanced_hide_captions_button_summary_off">Captions button is shown</string>
@@ -614,20 +639,18 @@
         <patch id="layout.returnyoutubedislike.ReturnYouTubeDislikeResourcePatch">
             <string name="revanced_ryd_settings_title">Return YouTube Dislike</string>
             <string name="revanced_ryd_video_likes_hidden_by_video_owner">Hidden</string>
-            <!-- Toast shown if network connection times out. Translations of this should not be longer
-                 than the original English or the text can be clipped and not entirely shown. -->
+            <!-- Toast shown if network connection times out. Translations of this should not be longer than the original English or the text can be clipped and not entirely shown. -->
             <string name="revanced_ryd_failure_connection_timeout">Dislikes temporarily not available (API timed out)</string>
             <string name="revanced_ryd_failure_connection_status_code">Dislikes not available (status %d)</string>
             <string name="revanced_ryd_failure_client_rate_limit_requested">Dislikes not available (client API limit reached)</string>
             <string name="revanced_ryd_failure_generic">Dislikes not available (%s)</string>
             <!-- Toast shown if the user enables RYD while a video is opened, and then tries to vote for the video. -->
-            <string name="revanced_ryd_failure_ryd_enabled_while_playing_video_then_user_voted">Reload video to vote using ReturnYouTubeDislike</string>
+            <string name="revanced_ryd_failure_ryd_enabled_while_playing_video_then_user_voted">Reload video to vote using Return YouTube Dislike</string>
             <string name="revanced_ryd_enable_title">Return YouTube Dislike</string>
             <string name="revanced_ryd_enable_summary_on">Dislikes are shown</string>
             <string name="revanced_ryd_enable_summary_off">Dislikes are not shown</string>
             <string name="revanced_ryd_shorts_title">Show dislikes on Shorts</string>
-            <!-- %s is either an empty blank string, or it is 'revanced_ryd_shorts_summary_disclaimer'.
-                 This text should read normally in both situations. -->
+            <!-- %s is either an empty blank string, or it is 'revanced_ryd_shorts_summary_disclaimer'. This text should read normally in both situations. -->
             <string name="revanced_ryd_shorts_summary_on">Dislikes shown on Shorts %s</string>
             <string name="revanced_ryd_shorts_summary_off">Dislikes hidden on Shorts</string>
             <!-- Shown only when used with 'revanced_ryd_shorts_summary_on' and it is never displayed alone. -->
@@ -726,8 +749,7 @@
             <string name="revanced_sb_api_url_changed">API URL changed</string>
             <string name="revanced_sb_settings_ie">Import/Export settings</string>
             <string name="revanced_sb_settings_copy">Copy</string>
-            <!-- %s is either an empty blank string, or it is 'revanced_sb_settings_ie_sum_warning'.
-                 This text should read normally in both situations. -->
+            <!-- %s is either an empty blank string, or it is 'revanced_sb_settings_ie_sum_warning'. This text should read normally in both situations. -->
             <string name="revanced_sb_settings_ie_sum">Your SponsorBlock JSON configuration that can be imported/exported to ReVanced and other SponsorBlock platforms %s</string>
             <!-- Shown only when used with 'revanced_sb_settings_ie_sum' and it is never displayed alone. -->
             <string name="revanced_sb_settings_ie_sum_warning">This includes your private user id. Be sure to share this wisely</string>
@@ -798,8 +820,7 @@
             <string name="revanced_sb_submit_failed_forbidden">Can\'t submit the segment: %s</string>
             <string name="revanced_sb_submit_failed_duplicate">Can\'t submit the segment.\nAlready exists</string>
             <string name="revanced_sb_submit_succeeded">Segment submitted successfully</string>
-            <!-- Toast shown if network connection times out. Translations of this should not be longer
-                 than the original English or the text can be clipped and not entirely shown. -->
+            <!-- Toast shown if network connection times out. Translations of this should not be longer than the original English or the text can be clipped and not entirely shown. -->
             <string name="revanced_sb_sponsorblock_connection_failure_timeout">SponsorBlock temporarily not available (API timed out)</string>
             <string name="revanced_sb_sponsorblock_connection_failure_status">SponsorBlock temporarily not available (status %d)</string>
             <string name="revanced_sb_sponsorblock_connection_failure_generic">SponsorBlock temporarily not available</string>
@@ -813,6 +834,8 @@
             <string name="revanced_sb_new_segment_choose_category">Choose the segment category</string>
             <string name="revanced_sb_new_segment_disabled_category">Category is disabled in settings. Enable category to submit.</string>
             <string name="revanced_sb_new_segment_title">New SponsorBlock segment</string>
+            <!-- Do not rearrange the (hour):(minute):second) time format operators here.
+                 YT shows the same seekbar time format for all languages, and this string is confirming the segment time as it appears in the seekbar. -->
             <string name="revanced_sb_new_segment_mark_time_as_question">Set %1$02d:%2$02d:%3$03d as the start or end of a new segment?</string>
             <string name="revanced_sb_new_segment_mark_start">start</string>
             <string name="revanced_sb_new_segment_mark_end">end</string>
@@ -820,6 +843,8 @@
             <string name="revanced_sb_new_segment_time_start">Time the segment begins at</string>
             <string name="revanced_sb_new_segment_time_end">Time the segment ends at</string>
             <string name="revanced_sb_new_segment_confirm_title">Are the times correct?</string>
+            <!-- Do not rearrange the (hour):(minute):second) time format operators here.
+                 YT shows the same seekbar time format for all languages, and this string is confirming the segment time as it appears in the seekbar. -->
             <string name="revanced_sb_new_segment_confirm_content">The segment lasts from %1$02d:%2$02d to %3$02d:%4$02d (%5$d minutes %6$02d seconds)\nIs it ready to submit?</string>
             <string name="revanced_sb_new_segment_start_is_before_end">Start must be before the end</string>
             <string name="revanced_sb_new_segment_mark_locations_first">Mark two locations on the time bar first</string>
@@ -948,6 +973,7 @@
             <string name="revanced_alt_thumbnail_stills_time_entry_1">Beginning of video</string>
             <string name="revanced_alt_thumbnail_stills_time_entry_2">Middle of video</string>
             <string name="revanced_alt_thumbnail_stills_time_entry_3">End of video</string>
+            <!-- Translations of this should not be longer than the original English text, otherwise the text can be clipped and not entirely shown. -->
             <string name="revanced_alt_thumbnail_dearrow_error">DeArrow temporarily not available (status code: %s)</string>
             <string name="revanced_alt_thumbnail_dearrow_error_generic">DeArrow temporarily not available</string>
         </patch>
@@ -969,23 +995,6 @@
             <string name="revanced_spoof_device_dimensions_summary_on">Device dimensions spoofed</string>
             <string name="revanced_spoof_device_dimensions_summary_off">Device dimensions not spoofed\n\nSpoofing the device dimensions can unlock higher video qualities but unknown side effects may occur</string>
         </patch>
-        <!-- This patch is no longer used, these strings are not in use, and these strings will be deleted in the future. -->
-        <patch id="misc.fix.playback.SpoofSignaturePatch">
-            <string name="revanced_spoof_signature_verification_screen_title">Spoof app signature</string>
-            <string name="revanced_spoof_signature_verification_screen_summary">Spoof the app signature to prevent playback issues</string>
-            <string name="revanced_spoof_signature_verification_enabled_title">Spoof app signature</string>
-            <string name="revanced_spoof_signature_verification_enabled_summary_on">App signature spoofed\n\nSide effects include:\n• Enhanced bitrate is not available\n• Videos cannot be downloaded\n• No seekbar thumbnails for paid videos</string>
-            <string name="revanced_spoof_signature_verification_enabled_summary_off">App signature not spoofed\n\nVideo playback may not work</string>
-            <string name="revanced_spoof_signature_verification_enabled_user_dialog_message">Turning off this setting will cause video playback issues.</string>
-            <string name="revanced_spoof_signature_in_feed_enabled_title">Spoof app signature in feed</string>
-            <string name="revanced_spoof_signature_in_feed_enabled_summary_on">App signature spoofed\n\nSide effects include:\n• Feed videos are missing subtitles\n• Automatically played feed videos will show up in your watch history</string>
-            <string name="revanced_spoof_signature_in_feed_enabled_summary_off">App signature not spoofed for feed videos\n\nFeed videos will play for less than 1 minute before encountering playback issues</string>
-            <string name="revanced_spoof_storyboard_title">Spoof storyboard</string>
-            <string name="revanced_spoof_storyboard_summary_on">Storyboard spoofed</string>
-            <string name="revanced_spoof_storyboard_summary_off">Storyboard not spoofed\n\nSide effects include:\n• No ambient mode\n• Seekbar thumbnails are hidden</string>
-            <string name="revanced_spoof_storyboard_timeout">Spoof storyboard temporarily not available (API timed out)</string>
-            <string name="revanced_spoof_storyboard_io_exception">Spoof storyboard temporarily not available: %s</string>
-        </patch>
         <patch id="misc.gms.GmsCoreSupportResourcePatch">
             <string name="microg_settings_title">GmsCore Settings</string>
             <string name="microg_settings_summary">Settings for GmsCore</string>
@@ -1014,12 +1023,6 @@
             <string name="revanced_disable_zoom_haptics_summary_on">Haptics are disabled</string>
             <string name="revanced_disable_zoom_haptics_summary_off">Haptics are enabled</string>
         </patch>
-        <!-- This patch is no longer used and these strings will soon be deleted. -->
-        <patch id="video.hdrbrightness.HDRBrightnessPatch">
-            <string name="revanced_hdr_auto_brightness_title">Enable auto HDR brightness</string>
-            <string name="revanced_hdr_auto_brightness_summary_on">Auto HDR brightness is enabled</string>
-            <string name="revanced_hdr_auto_brightness_summary_off">Auto HDR brightness is disabled</string>
-        </patch>
         <patch id="video.quality.RememberVideoQualityPatch">
             <string name="revanced_video_quality_default_entry_1">Automatic quality</string>
             <string name="revanced_video_quality_default_entry_2">2160p</string>
@@ -1062,6 +1065,29 @@
             <string name="revanced_slide_to_seek_summary_on">Slide to seek is enabled</string>
             <string name="revanced_slide_to_seek_summary_off">Slide to seek is not enabled</string>
         </patch>
+        <!-- This patch is no longer used, these strings are not in use, and these strings will be deleted in the future. -->
+        <patch id="misc.fix.playback.SpoofSignaturePatch">
+            <string name="revanced_spoof_signature_verification_screen_title">Spoof app signature</string>
+            <string name="revanced_spoof_signature_verification_screen_summary">Spoof the app signature to prevent playback issues</string>
+            <string name="revanced_spoof_signature_verification_enabled_title">Spoof app signature</string>
+            <string name="revanced_spoof_signature_verification_enabled_summary_on">App signature spoofed\n\nSide effects include:\n• Enhanced bitrate is not available\n• Videos cannot be downloaded\n• No seekbar thumbnails for paid videos</string>
+            <string name="revanced_spoof_signature_verification_enabled_summary_off">App signature not spoofed\n\nVideo playback may not work</string>
+            <string name="revanced_spoof_signature_verification_enabled_user_dialog_message">Turning off this setting will cause video playback issues.</string>
+            <string name="revanced_spoof_signature_in_feed_enabled_title">Spoof app signature in feed</string>
+            <string name="revanced_spoof_signature_in_feed_enabled_summary_on">App signature spoofed\n\nSide effects include:\n• Feed videos are missing subtitles\n• Automatically played feed videos will show up in your watch history</string>
+            <string name="revanced_spoof_signature_in_feed_enabled_summary_off">App signature not spoofed for feed videos\n\nFeed videos will play for less than 1 minute before encountering playback issues</string>
+            <string name="revanced_spoof_storyboard_title">Spoof storyboard</string>
+            <string name="revanced_spoof_storyboard_summary_on">Storyboard spoofed</string>
+            <string name="revanced_spoof_storyboard_summary_off">Storyboard not spoofed\n\nSide effects include:\n• No ambient mode\n• Seekbar thumbnails are hidden</string>
+            <string name="revanced_spoof_storyboard_timeout">Spoof storyboard temporarily not available (API timed out)</string>
+            <string name="revanced_spoof_storyboard_io_exception">Spoof storyboard temporarily not available: %s</string>
+        </patch>
+        <!-- This patch is no longer used and these strings will soon be deleted. -->
+        <patch id="video.hdrbrightness.HDRBrightnessPatch">
+            <string name="revanced_hdr_auto_brightness_title">Enable auto HDR brightness</string>
+            <string name="revanced_hdr_auto_brightness_summary_on">Auto HDR brightness is enabled</string>
+            <string name="revanced_hdr_auto_brightness_summary_off">Auto HDR brightness is disabled</string>
+        </patch>
     </app>
     <app id="twitch">
         <patch id="ad.audio.AudioAdsPatch">