If I recall correctly, we were told not to do this by the gnome-i18n team.  See http://svn.gnome.org/viewvc/orca?view=revision&revision=2298 and http://bugzilla.gnome.org/show_bug.cgi?id=412200#c48.  I'm trying to find the e-mail archive from the gnome-i18n team, but I cannot seem to find it right now.

I had a chat with danilo in #i18n.  The conclusion is that usage text should be marked for translation, but the command line options should not.  So, we might end up with something like:

    # Translators: blah blah blah
    #
    print "-t, --text-setup             " + _("Set up user preferences (text version")
    # Translators: blah blah blah
    #
    print "-n, --no-setup               " + _("Skip set up of user preferences")

I'm not sure what to do about the -e and -d options, but perhaps something like the following (this is for just the enable section):

...top of file...

from orca_i18n import Q_        # to provide qualified translatable strings

...usage() method...

    print "-e, --enable=[" \
        + Q_("option|speech") + "|" \
        + Q_("option|braille") + "|" \
        + Q_("option|braille-monitor") + "|" \
        + Q_("option|magnifier") + "|" \
        + Q_("option|main-window") + "] ",
    print _("Force use of option")

...main() method...

                # Translators: blah blah blah.
                #
                # ONLY TRANSLATE THE PART AFTER THE PIPE CHARACTER |
                #
                if feature == Q_("option|speech"):
                    _commandLineSettings["enableSpeech"] = True
                # Translators: blah blah blah.
                #
                # ONLY TRANSLATE THE PART AFTER THE PIPE CHARACTER |
                #
                elif feature == Q_("option|braille"):
                    _commandLineSettings["enableBraille"] = True
                # Translators: blah blah blah.
                #
                # ONLY TRANSLATE THE PART AFTER THE PIPE CHARACTER |
                #
                elif feature == Q_("option|braille-monitor"):
                    _commandLineSettings["enableBrailleMonitor"] = True
                # Translators: blah blah blah.
                #
                # ONLY TRANSLATE THE PART AFTER THE PIPE CHARACTER |
                #
                elif feature == Q_("option|magnifier"):
                    _commandLineSettings["enableMagnifier"] = True
                # Translators: blah blah blah.
                #
                # ONLY TRANSLATE THE PART AFTER THE PIPE CHARACTER |
                #
                elif feature == Q_("option|main-window"):
                    _commandLineSettings["showMainWindow"] = True

Created attachment 98341 [details] [review]
Patch to hopefully fix the problem.

Seems to work nicely. Could others please test too.

Just did a quick look at the code -- have not tested it yet -- looks good with the exception of a couple things:

+                # Translators: this option will enable speech output in Orca.
+                #
+                # ONLY TRANSLATE THE PART AFTER THE PIPE CHARACTER |
+                #
+                if feature == Q_("option|speech"):

...

+
+                # Translators: this option will disable speech output in Orca.
+                #
+                # ONLY TRANSLATE THE PART AFTER THE PIPE CHARACTER |
+                #
+                if feature == Q_("option|speech"):

Since the comments are for the same string to be translated, they will end up in the orca.pot file as something like:

# Translators: this option will enable speech output in Orca.
#
# ONLY TRANSLATE THE PART AFTER THE PIPE CHARACTER |
# Translators: this option will disable speech output in Orca.
#
# ONLY TRANSLATE THE PART AFTER THE PIPE CHARACTER |

So, maybe just keeping the comments more generic might be better, and you probably only need to include them once in the file:

# Translators: this option is for enabling speech synthesis output.
#
# ONLY TRANSLATE THE PART AFTER THE PIPE CHARACTER |

# Translators: this option is for enabling braille output on a physical
# refreshable braille display.
#
# ONLY TRANSLATE THE PART AFTER THE PIPE CHARACTER |

# Translators: this option is for enabling a GUI to monitor what is
# being sent to the physical braille display.
#
# ONLY TRANSLATE THE PART AFTER THE PIPE CHARACTER |

# Translators: this option is for enabling magnifier use.
#
# ONLY TRANSLATE THE PART AFTER THE PIPE CHARACTER |


My only other comment is this:

+    print _("If Orca has not been previously set up by the user, Orca")
+    print _("will automatically launch the preferences set up unless ")
+    print _("the -n or --no-setup option is used.")

I'm not sure how translators handle text split across multiple lines.  I think asking the gnome-i18n folks about this would be a good thing.

Thanks!

Created attachment 98342 [details] [review]
Revision #2

This hopefully deals with concern #1. As for concern #2: there 
was nobody in the IRC #gnome-i18n channel (or I'm doing it wrong), 
so I'll try again tomorrow.

Created attachment 98348 [details] [review]
Revision #3

IRC chat room is #i18n. Just chatted with andre. He pointed me at:
http://developer.gnome.org/doc/tutorials/gnome-i18n/developer.html#split-sentences

I've adjusted this to one looong line. It's > 80 characters.
How should it be rewritten to fix that?

> IRC chat room is #i18n. Just chatted with andre.

