message string coding style

[Neil Williams]

On Friday 24 March 2006 9:15 am, Christian Stimming wrote:
> However, your coding style concerning the message strings caught my eye.
> I already told hampton on IRC what the translators think about that, and
> I thought I should point out on the mailing list the implications for
> the translators, just for future reference. Your code looks like this:
>
> +static gboolean
> +remove_old_report(gpointer key, gpointer val, gpointer data)
> +{
> +    /* ... */
> +    gchar *msg, *str = _("Do you want to display '%s'?");
> +    gint response;

If the preferred method advised by Christian cannot be used, Chris, you can 
use a comment immediately above the gettext call which will be retained into 
the POT file:

+    /* Translators: the string is the name of a report */
+    gchar *msg, *str = _("Do you want to display '%s'?");
+    gint response;

(or whatever it actually is.)

This then gets into the pot file as:
#. Translators: Name of the account where all the missing accounts
#. are put into. (FIXME: is this correct?)
#: ../src/backend/file/io-gncbin-r.c:507
msgid "Lost Accounts"
msgstr ""

(Note that some unnecessary comments have made their way into the POT file for 
this reason - they are too close to a gettext call. If your comment is 
expressly to assist translators, it's worth making that obvious in the 
comment, as above.)

IIRC, // comment syntax is not picked up.

BTW a common annoyance, this example should actually be:
"Name of the account into which all the missing accounts can be placed."
(s/can/will/ if you like.)

*Avoid split-infinitives* (ending a sentence with "into", "for", "to" etc.) 
Use "which" and "whom" instead.

Split-infinitives, colour, favourite and -ise instead of -ize are the main 
reasons for an en_GB translation.
;-)

(two nations separated by a common language)

> Let me explain what this means to translators. Translators will see the
> string "Do you want to display '%s'?" in the gnucash.pot file. Then,
> they will wonder what this mysterious "%s" might be -- is it a verb, is
> it a number, is it the name of a picture, is it the name of whatever? 

If you use a comment, it needs to unambiguously answer these questions. You 
should describe the string that will replace the %s as fully as possible. 
Multiple lines are fine within the same comment.

Grammatical differences may, for example, require that the %s is moved within 
the translated string to the middle or even beginning depending on whether it 
is a verb, noun or other construct. This can only be done if the msgid and/or 
comment make sense and are unambiguous.

> The translator is forced to read through the whole function, 

Worse, try to correlate the string with the value passed by a function in 
another file if this is a public API string.

> looking for the place where this obnoxious "str" variable is used
> eventually. From a translator point of view this sucks. Royally. Please
> do *not* use this coding style.

(without comments)

-- 

Neil Williams
=============
http://www.data-freedom.org/
http://www.nosoftwarepatents.com/
http://www.linux.codehelp.co.uk/

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 191 bytes
Desc: not available
Url : http://lists.gnucash.org/pipermail/gnucash-devel/attachments/20060324/b9054481/attachment.bin