Development/Tutorials/Localization/i18n Semantics - Revision history

Zander at 12:23, 22 March 2012

2012-03-22T12:23:18Z

Icwiener: Fix syntax highlighting.

2011-06-27T17:20:13Z

Fix syntax highlighting.

Show changes

Aspotashev: Undo revision 58729 by Aspotashev (Talk)

2011-05-12T17:08:58Z

Undo revision 58729 by Aspotashev (Talk)

Aspotashev: add KUIT "@action:undo"

2011-05-11T19:05:40Z

add KUIT "@action:undo"

Odysseus: /* Abstract */

2010-11-27T16:37:41Z

‎Abstract

Ilic: Mention new 'row' subcue.

2010-06-12T16:24:21Z

Mention new 'row' subcue.

Smarquis: /* Should I Go For Semantic Markup? */

2009-04-28T17:38:58Z

‎Should I Go For Semantic Markup?

Ilic: Added attribute 'strong' to 'emphasis'.

2009-04-21T19:18:43Z

Added attribute 'strong' to 'emphasis'.

Ilic: Change of context property name in Designer in Qt 4.5.

2009-04-21T18:19:48Z

Change of context property name in Designer in Qt 4.5.

Ilic: Notes on default visual formatting by role/subcue combination.

2009-04-18T18:16:06Z

Notes on default visual formatting by role/subcue combination.

@@ Line 44: / Line 44: @@
 </syntaxhighlight>}}
-Even when context marker is present, sometimes the programmer may want to provide an additional "free-form" description to translators, in order shed more light on particularly ambiguous strings. The free-form description is just separated by a whitespace from the context marker proper, like this:
+Even when a context marker is present, sometimes the programmer may want to provide an additional "free-form" description to translators, in order to shed more light on particularly ambiguous strings. The free-form description is just separated by a whitespace from the context marker proper, like this:
 <syntaxhighlight lang="cpp-qt">
 i18nc("@item:inmenu Sorting order", "Descending");
@@ Line 63: / Line 63: @@
 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. A notorious example of inconsistent visual formatting are 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 when semantically marked; for example, the standard "/" path delimiters in a <tt><filename></tt> text will be substituted for platform specific ones.
+For the users, the use of semantic tags means consistent formatting of same kinds of text. A notorious example of inconsistent visual formatting are 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 within the tag may be modified when semantically marked; for example, the standard "/" path delimiters in a <tt><filename></tt> text will be substituted for platform specific ones.
 Translators will benefit from both context markers and tags. For the <tt>@action</tt> role of the "Move" string in the example above, the translator may use command form of the verb, while gerund form (like "Moving") may be more appropriate for the <tt>@title</tt> role, which would be used if the string was title of the menu, window, etc. The interface subcue, like <tt>:button</tt> above, if present, additionally enables the translator to mentally picture the actual runtime GUI. Tags within the text will also benefit translators, as they may clarify the structure of the sentence, especially in presence of placeholder substitutions.

@@ Line 87: / Line 87: @@
 :: <tt>:inmenu</tt> - menu entries that perform an action
 :: <tt>:intoolbar</tt> - toolbar buttons
+:
 : All <tt>@action</tt> markers are formatted as '''plain text''' by default.

@@ Line 87: / Line 87: @@
 :: <tt>:inmenu</tt> - menu entries that perform an action
 :: <tt>:intoolbar</tt> - toolbar buttons
+:
 : All <tt>@action</tt> markers are formatted as '''plain text''' by default.

