[MeeGo-il10n] Translator comments in QML-based files

[margie_foster]

How developers of qml-based apps should be using comments for qsTr() /
tr().

Here is the format of translator-visible comments around a translation
in QML code:

//: extracomment

qsTr("Translatable string", "comment");

The exact same syntax, but with tr(), works in C++ Code.

NOW... the critical thing is the meaning of "comment" vs.
"extracomment". Comment would be better termed "translation context".

This string is actually used to distinguish one copy of your string from
another. If you use two different "comment" strings for two different
copies of the same translatable string, the string will appear in the TS
file TWICE and need to be translated TWICE!

Extracomment, on the other hand, is purely for the benefit of the
translator. Here you can be more long-winded and offer info that can
help in the translation.

I have verified that at least in QML code, you can have multiple lines
of //: and the lines can be quite long (I tried 200 characters) -- they
all get concatenated and placed in an <extracomment> tag in the .ts
file.

So... make sure you understand the distinction. Use "comment" only when
the same string needs to be translated in two different ways. 

As a first example, consider the common case where your strings are
unique and only used in one sense. Then you should use only
extracomment, not comment:

//: Title of photo application

property string labelBook: qsTr("Photos")

noContent: qsTr("There are no photos in this album.")


//: %1 is album name, %2 is photo name, used to refer to photo being
deleted
message: qsTr("%1: %2")

(Here I'm presuming the first and last one need explanation, the second
is self-explanatory.)

As another example, consider a location-based stock trading app where
you can get trading advice from your friends:

//: Context menu item to close dialog
addItem(qsTr("Close", "Verb"))

//: Label for price at end of trading day
label: qsTr("Close", "Noun")

//: Friend is nearby on the map
popupText: qsTr("Close", "Adjective - physical")

//: Description of depth of friendship
friend.creepyRelationshipMonitor = qsTr("Close", "Adjective -
emotional")

//: Tooltip on close X button
tooltip: qsTr("Close", "Verb")

The "comments" used are terse; they are mainly used to distinguish
usages programmatically. The extracomment is still used for the main
source of detail for translation. Note this code will generate FOUR
copies of "Close" in the .ts file... the first and last, with identical
"context comment", will use the same translation.

In short, "extra comments" should be used for every string that requires
an explanation; "comments" should only be used when identical strings
with different meanings are used in the same context, so that separate
strings will be added to the TS file.
 

One final note: Right this moment, Transifex doesn't actually support
the "comment" field correctly... instead, it always shows just one copy
of the string for translation. But this should be fixed in the next
couple weeks, so if you use the comment and extracomment field
correctly, translators will have the right amount of control after the
string freeze.