pygettext: extract translators comments

[htrd]

BPO	1288056
Nosy	@warsaw, @merwok
Files	pygettext.diff: pygettext patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2005-09-11.22:05:19.000>
labels = ['type-feature']
title = 'pygettext: extract translators comments'
updated_at = <Date 2019-03-15.23:55:11.034>
user = 'https://bugs.python.org/htrd'

bugs.python.org fields:

activity = <Date 2019-03-15.23:55:11.034>
actor = 'BreamoreBoy'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Demos and Tools']
creation = <Date 2005-09-11.22:05:19.000>
creator = 'htrd'
dependencies = []
files = ['6779']
hgrepos = []
issue_num = 1288056
keywords = ['patch']
message_count = 4.0
messages = ['48728', '107562', '108903', '221642']
nosy_count = 3.0
nosy_names = ['barry', 'htrd', 'eric.araujo']
pr_nums = []
priority = 'low'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue1288056'
versions = ['Python 3.4', 'Python 3.5']

[htrd]

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.

[merwok]

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

[merwok]

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\>)

[BreamoreBoy]

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?