← Older revision		Revision as of 16:37, 27 November 2010
Line 2:		Line 2:

	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?		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?
		+
		+	{{Note\|A [http://people.ubuntu.com/~apachelogger/misc/i18nccheatsheet.png handy cheat sheet] for the KUIT semantic markup language has been prepared by apachelogger.}}

	== Semantic Markup by Examples ==		== Semantic Markup by Examples ==

@@ Line 89: / Line 89: @@
 ; <tt>@title</tt>
-: Text that is semantically a title in the interface. These would include window titles, menu titles, tab names, option group names in configuration dialogs, and column names in list views.
+: Text that is semantically a title in the interface. These would include window titles, menu titles, tab names, option group names in configuration dialogs, and column and row names in list views.
+:
 :: <tt>:window</tt> - window title (also dock name)
@@ Line 96: / Line 96: @@
 :: <tt>:group</tt> - option group
 :: <tt>:column</tt> - column name
+:
 : All <tt>@title</tt> markers are formatted as '''plain text''' by default.

@@ Line 371: / Line 371: @@
 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 an i18n-checker script that will report the problems in KUIT markup, as well as check some other i18n nuances. It is run daily on KDE code repository-wide as part Krazy-framework, but you can also run it locally on your code. It can be found in {{path|trunk/trunk/KDE/kdesdk/ebn/krazy/plugins/i18ncheckarg}}. Furthermore, as of this moment Krazy checks only C++ sources, while when you run the script locally, some of the XML sources containing translatable strings will be checked as well. <tt>i18ncheckarg</tt> requires Perl libxml bindings, which are probably already packaged for your distribution (Debian package is libxml-libxml-perl).
+To make your job easier, there is an i18n-checker script that will report the problems in KUIT markup, as well as check some other i18n nuances. It is run daily on KDE code repository-wide as part Krazy-framework, but you can also run it locally on your code. It can be found in {{path|trunk/quality/krazy2/plugins/general/i18ncheckarg}}. Furthermore, as of this moment Krazy checks only C++ sources, while when you run the script locally, some of the XML sources containing translatable strings will be checked as well. <tt>i18ncheckarg</tt> requires Perl libxml bindings, which are probably already packaged for your distribution (Debian package is libxml-libxml-perl).
 {{note|By default <tt>i18ncheckarg</tt> takes a single filename to check, but using <tt>--allsources</tt> option you can provide as many file or directory paths as you wish; typically you would give top directory path to your sources. Also, to report all missing context markers use <tt>--ctxmark</tt> option, or otherwise missing markers will be reported only if some threshold of marked-to-total number of messages in a file is reached.}}
 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.

@@ Line 198: / Line 198: @@
        "Checking <emphasis>feedback</emphasis> circuits...");
 </code>
 ; <tt>&lt;envar&gt;</tt>

@@ Line 35: / Line 35: @@
 The other difference is the use of the semantic tags, which convey the meaning of a word or phrase within the text. The <tt><filename>%1</filename></tt> part of the third message tells that the substituted text is the name of a file. The <tt><title></tt> and <tt><para></tt> tags in the last message clearly lay out structure of a longer informational text.
-{{note|The context marker can be added when within some of the standard XML sources too. In Qt Designer forms (<tt>.ui</tt> files), each text label to a widget has <tt>comment</tt> attribute, which can be used in the same manner as context argument of <tt>i18nc()</tt> call. Similarly, in the KXmlGui (<tt>.rc</tt>) and KConfigXT (<tt>.kcfg</tt>) files, tags <tt><text></tt>, <tt>label</tt>, and <tt>whatsthis</tt> can have a <tt>context</tt> attribute. For example:
+{{note|The context marker can be added when within some of the standard XML sources too. In Qt Designer forms (<tt>.ui</tt> files), each text label to a widget has <tt>comment</tt> attribute (presented as "disambiguation" property within Designer, or "comment" prior to Qt 4.5), which can be used in the same manner as context argument of <tt>i18nc()</tt> call. Similarly, in the KXmlGui (<tt>.rc</tt>) and KConfigXT (<tt>.kcfg</tt>) files, tags <tt><text></tt>, <tt>label</tt>, and <tt>whatsthis</tt> can have a <tt>context</tt> attribute. For example:
 <code>
 <label context="@label">Hide trivial details</label>

@@ Line 63: / Line 63: @@
 For the users, the use of semantic tags means consistent formatting of same kinds of text. A notorious example of inconsistent visual formatting are 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 when semantically marked; for example, the standard "/" path delimiters in a <tt><filename></tt> text will be substituted for platform specific ones.
-Translators will benefit from both context markers and tags. For the <tt>@action</tt> role of the "Move" string in the example above, the translator may use command form of the verb, while gerund form (like "Moving") may be more appropriate for the <tt>@title</tt> role, which would be used if the string was title of the menu, window, etc. The interface subcue, like <tt>:button</tt> above, if present, additionally enables the translator to mentally picture the actual runtime GUI. Tags within the text will also benefit translators, as they may clear up the structure of the sentence, especially in presence of placeholder substitutions.
+Translators will benefit from both context markers and tags. For the <tt>@action</tt> role of the "Move" string in the example above, the translator may use command form of the verb, while gerund form (like "Moving") may be more appropriate for the <tt>@title</tt> role, which would be used if the string was title of the menu, window, etc. The interface subcue, like <tt>:button</tt> above, if present, additionally enables the translator to mentally picture the actual runtime GUI. Tags within the text will also benefit translators, as they may clarify 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. For example, any <tt>@title</tt> role will use plain text, whereas <tt>@info</tt> roles will mostly be formatted with HTML tags, except in case of some subcues, when they will be plain text.
+Context markers also serve a technical purpose: they decide whether what form of visual formatting is used. For example, any <tt>@title</tt> role will use plain text, whereas <tt>@info</tt> will frequently produce rich text, depending on the subcue.
 None the least, semantic markup removes the burden from programmers of thinking about the visual formatting to apply, like "''Should I put the path in quotes or &lt;b>?''", or "''Should the title be &lt;h2> or &lt;h3>?''", and so on.
@@ Line 72: / Line 72: @@
 Context marker consist of the semantic role and the interface subcue, in the form of <tt>@role:subcue</tt>. Each message should be given a role, but the subcue may be left out. The subcue should be given only when the string clearly maps to the user interface element that it describes.
 {{warning|Roles and subcues in the context marker cannot be specified at will, but must be drawn from the sets defined below. This is important for several reasons, one being that translators have deliberated about and agreed upon the meanings of presented sets, rather than having to second-guess arbitrary combinations.}}
-KUIT defines the following roles and subcues:
+KUIT defines the following roles and subcues (with notes on default visual formatting):
 ; <tt>@action</tt>
@@ Line 83: / Line 85: @@
 :: <tt>:inmenu</tt> - menu entries that perform an action
 :: <tt>:intoolbar</tt> - toolbar buttons
 ; <tt>@title</tt>
@@ Line 92: / Line 96: @@
 :: <tt>:group</tt> - option group
 :: <tt>:column</tt> - column name
 ; <tt>@option</tt>
@@ Line 98: / Line 104: @@
 :: <tt>:check</tt> - checkbox label
 :: <tt>:radio</tt> - radio-button label
 ; <tt>@label</tt>
@@ Line 107: / Line 115: @@
 :: <tt>:textbox</tt> - text and edit boxes
 :: <tt>:chooser</tt> - chooser widgets (fonts, colors, etc.)
 ; <tt>@item</tt>
@@ Line 116: / Line 126: @@
 :: <tt>:inrange</tt> - range labels to sliders, etc.
 :: <tt>:intext</tt> - words and phrases inserted into other messages
 ; <tt>@info</tt>
@@ Line 127: / Line 139: @@
 :: <tt>:credit</tt> - contributor names and their contributions
 :: <tt>:shell</tt> - info output to the terminal, rather than to GUI
 == Semantic Tags ==
@@ Line 327: / Line 341: @@
 </code>
-== Limitations to Use of Semantic Markup ==
+== Limitations to Semantic Markup ==
 Semantic markup cannot be used in "dumb" strings, which do not pass through KDE's i18n subsystem. These would be, for example, strings in <tt>.desktop</tt> 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.