The .po file format supports "automatic comments". These are    
comments which have been automatically generated or extracted    
from the original source along with the "msgid" reference strings.    
    
Automatic comments are a good way to communicate extra   
information to the translator. For example message context, or  
information about string substitutions.  
  
The Gnu gettext tools have good support for "automatic  
comments". For example msgmerge (which merges updates  
from a programmer into the master po file maintained by a  
translator) will preserve the programmer's copy of the "automatic  
comments" but the translator's copy of the other comments.  
    
This patch includes an option to pygettext which automatically    
copies comments from Python source code into its output .po    
file. The comment must appear on the same line as the    
extracted string, and the first character of the comment    
(immediately after the #) must be a period.    
    
Example usage:    
    
msg = _('Opening file....') #. status bar message    
msg = _("Connected on %1") #. eg. connected on com1    
    
Rationale:    
    
Why not use any python source code comment on the same   
line, rather than require the #. prefix? My first variant of this patch   
worked that way. I found this inadvertently included too many   
programmer-oriented comments that were inappropriate for the    
translator.    
    
Why the #. notation? This is the same format as used in .po    
files. Thats not a big advantage, because nobody spends much 
time reading raw po files. It is concise, which is an advantage 
since the comment needs to be on the same line as the 
extracted string.    
    
Why should the python source code notation use python    
comments, rather than an extra parameter to the _    
function? Partly tradition.... Gnu gettext for C also looks in    
specially marked comments. It is also nice to not require    
changes to other translateable string extraction tools (if there are    
any) or existing translation functions which currently do not   
expect an extra parameter.   
    
Why a new command line option? Hmmmm - no good reason.....   
maybe this functionality should always be enabled.   
    
Why require the comment to be on the same line? Gnu gettext   
for C searches the same line *and* the preceeding line. I have   
experience converting a large python project of approx 800   
extracted strings where this hasnt been a problem. Im happy to   
extend this if necessary.   
   
   
   
    
    

Translator comments seem to me nicer than contexts (http://bugs.python.org/issue2504), but I’m not sure which one is recommended when they overlap.

I’m -1 on the same line restriction. Python style is to put comments on the previous line.

The 2.x line does not accept new features, so your patch needs to be ported to 3.x (branch name py3k).

FWIW, Babel uses a different style of comments, on the preceding line: http://babel.edgewall.org/wiki/Documentation/messages.html#translator-comments

It appears that I had mistaken comments in the source and comments in the pot/po files:

     /* TRANSLATORS: The placeholder indicates etc. */
     printf (_("Something.\n"));

These will be extracted by ‘xgettext’, leading to a .pot file that contains this:

     #. TRANSLATORS: The placeholder indicates etc.
     #: src/hello.c:178
     #, c-format
     msgid "Report bugs to <%s>.\n"
     msgstr ""


(From <http://www.gnu.org/software/gettext/manual/gettext.html>)

Is there anything of value in the patch which can be used, as I can't comment on it from a technical viewpoint?  Otherwise can we close this as "out of date" or "won't fix" as appropriate?