(Add :column subcue to @title.) |
m (No such thing as @info:message.) |
||
Line 306: | Line 306: | ||
<code cpp> | <code cpp> | ||
− | i18nc("@info | + | i18nc("@info/plain", |
"<filename>%1</filename> does not exist", fname); | "<filename>%1</filename> does not exist", fname); | ||
</code> | </code> |
This section needs improvements: Please help us to
cleanup confusing sections and fix sections which contain a todo This article is describing a system currently in RFC phase, pending design modifications. Skip it unless you would like to make comments and proposals yourself. |
Typical way of formatting user visible strings in application interfaces, for a long time has been that of plain text or at most visual markup like HTML tags. In most textual content environments, shift to semantic markup has been recognized as superior to visual (for example, the Docbook XML for documentation). Why not go down the same road for UI strings?
In the semantic model, text elements are marked for their meaning, rather than for their visual appearance. Consider a few i18n examples of visual formatting:
i18n("Move");
i18n("Descending");
i18n("<qt>%1 does not exist</qt>", fname);
i18n("
Using KDE UI text semantic markup (KUIT for short), these strings would be formated like this:
i18nc("@action:button", "Move");
i18nc("@item:inmenu", "Descending");
i18nc("@info", "<filename>%1</filename> does not exist", fname);
i18nc("@info:whatsthis",
"<title>History Sidebar</title>" "<para>You can configure the history sidebar here.</para>");
Two distinct differences between visual and KUIT markup can be observed.
The first is the use of context i18n calls, the i18nc(), to convey the broad usage context of a string by means of context marker. The first message above, "Move", has been assigned the @action:button marker, where @action is the main context that describes the text as an action to be taken (e.g. operation on data or opening of a new dialog), and :button the interface subcue saying that this text is displayed on a pushbutton widget. The second message, "Descending", has been marked as a semantically a list entry (@item), displayed in a menu (:inmenu). The interface subcue can be left out if none is appropriate.
The other difference is the use of semantic tags, which convey the meaning of the element. For example, the <filename>%1</filename> bit in the third message tells that the substituted text is the name of a file, and the <title> and <para> tags in the last message lay out a clear structure of longer informational texts.
Note |
---|
The context marker can be added when working with Qt Designer too. Each text label of a widget has a comment attribute, which can be used in same manner as context argument of i18nc() call. |
Even when context marker is present, sometimes the programmer may want to provide an additional free-form clarification to translators, in order shed more light on particularly ambiguous strings. It is just separated by a whitespace from the context marker proper, like this:
i18nc("@item:inmenu Sorting order", "Descending");
KUIT markup has advantages both to users and to translators of applications that make use of it.
For the users, the use of semantic tags means consistent formatting of same kinds of text. The notorious example of inconsistent visual formatting would be filenames and paths, which are sometimes put in as is, sometimes in quotes (and ordinary quotes at that, rather than proper English fancy quotes), and sometimes in bold tags. Furthermore, the text withing the tag may be modified with semantic markup; for example, the <filename> text is transformed from "/" path delimiters to platform specific ones.
Translators will benefit from both context markers and tags. The "Move" string in the example above had @action context, for which the translator may use command form of the verb, while gerund form (like "Moving") may be more appropriate in the @title context, which would be used if the string was title of the menu, option group, etc. The interface subcue, like :button above, if present additionally enables translator to mentally picture the actual runtime appearance on the spot. Tags within the text will also benefit translators, as they may clear up the structure of the sentence, especially in presence of placeholder substitutions.
The context markers also serve a technical purpose. They decide whether what form of visual formatting is used. E.g. any @title context will use plain text, whereas @info contexts will mostly be formatted with HTML tags (may depend on the interface subcue too).
None the least, semantic markup removes the burden of thinking about the visual formatting to apply while programming, like "Should I put the path in quotes or <b>?", or "Should the title be <h2> or <h3>?", and so on.
Context marker consist of the main context and the interface subcue. The subcue needs not be present, and should be provided only when the text clearly maps to what the subcue describes. KUIT presently defines the following main contexts and their possible interface subcues:
KUIT semantic tags come in several logical groups:
Phrase tags are mostly terminal, meaning that by default they will not admit any subtags; where some subtags can be used, it is so indicated. KUIT defines the folowing description tags:
i18nc("@action:inmenu",
"Open with <application>%1</application>", appName);
i18nc("@info:whatsthis",
"You can try the following snippet:<bcode>" "\begin{equation}" " C_{D_i} = \frac{C_z^2}{e \pi \lambda}" "\end{equation}" "</bcode>");
i18nc("@info",
"This will call <command>%1</command> internally.", cmdName);
i18nc("@info",
"Consult man entry for <command section='1'>%1</command>", cmdName);
i18nc("@info",
"Send bug reports to <email>%1</email>.", emailNull);
i18nc("@info",
"Send praises to <email address='%1'>the author</email>.", emailMy);
i18nc("@info:progress",
"Checking <emphasis>feedback</emphasis> circuits...");
i18nc("@info",
"Assure that your <envar>PATH</envar> is properly set.");
i18nc("@info", "Cannot read <filename>%1</filename>.", filename);
i18nc("@info",
"<filename><envar>HOME</envar>/.foorc</filename> does not exist.");
i18nc("@info:tooltip",
"Execute <icode>svn merge</icode> on selected revisions.");
i18nc("@info:whatsthis",
"The line colors can be changed under " "<interface>Settings->Visuals</interface>.");
i18nc("@info:tooltip",
"Go to <link>%1</link> website.", urlKDE);
i18nc("@info:tooltip",
"Go to <link url='%1'>the KDE website</link>.", urlKDE);
i18nc("@info",
"The fortune cookie says: <message>%1</message>", trouble);
i18nc("@info:progress",
"Connecting to <numid>%1</numid>...", portNo);
i18nc("@info",
"Replace <placeholder>name</placeholder> with your name.");
i18nc("@item:type",
"<placeholder>All images</placeholder>");
i18nc("@info", "Apply color scheme <resource>%1</resource>?", colScheme);
i18nc("@info:whatsthis",
"Cycle through layouts using <shortcut>Alt+Space</shortcut>.");
Sentence tags mark complete sentences in text, and will admit any phrase tags as subtags. The following are defined:
i18nc("@info",
"Probably the best known of all duck species is the Mallard. " "It breeds throughout the temperate areas around the world. " "<note>Most domestic ducks are derived from Mallard.</note>");
i18nc("@info",
"Really delete this key?" "<warning>This cannot be undone.</warning>");
Structure tags are used to split longer texts into titles, paragraphs, and lists. By default they can contain any phrase or sentence tags, unless indicated otherwise.
If any of the structure tags is present, then there must be no text outside of structure tags. The following is not valid KUIT markup:
// invalid markup
i18nc("@info",
"<title>History Sidebar</title>" "You can configure the history sidebar here."); // <para> missing
Semantic markup cannot be used in "dumb" strings, which do not pass through KDE's i18n subsystem. These would be, for example, strings in .desktop format files. But not the strings in UI files, as in Qt Designer they can be equipped with both context markers (via comment field to text properties) and semantic tags.
Qt's rich text HTML tags can be used concurrently with KUIT tags, but this is not advised unless necessary. They may be needed, for example, to create tables or insert images, as KUIT does not implement this functionality at the moment.
Sometimes, the visual formatting may not be quite appropriate for the output device; each context comes with a default formatting. For example, if the @info context is applied to a string which is used in a widget that does not handle rich text, it will come out with HTML tags displayed verbatim. To handle this, visual formatting can be explicitly signaled by /format modifier to context marker:
i18nc("@info/plain",
"<filename>%1</filename> does not exist", fname);
Presently, the possible format modifiers are /plain, /rich and /shell. In particular, any strings which are output to the terminal should have explicit /shell format.
Admittedly, KUIT markup is an additional thing to be learned and applied throughout the course of development. By now you may be wondering if it is worthwile to invest time into that, particularly in view of two cases:
You are strongly advised to use KUIT for new code. Compared to the total time spent on code, writing UI messages is only a small fraction. Context markers will help translators a lot, and message tags will provide consistent visual text formatting to your application.
When modifying existing code, there are two issues. First, obviously it is a daunting task to go through hundreds (or worse) of messages and equip them with semantic markup. Second, by changing the messages, the translators too will have to review their existing translations; however, it is not expected that the porting will take so "epic" proportions that the translators cannot keep up. Sumarily, feel free to do as you see fit.
Additionally, for porting, keep in mind that it is not all-or-nothing proposal. Any amount of semantic messages are useful to translators, and users can only see the difference for the better. Thus, for example, deciding to make all new messages semantic and slowly over time fix old messages, is a perfectly fine strategy.
To make your job easier, there is a standalone i18n-checker script that you can run on your code by yourself, and which is also daily run on the code repository wide (as part Krazy-framework), that will report the problems in KUIT markup, as well as check some other i18n nuances. It can be found in the KDE repository, in ((when it's done)).
Last but not the least, there is also a chic-effect to the KUIT. Its wide use, together with some under-the-hood elements on translators' disposal, will make KDE4's i18n layer without peer in free or proprietary software world. Insofar as you consider localization excellence an important part of the overall KDE excellence, this is something that may also tip your decision :) -- Your Friendly Translator.