[orca] Add translator notes; provide more detail for vague ones

[Joanmarie Diggs <joanied src gnome org>]

commit 2f1dd6be32e99f34758885f54895e3d562600001
Author: Joanmarie Diggs <jdiggs igalia com>
Date:   Tue May 15 19:53:53 2012 -0400

    Add translator notes; provide more detail for vague ones

 src/orca/chat.py                          |   28 ++++++++++++++++-
 src/orca/scripts/toolkits/Gecko/script.py |   46 ++++++++++++++++++++++++----
 2 files changed, 65 insertions(+), 9 deletions(-)
---
diff --git a/src/orca/chat.py b/src/orca/chat.py
index 8337038..baf9b10 100644
--- a/src/orca/chat.py
+++ b/src/orca/chat.py
@@ -332,24 +332,48 @@ class Chat:
         """Defines InputEventHandler fields for chat functions which
         will be used by the script associated with this chat instance."""
 
+        # Translators: In chat applcations, Orca automatically presents incoming
+        # messages in speech and braille. If a user is in multiple conversations
+        # or channels at the same time, it can be confusing to know what room or
+        # channel a given message came from just from hearing/reading it. For
+        # For this reason, Orca has an option to present the name of the room
+        # first ( "#a11y <joanie> hello!" instead of "<joanie> hello world!".
+        # This string to be translated is associated with the command to toggle
+        # room name presentation on or off.
+        # 
         self.inputEventHandlers["togglePrefixHandler"] = \
             input_event.InputEventHandler(
                 self.togglePrefix,
                 _("Toggle whether we prefix chat room messages with " \
                   "the name of the chat room."))
 
+        # Translators: In chat applications, it is often possible to see that
+        # a "buddy" is typing currently (e.g. via a keyboard icon or status
+        # text). Some users like to have this typing status announced by Orca;
+        # others find that announcment unpleasant. Therefore, it is a setting
+        # in Orca. This string to be translated is associated with the command
+        # to toggle typing status presentation on or off.
         self.inputEventHandlers["toggleBuddyTypingHandler"] = \
             input_event.InputEventHandler(
                 self.toggleBuddyTyping,
                 _("Toggle whether we announce when our buddies are typing."))
 
+        # Translators: Orca has a command to review previous chat room messages
+        # in speech and braille. Some users prefer to have this message history
+        # combined (e.g. the last ten messages which came in, no matter what
+        # room they came from). Other users prefer to have specific room history
+        # (e.g. the last ten messages from #a11y). Therefore, this is a setting
+        # in Orca. This string to be translated is associated with the command
+        # to toggle specific room history on or off.
         self.inputEventHandlers["toggleMessageHistoriesHandler"] = \
             input_event.InputEventHandler(
                 self.toggleMessageHistories,
                 _("Toggle whether we provide chat room specific message " \
                   "histories."))
 
-        # Add the chat room message history event handler.
+        # Translators: Orca has a command to review previous chat room messages
+        # in speech and braille. This string to be translated is associated
+        # with the keyboard commands used to review those previous messages.
         #
         self.inputEventHandlers["reviewMessage"] = \
             input_event.InputEventHandler(
@@ -408,7 +432,7 @@ class Chat:
         grid.set_border_width(12)
 
         # Translators: If this checkbox is checked, then Orca will speak
-        # the name of the chat room.
+        # the name of the chat room prior to presenting an incoming message.
         #
         label = _("_Speak Chat Room name")
         value = _settingsManager.getSetting('chatSpeakRoomName')
diff --git a/src/orca/scripts/toolkits/Gecko/script.py b/src/orca/scripts/toolkits/Gecko/script.py
index 7aca872..1c44e91 100644
--- a/src/orca/scripts/toolkits/Gecko/script.py
+++ b/src/orca/scripts/toolkits/Gecko/script.py
@@ -479,24 +479,55 @@ class Script(default.Script):
         self.inputEventHandlers["advanceLivePoliteness"] = \
             input_event.InputEventHandler(
                 Script.advanceLivePoliteness,
-                # Translators: this is for advancing the live regions
-                # politeness setting
+                # Translators: this string refers to an Orca command which
+                # advances the live region "politeness" setting from one
+                # level to the next.
+                #
+                # The term "live region" refers to dynamically updated
+                # content, typically on a web page, about which a user
+                # likely wants to be notified. For instance, a stock
+                # ticker on a financial site or a table of updated scores
+                # on a sports site. In contast, a countdown timer or clock
+                # on a web site is NOT a live region.
+                #
+                # The "politeness" level is an indication of when the user
+                # wishes to be notified about a change to live region content,
+                # e.g. never ("off"), when idle ("polite"), or when there is
+                # a change ("assertive").
                 #
                 _("Advance live region politeness setting."))
 
         self.inputEventHandlers["setLivePolitenessOff"] = \
             input_event.InputEventHandler(
                 Script.setLivePolitenessOff,
-                # Translators: this is for setting all live regions
-                # to 'off' politeness.
+                # Translators: this string refers to an Orca command which
+                # turns changes the live region "politness" level to "off."
+                #
+                # The term "live region" refers to dynamically updated
+                # content, typically on a web page, about which a user
+                # likely wants to be notified. For instance, a stock
+                # ticker on a financial site or a table of updated scores
+                # on a sports site. In contast, a countdown timer or clock
+                # on a web site is NOT a live region.
+                #
+                # The "politeness" level is an indication of when the user
+                # wishes to be notified about a change to live region content,
+                # e.g. never ("off"), when idle ("polite"), or when there is
+                # a change ("assertive").
                 #
                 _("Set default live region politeness level to off."))
 
         self.inputEventHandlers["monitorLiveRegions"] = \
             input_event.InputEventHandler(
                 Script.monitorLiveRegions,
-                # Translators: this is a toggle to monitor live regions
-                # or not.
+                # Translators: this string refers to an Orca command which
+                # allows the user to toggle whether or not Orca pays attention
+                # to changes in live regions. Note that turning off monitoring
+                # of live events is NOT the same as turning the politeness level
+                # to "off". The user can opt to have no notifications presented
+                # (politeness level of "off") and still manually review recent
+                # updates to live regions via Orca commands for doing so -- as
+                # long as the monitoring of live regions is enabled.
                 #
                 _("Monitor live regions."))
 
@@ -504,7 +535,8 @@ class Script(default.Script):
             input_event.InputEventHandler(
                 Script.reviewLiveAnnouncement,
                 # Translators: this is for reviewing up to nine stored
-                # previous live messages.
+                # previous live messages. Please see previous translator
+                # notes for more information on live regions.
                 #
                 _("Review live region announcement."))