Yeah Andre!

> I've adjusted this to one looong line. It's > 80 characters.
> How should it be rewritten to fix that?

I think embedding the \n is fine, though the note to translators should probably indicate this is text being sent to a terminal and we want to keep the text lines within terminal boundaries (maybe all the usage text should say that?).

I think one thing you can do to bring the code inside the 80 character boundary is something like this:

   print _("If Orca has not been previously set up by the user, Orca\n" \
           "will automatically launch the preferences set up unless\n" \
           "the -n or --no-setup option is used.")

The syntax above just automatically concatenates the strings together.  I believe intltool will treat it like one big string so it shows up in the pot file.  To check this, cd to Orca's po directory and run "intltool-update -po".  This will create an orca.pot file which you can search for the given string.

Created attachment 98391 [details] [review]
Revision #4

I realize this is going to be frustrating, and I apologize.  Our comments to translators, however, are a different kind of beast than the other comments in our code.  The 'normal' comments in our code are for team members, and we can afford to take some liberties with the comments.  

The comments for translators, however, are for a much larger audience, perhaps many of whom use English as a second language.  In addition, the comments are lifted from the code and placed into a *.po file.  As a result, the translators, who are also often not programmers, do not have the same context as we do when looking at the comments.  There only context is the string and the comments.  So, we need to approach the comments to translators from this point of view.  

BTW, we received a number of compliments from the GNOME translation team regarding the care we've taken in being clear in how we describe the strings marked for translation.  This positive feedback from them is my motivation for this reply -- I want us to maintain the same level of i18n discipline. IMO, the quality of the comments can directly impact the quality of the translation.

To get a flavor of what a translator sees, you can run the following command in the po directory (as also mentioned in comment #8): "intltool-update -po".  This will quickly create an orca.pot file which is pretty much the translator's view into our project.

The following comments are based upon looking at the orca.pot file.  Lines preceded with a ">" are things I've pulled directly from the file.

>#. Translators: this is the Orca command line option that will display
>#. all this usage information.
>#.
>#: ../src/orca/orca.py:1185
>msgid "Show this help message"
>msgstr ""

For all the options, I wonder if the general flavor of the comments for translators might be more helpful if they were something like "this is the description of the command line option '-?, --help' that is used to display usage information."  That is, the actual command line option is given and it is noted that this is descriptive text for that option.  That way, maybe the translators could choose wordings similar to the command line option if the word for the command line option was close to something in their locale. 

If you think the current comments for the translators are clear enough, though, feel free to leave them as they are.  I don't think they are, but I might be trying to be too helpful.

>#. Translators: by default, Orca excepts to find its user preferences
>#. in a directory called .orca under the user's home directory. This
>#. Orca command line option allows you sto specify an alternation
>#. location for those user preferences.

Minor spelling: "excepts" vs. "expects", "sto" vs. "to" and "alternation" vs. "alternate".

>msgid "Force use of option"
>msgid "Prevent use of option"

I think some sort of translator comment might help here as well. Perhaps something that just says what the command line argument is and what the options are. Again, maybe I'm trying to be too helpful.  Remember, however, that the translator has very little context or understanding of what the string is for.

>msgid ""
>"\n"
>"If Orca has not been previously set up by the user, Orca\n"
>"will automatically launch the preferences set up unless\n"
>"the -n or --no-setup option is used."

The concatenation from comment #8 seemed to work well.  Good!  The only odd thing is the very first "\n" (not all of them, just the first one).  Based upon past experiences with translators, they may get a little miffed about that, or at least just fire off an e-mail asking us what it is all about.  To prevent that, we probably could just handle this by a single "print" on its own line as is currently done in the code.

Thanks!

D'Oh!

> as we do when looking at the comments.  There only context is the string and

"Their" only context.  Sorry about that.

Created attachment 98415 [details] [review]
Revision #5

(In reply to comment #12)
> Created an attachment (id=98415) [edit]
> Revision #5
> 

Looks great!  Tested and also analyzed the orca.pot file. Thanks for bearing with me on this.

Feel free to close!  Thanks for bearing with me on this one.

Uh oh!  It turns out that marking the enable/disable items for translation breaks accessible login.  The reason for this is that accessible login contains raw untranslatable commands for starting orca, and these commands include options such as "-d main-window" (disable the main window).

By marking the options for translation, we are at high risk for not getting a match for locales other than en_US.  For example, 'magnification' becomes 'loupe' for fr_FR.  So, to enable magnification for the fr_FR locale, you need to run "orca -e loupe".  This, of course, will not work with a fr_FR login screen when gdm attempts to run orca with "orca -e magnifier".

To fix this, we need to not mark the command line options for translation.  Reopening.  This needs to be fixed for both GNOME 2.22 and GNOME 2.24.  Rich, I'll take this one if it brings back bad memories for you.  :-)

Created attachment 112633 [details] [review]
Do not mark command line options for translation

Patch committed to trunk and gnome-2-22 branch.  Closing as FIXED.