diff --git a/cmake/kf5i18nuic.cmake b/cmake/kf5i18nuic.cmake index 24f9bf0..6652d23 100644 --- a/cmake/kf5i18nuic.cmake +++ b/cmake/kf5i18nuic.cmake @@ -1,49 +1,49 @@ # Copyright (c) 2006, Alexander Neundorf, # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions # are met: # 1. Redistributions of source code must retain the above copyright # notice, this list of conditions and the following disclaimer. # 2. Redistributions in binary form must reproduce the above copyright # notice, this list of conditions and the following disclaimer in the # documentation and/or other materials provided with the distribution. # 3. Neither the name of the University nor the names of its contributors # may be used to endorse or promote products derived from this software # without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE # ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF # SUCH DAMAGE. EXECUTE_PROCESS(COMMAND ${KDE_UIC_EXECUTABLE} -tr tr2i18n ${KDE_UIC_FILE} OUTPUT_VARIABLE _uic_CONTENTS ) set(KDE_UIC_CPP_FILE ${KDE_UIC_H_FILE}) IF (_uic_CONTENTS) - #replace tr218n("") with QString::null to avoid warning from KLocale - STRING(REGEX REPLACE "tr2i18n\\(\"\"\\)" "QString::null" _uic_CONTENTS "${_uic_CONTENTS}" ) - STRING(REGEX REPLACE "tr2i18n\\(\"\", \"\"\\)" "QString::null" _uic_CONTENTS "${_uic_CONTENTS}" ) + #replace tr218n("") with QString() to avoid warning from KLocale + STRING(REGEX REPLACE "tr2i18n\\(\"\"\\)" "QString\\(\\)" _uic_CONTENTS "${_uic_CONTENTS}" ) + STRING(REGEX REPLACE "tr2i18n\\(\"\", \"\"\\)" "QString\\(\\)" _uic_CONTENTS "${_uic_CONTENTS}" ) #replace image15_data with img15_filename to make enable_final work STRING(REGEX REPLACE "image([0-9]+)_data" "img\\1_${KDE_UIC_BASENAME}" _uic_CONTENTS "${_uic_CONTENTS}") #fixup include guard STRING(REGEX REPLACE "#ifndef " "#ifndef UI_" _uic_CONTENTS "${_uic_CONTENTS}") STRING(REGEX REPLACE "#define " "#define UI_" _uic_CONTENTS "${_uic_CONTENTS}") FILE(WRITE ${KDE_UIC_CPP_FILE} "#include \n\n${_uic_CONTENTS}\n") ENDIF() diff --git a/docs/programmers-guide.md b/docs/programmers-guide.md index 9505366..934bf39 100644 --- a/docs/programmers-guide.md +++ b/docs/programmers-guide.md @@ -1,2281 +1,2281 @@ Programmer's Guide {#prg_guide} ================== - [Introduction](#intro) - [Writing Messages](#write_i18n) - [General Messages](#gen_usage) - [Specialized Messages](#spec_usage) - [Placeholder Substitution](#subs_notes) - [Writing Good Texts](#good_text) - [Writing Good Contexts](#good_ctxt) - [Extraction-Only Macros](#i18n_noop) - [Messages before creation of Q*Application instance](#before_qapp) - [Connecting Calls to Catalogs](#link_cat) - [Connecting to Catalogs in Application Code](#link_prog) - [Connecting to Catalogs in Library Code](#link_lib) - [Connecting to Catalogs in Non-Code Files](#link_noncode) - [Handling Catalog Files](#handle_cat) - [Extracting Templates](#handle_extract) - [Placing and Installing Catalogs](#handle_install) - [Updating Catalogs](#handle_update) - [Semantic Markup](#kuit_markup) - [Defining Tags](#kuit_def_tags) - [Selecting Visual Format](#kuit_sel_fmt) - [Escaping](#kuit_escape) - [Predefined Tags](#kuit_tags) - [Predefined Entities](#kuit_ents) - [Localizing Non-Text Resources](#non_text) - [Further References](#refs) ## Introduction *Internationalization* (i18n) is the process of preparing the source code such that the running program can receive and output user-visible information in various human languages, or, more precisely, *locales*. This is because the same language may be spoken at several places which differ in other details of relevance to the software internationalization (e.g. dialect, calendar, etc). I18n is performed by the programmer. *Localization* (l10n) is the process of adapting relevant program resources for a particular locale. L10n is performed by the translator, who is usually a native of the locale. User interface text is the most prominent resource needing l10n. In the source code, there are two general approaches to writing i18n'd user-visible strings, hereafter called *messages*. In the first approach, the programmer writes symbolic identifier in place of actual message text, and then for each language there is a file, called translation *catalog*, which contains the actual text linked to the appropriate identifier. For example, in the code: ~~~ QString msg = getId("out_of_disk_space"); ~~~ and in the translation catalog: ~~~ out_of_disk_space "There is no space left on the disk." ~~~ In the second approach, the programmer writes actual text inside the source code, in an agreed upon human language, which is usually American English. Then there is a translation catalog for every *other* language, in which English and translated text of the message are linked. For example, in the code: ~~~ QString msg = i18n("There is no space left on the disk."); ~~~ and in the translation catalog: ~~~ msgid "There is no space left on the disk." msgstr "Nema više prostora na disku." ~~~ One may observe that the second approach is technically a generalization of the first approach. However, in actual use there are non-negligible differences in the i18n/l10n workflow between these approaches, and therefore they are treated as qualitatively different. Both approaches -- the symbolic-identifier and the actual-text -- have some advantages and disadvantages over each other. That is why today both are in use, in software i18n in general. Within free software, though, the actual-text approach is considerably more widespread, as embodied in the GNU Gettext i18n system. Whether this is a historical accident, or due to sensibilities of people writing free software, is left to the interested reader to research. The KDE Ki18n library, being built atop Gettext, provides the actual-text approach. In the following it is described how to use Ki18n, from the viewpoint of programmers and maintainers. Basic instructions are split into three parts: \li The first part deals with how to write i18n messages in the code. This is the largest and the most important part, since there are many nuances to preparing quality messages for translation. Section: \ref write_i18n. \li The second part describes how to connect particular translation calls with particular translation catalogs, so that the system can know in which catalogs to search for translations. In particular, there are some differences here depending on whether the piece of code is an application or a library. Section: \ref link_cat. \li The third part explains how to *extract* messages from the code, in order to create the translation *template*. The template is simply a clean translation catalog (having only English part of each message), which the translator copies over and fills in the translations for a particular language. Then it is shown how and where to install translation catalogs, and how to update existing translation catalogs to newly extracted templates (after some new development has been done, causing new messages to appear, some to be removed, and some modified). Unlike in the GNU Gettext manual, here there are no dependencies or references to a particular software build system; this is left to the maintainer to choose. Section: \ref handle_cat. There are also two special topics: \li Some programmers like to have more structure and consistency in message texts, and for them Ki18n provides a customizable semantic markup. Section: \ref kuit_markup. \li Sometimes there are program resources other than text that require localization. Ki18n provides a generic, though rudimentary solution for such cases. Section: \ref non_text. ## Writing Messages Most messages can be internationalized with simple `i18n*` calls, which are described in the section \ref gen_usage. A few messages may require treatment with `ki18n*` calls, and when this is needed is described in the section \ref spec_usage. Argument substitution in messages is performed using the familiar Qt syntax `%`, but there may be some differences; the section \ref subs_notes gives some notes about placeholders. Finally, guidelines for writing good messages are given in sections \ref good_text and \ref good_ctxt. ### General Messages General messages are wrapped with `i18n*` calls. These calls are *immediate*, which means that they return the final localized text (including substituted arguments) as a `QString` object, that can be passed to UI widgets. The most frequent message type, a simple text without any arguments, is handled like this: ~~~ QString msg = i18n("Just plain info."); ~~~ The message text may contain arbitrary Unicode characters, and the source file *must* be UTF-8 encoded. Ki18n supports no other character encoding. If there are some arguments to be substituted into the message, `%` placeholders are put into the text at desired positions, and arguments are listed after the string: ~~~ QString msg = i18n("%1 has scored %2", playerName, score); ~~~ Arguments can be of any type for which there exists an overloaded `KLocalizedString::subs` method. Up to 9 arguments can be inserted in this fashion, due to the fact that `i18n` calls are realized as overloaded templates. If more than 9 arguments are needed, which is extremely rare, a `ki18n*` call (described later) must be used. Sometimes a short message in English is ambiguous to translators, possibly leading to a wrong translations. Ambiguity can be resolved by providing a context string along the text, using the `i18nc` call. In it, the first argument is the context, which only the translator will see, and the second argument is the text which the user will see: ~~~ QString msg = i18nc("player name - score", "%1 - %2", playerName, score); ~~~ Section \ref good_ctxt gives a few pointers on when contexts are needed, and what they should contain. In messages stating how many of some kind of objects there are, where the number of objects is inserted at run time, it is necessary to differentiate between *plural forms* of the text. In English there are only two forms, one for number 1 (singular) and another form for any other number (plural). In other languages this might be more complicated (more than two forms), or it might be simpler (same form for all numbers). This is handled properly by using the `i18np` plural call: ~~~ QString msg = i18np("%1 image in album %2", "%1 images in album %2", numImages, albumName); ~~~ The plural form is decided by the first integer-valued argument, which is `numImages` in this example. In rare cases when there are two or more integer arguments, they should be ordered carefully. In QML code, due to some limitations, always the first argument will be treated as plural-deciding, so it should be an appropriate number (integer or a round double); otherwise, behavior is undefined. It is also allowed to omit the plural-deciding placeholder, for example: ~~~ QString msg = i18np("One image in album %2", "%1 images in album %2", numImages, albumName); ~~~ or even: ~~~ QString msg = i18np("One image in album %2", "More images in album %2", numImages, albumName); ~~~ If the code context is such that the number is always greater than 1, the plural call must be used nevertheless. This is because in some languages there are different plural forms for different classes of numbers; in particular, the singular form may be used for numbers other than 1 (e.g. those ending in 1). If a message needs both context and plural forms, this is provided by `i18ncp` call: ~~~ QString msg = i18ncp("file on a person", "1 file", "%1 files", numFiles); ~~~ In the basic `i18n` call (no context, no plural) it is not allowed to put a literal string as the first argument for substitution. In debug mode this will even trigger a static assertion, resulting in compilation error. This serves to prevent misnamed calls: context or plural frequently needs to be added at a later point to a basic call, and at that moment the programmer may forget to update the call name from `i18n` to `i18nc/p`. Furthermore, an empty string should never be wrapped with a basic `i18n` call (no `i18n("")`), because in translation catalog the message with empty text has a special meaning, and is not intended for client use. The behavior of `i18n("")` is undefined, and there will be some warnings in debug mode. There is also a complement of `i18nd*` calls (`i18nd`, `i18ndc`, `i18ndp`, `i18ndcp`), which are not supposed to be used directly, but as will be explained in the section \ref link_cat. ### Specialized Messages There are some situations where `i18n*` calls are not sufficient, or are not convenient enough. One obvious case is if more than 9 arguments need to be substituted. Another case is if it would be easier to substitute arguments later on, after the line with the i18n call. For cases such as these, `ki18n*` calls can be used. These calls are *deferred*, which means that they do not return the final translated text as `QString`, but instead return a `KLocalizedString` instance which needs further treatment. Arguments are then substituted one by one using `KLocalizedString::subs` methods, and after all arguments have been substituted, the translation is finalized by one of `KLocalizedString::toString` methods (which return `QString`). For example: ~~~ KLocalizedString ks; case (reportSource) { SRC_ENG: ks = ki18n("Engineering reports: %1"); break; SRC_HEL: ks = ki18n("Helm reports: %1"); break; SRC_SON: ks = ki18n("Sonar reports: %1"); break; default: ks = ki18n("General report: %1"); } QString msg = ks.subs(reportText).toString(); ~~~ `subs` methods do not update the `KLocalizedString` instance on which they are invoked, but return a copy of it with one argument slot filled. This allows to use `KLocalizedString` instances as a templates for constructing final texts, by supplying different arguments. Another use for deferred calls is when special formatting of arguments is needed, like requesting the field width or number of decimals. `subs` methods can take these formatting parameters. In particular, arguments should not be formatted in a custom way, because `subs` methods will also take care of proper localization (e.g. use either dot or comma as decimal separator in numbers, etc): ~~~ // BAD (number not localized): QString msg = i18n("Rounds: %1", myNumberFormat(n, 8)); // Good: QString msg = ki18n("Rounds: %1").subs(n, 8).toString(); ~~~ Like with `i18n`, there are context, plural, and context-plural variants of `ki18n:` ~~~ ki18nc("No function", "None").toString(); ki18np("File found", "%1 files found").subs(n).toString(); ki18ncp("Personal file", "One file", "%1 files").subs(n).toString(); ~~~ `toString` methods can be used to override the global locale. To override only the language of the locale, `toString` can take a list of languages for which to look up translations (ordered by decreasing priority): ~~~ QStringList myLanguages; ... QString msg = ki18n("Welcome").toString(myLanguages); ~~~ The section \ref link_cat describes how to specify the translation *domain*, a canonical name for the catalog file from which `*i18n*` calls will draw translations. But `toString` can always be used to override the domain for a given call, by supplying a specific domain: ~~~ QString trName = ki18n("Georgia").toString("country-names"); ~~~ Relevant here is the set of `ki18nd*` calls (`ki18nd`, `ki18ndc`, `ki18ndp`, `ki18ndcp`), which can be used for the same purpose, but which are not intended to be used directly. This will also be covered in the section \ref link_cat. #### Dynamic Contexts Translators are provided with the capability to script translations, such that the text changes based on arguments supplied at run time. For the most part, this feature is transparent to the programmer. However, sometimes the programmer may help in this by providing a *dynamic* context to the message, through `KLocalizedString::inContext` methods. Unlike the static context, the dynamic context changes at run time; translators have the means to fetch it and use it to script the translation properly. An example: ~~~ KLocalizedString ks = ki18nc("%1 is user name; may have " "dynamic context gender=[male,female]", "%1 went offline"); if (knownUsers.contains(user) && !knownUsers[user].gender.isEmpty()) { ks = ks.inContext("gender", knownUsers[user].gender); } QString msg = ks.subs(user).toString(); ~~~ Any number of dynamic contexts, with different keys, can be added like this. Normally every message with a dynamic context should also have a static context, like in the previous example, informing the translator of the available dynamic context keys and possible values. Like `subs` methods, `inContext` does not modify the parent instance, but returns a copy of it. ### Messages before creation of Q*Application instance Fetching the translated messages only works after the Q*Application instance has been created. So any code which will be executed before and which handles text that should be translated has to delay the actual lookup in the catalog (like other locale-dependent actions), in one of two ways: either by using statically initialized character arrays wrapped in `I18N_*` macros for extraction, and later making the actual `i18n*` calls (see section \ref i18n_noop); or by using `ki18n*` calls to create `KLocalizedString` instances, which do not perform immediate catalog lookup, and later fetching the actual translation through their toString() methods (see section \ref spec_usage); One reason for this is that Gettext follows the standard C/POSIX locale settings. By standard on the start of a program all locale categories are fixed to the "C" locale, including the locale for the message catalog category (LC_MESSAGES). To use instead the locales specified by the environment variables, the locale values in the runtime need to be set to an empty string. This is usually done in one go for all locale categories by this call: ~~~ setlocale(LC_ALL, ""); ~~~ From this point on the locale specific environment variables "LANGUAGE", "LC_*" and "LANG" are considered for deciding which locale to use for which category. This includes Gettext when picking the message catalog to use. The constructor of QCoreApplication (and thus its subclasses) does a call like that. Which means any `i18n*` calls done _after_ the creation of the QCoreApplication instance (or of its subclasses) will use a message catalog based on the locale specific environment variables, as one usually expects, But any calls _before_ will use a message catalog for the "C" locale. ### Placeholder Substitution Hopefully, most of the time `%` placeholders are substituted in the way one would intuitively expect them to be. Nevertheless, some details about substitution are as follows. Placeholders are substituted in one pass, so there is no need to worry about what will happen if one of the substituted arguments contains a placeholder, and another argument is substituted after it. All same-numbered placeholders are substituted with the same argument. Placeholders directly index arguments: they should be numbered from 1 upwards, without gaps in the sequence, until each argument is indexed. Otherwise, error marks will be inserted into message at run time (when the code is compiled in debug mode), and any invalid placeholder will be left unsubstituted. The exception is the plural-deciding argument in plural calls, where it is allowed to drop its placeholder, in either the singular or the plural text. If none of the arguments supplied to a plural call is integer-valued, an error mark will be inserted into the message at run time (when compiled in debug mode). Integer arguments will be by default formatted as if they denote an amount, according to locale rules (thousands separation, etc.) But sometimes an integer is a numerical identifier (e.g. port number), and then it should be manually converted into `QString` beforehand to avoid treatment as amount: ~~~ i18n("Listening on port %1.", QString::number(port)); ~~~ ### Writing Good Texts When writing message texts, sometimes it is tempting to assemble text from pieces such as to have less repetition. However, such shortcuts frequently cannot work for other languages, and are almost always confusing to translators. The first rule of writing good message texts is therefore to *keep sentences together and clearly structured* (or "no word puzzles"), even at the cost of some repetition. At its basic, this rule means always to use placeholders for insertion of run time arguments, rather than string concatenation. For example: ~~~ // BAD: i18n("File ") + filePath + i18n(" not found."); // Good: i18n("File %1 not found.", filePath); ~~~ This is rather obvious, since it also results in clearer and shorter code. But sometimes placeholders can be overused: ~~~ // BAD: i18n("This contact is now %1.", isOnline ? i18n("online") : i18n("offline")); // Good: isOnline ? i18n("This contact is now online.") : i18n("This contact is now offline."); ~~~ The shorter version here is bad, because the sentence structure of translation may need to change by more than the one word, and also because a less thorough translator may fail to check in which way the short messages "online" and "offline" are used. If an otherwise long text needs to differ in only small part, then a reasonable solution is to split it at sentence level, but also explain the situation to translators through context: ~~~ // BAD: i18n("Something very long here. This contact is now %1.", isOnline ? i18n("online") : i18n("offline")); // Good: i18nc("%1 one of the 'This contact...' messages below", "Something very long here. %1", isOnline ? i18n("This contact is now online.") : i18n("This contact is now offline.")); // BAD: i18n("Something very long here. ") + isOnline ? i18n("This contact is now online.") : i18n("This contact is now offline."); ~~~ The third version above is bad because, firstly, the translator may wonder about the trailing space in the first message or simply overlook it, and secondly, there may be some cross-dependency between the translation of the long message and the short messages. In general, insertions of one message into another should *always* be accompanied by contexts, and composition-significant leading and trailing whitespace should be avoided. The second basic rule of writing good texts is to *expose every user-visible text for translation*. One should *never* make assumptions of the type "this does not need translation" or "it will be same in every language". One example where programmers sometimes make such assumption are compositions without any letters: ~~~ // BAD: QString("%1: %2").arg(albumName, playCount); // Good: i18nc("album name: play count", "%1: %2", albumName, playCount) ~~~ Here, in some languages the arrangement of whitespace will need to differ (e.g. a space may be needed before the colon as well). Letter-free compositions should also normally be equipped with context, because, for example, separation may depend on type of arguments. Another example of user-visible texts sometimes wrongly omitted from i18n are proper names: ~~~ // BAD: label1->setText(i18n("Written by:")); label2->setText("Roofus McBane"); // Good: label1->setText(i18n("Written by:")); label2->setText(i18n("Roofus McBane")); ~~~ Proper names too may need localization, for example, transliteration when the target language uses a different writing system. This holds for proper names of people, and of anything else. When it comes to text markup, like the HTML subset supported by Qt rich text processing, opinions are divided on how much of it to expose for translation. One argument goes that markup may be confusing for translators, and that exposing it increases the chance of syntactical errors in translation. This is true as such, but it should be balanced with situations where, either, the translator needs to modify the markup, or, the markup will convey some context to translator. For example, typographical modifiers should always be left in: ~~~ // BAD: label->setText("" + i18n("Disk almost full:") + ""); // Good: label->setText(i18n("Disk almost full:")); ~~~ because the target language may have different typographical standards (e.g. CJK languages tend to avoid boldface in text body font sizes, as it makes ideographs harder to recognize). Especially if tags are found around internal parts of the message text, it would be ungainly to hide them, e.g. by placeholder insertion. But, values to tag attributes, such as links in \, tags, should be inserted through placeholders (unless it is expected that translators provide localized values). In this example: ~~~ // Good: i18n("

Preprocessing has failed.

" "

Please check your bracketed images stack.

" "

Click \"Details\" to show processing details.

") ~~~ `

` tags could be avoided by splitting this message into one message per sentence, but this should not be done, because paragraphs should be translated as single units of meaning. Another important point about XML-like text markup, is to try and keep it well-formed in XML sense on the level of standalone message. For example: ~~~ // BAD (for translation, although fine by HTML / Qt rich text): i18n("

Some sentence." "

Another sentence."); // Good: i18n("

Some sentence.

" "

Another sentence.

"); ~~~ Well-formedness is good because the most frequent error in translation in presence of markup is mistyping (or miscopying) a tag. If the original text is well-formed, a translation checker tool can require the same of translation, and signal when that is not so. The previous example of non-well-formedness was perhaps trivial; in practice, non-trivial examples usually break some other rules too (e.g. no word puzzles). ### Writing Good Contexts The message context, given as first argument in `*i18nc` calls, is of great help to translators. Unfortunately, to a programmer it is not always clear when a context is needed, or what it should state. So, the very first rule of writing good contexts is to *listen to the translators asking for contexts*. When taking suggestions from translators, there is no need to worry if the proposed context will be sufficient for "all" languages. It is fine to simply add the information that a translator into particular language requested, and wait for translators into other languages to maybe request some other context information as well. Having said this, some apriori guidelines on contexts can be followed. Since in English the form of an adjective does not change based on the gender of the noun it modifies, properly translating messages which are single standalone adjectives will be impossible in many languages without a context. So, in general, every message which is a standalone adjective should have context: ~~~ i18nc("new file", "New"); i18nc("default action", "Default"); ~~~ Lists of related items typically benefit from having the same context, since they should all be translated in the same style: ~~~ i18nc("IPv4 configuration method", "Automatic (VPN)"); i18nc("IPv4 configuration method", "Automatic (VPN) addresses only"); i18nc("IPv4 configuration method", "Automatic (PPP)"); i18nc("IPv4 configuration method", "Automatic (PPP) addresses only"); ... ~~~ When there are placeholders in the text for which it is not clear, from the text alone, what kind of argument they represent, this should be explained in the context: ~~~ i18nc("%1 old file path, %2 new file path", "Cannot move '%1' to '%2'.", oldPath, newPath); i18nc("%1 track URL, %2 artist name", "%1 (by %2)", trackUrl, artistName); ~~~ It is frequently suggested to state in the context the grammar category of the message text, such as "this is a verb" or "this is a noun". Since the grammar category of the translation does not have to be the same as that of the original, this kind of context provides circumstantial information at best (see the section \ref uimark_ctxt for what translators may use it to draw some real information about), and is worthless at worst. Also, due to relative absence of declension in English grammar, different programmers may have different opinion on the grammar category: the menu title "View", is it a verb or a noun? #### User Interface Markers In the same way there exists a HIG (Human Interface Guidelines) document for the programmers to follow, translators should establish HIG-like convention for their language concerning the forms of UI text. Therefore, for a proper translation, the translator will need too know not only what does the message mean, but also where it figures in the UI. E.g. is the message a button label, a menu title, a tooltip, etc. To this end a convention has been developed among KDE translators, which programmers can use to succinctly describe UI usage of messages. In this convention, the context string starts with an *UI marker* of the form `@:`, and may be followed by any other usual context information, separated with a single space: ~~~ i18nc("@action:inmenu create new file", "New"); ~~~ The major and minor component of the UI marker are not arbitrary, but are drawn from the following table. For each component, the superscript states the Ki18n release when the component was introduced.
MajorMinorDescription
\@action5.0 Labels of clickable widgets which cause an action to be performed.
:button5.0 Push buttons in windows and dialogs.
:inmenu5.0 Menu entries that perform an action (as opposed e.g. to being checked).
:intoolbar5.0 Toolbar buttons.
\@title5.0 Text that is the title of a major UI element or a widget container.
:window5.0 Title of a window or a (dockable) view/pane.
:menu5.0 Menu title.
:tab5.0 Tab name.
:group5.0 Title to a group of widgets, like a group of checkboxes or radio buttons.
:column5.0 Column name in a table header, e.g. in a table view widget.
:row5.0 Row name in a table.
\@option5.0 Labels of option selection widgets, which can be enable/disabled or selected between.
:check5.0 Checkbox label, also a checkable menu entry.
:radio5.0 Radio button label.
\@label5.0 Various widget labels which are not covered by any of \@action, \@title, or \@option.
:slider5.0 Slider label.
:spinbox5.0 Spinbox label.
:listbox5.0 Label to a list box or combo box.
:textbox5.0 Label to a text box or text edit field.
:chooser5.0 Label to any special-purpose chooser widget, like color chooser, font chooser, etc.
\@item5.0 Strings that are items from a range of possibilities or properties of a given type.
:inmenu5.0 Item presented in menu (e.g. sort ordering, encoding name, etc).
:inlistbox5.0 Item presented in a list or combo box.
:intable5.0 Item presented in a table cell.
:inrange5.0 End range labels, e.g. on sliders.
:intext5.0 Words and short phrases which are inserted into a larger piece of text.
:valuesuffix5.46 Suffix appended to a value, including any spacing (e.g. in a spinbox).
\@info5.0 Any transient information for the user.
:tooltip5.0 Expanded formulation of the widget's label, usually appearing automatically when the pointer hovers over the widget.
:whatsthis5.0 Longer description of a widget's purpose and behavior, usually manually called up by the user.
:placeholder5.46 A hint what input is expected in an input field, shown in the place of the input where there is none yet.
:status5.0 A piece of text displayed in application's status view (e.g in the status bar).
:progress5.0 Text describing the current step or state of an operation, possibly periodically updating.
:usagetip5.0 A tip that comes up to inform the user about a certain possibility in a given context, e.g. a "tip of the day" on application startup.
Deprecated synonym: :tipoftheday.
:credit5.0 Contributor names and their contributions, e.g. in the about dialog.
:shell5.0 A note, warning or error sent to application's text output stream (stdout, stderr) rather than shown in the UI.
If none of the minor components apply to a given message, a major component can be used standalone. For example, this would happen with a library-provided list of items without any immediate UI context (e.g. language or country names), where the appropriate UI marker would be just `@item`. One way to extend the context after the UI marker, which is simple for the programmer yet can be very helpful for translators, is simply to add the text of the (technically or logically) parent widget. For example, if the action "New" is in the menu "File", then: ~~~ i18nc("@action:inmenu File", "New") ~~~ Or, if the item "Left" is found in the list box with the label "Vertical alignment": ~~~ i18nc("@item:inlistbox Vertical alignment", "Left") ~~~ #### Adding Contexts in Non-C++ files When Qt Designer is used to build the user interface, the \em -tr option of `uic` should be used to pass UI strings through Ki18n's `tr2i18n` function (see also \ref link_ui). This function is the equivalent of `i18n` or `i18nc`, based on whether the second argument is null or not. If a string in the `.ui` file has the attribute `comment=`, its value will be automatically used as the context argument. (In Qt Designer, this is the "disambiguation" property of a string.) Alternatively, strings can be passed to Ki18n's `tr2xi18n` function (see \ref kuit_markup). In KXmlGui (`.rc`) and KConfigXT (`.kcfg`) files, contexts can be added through `context=` attributes to `text`, `label`, and `whatsthis` tags. #### Disambiguation Context vs. Extracted Comment The GNU Gettext system actually defines *two* types of context for translators. The type discussed so far, the first argument of `*i18nc*` calls, is called *disambiguation context*. The other type of context is *extracted comment*. In Ki18n, this other type of context is written as a code comment, in the line just preceding the message text, and starting with *i18n:* keyword: ~~~ // i18n: This is a short text containing all letter of the alphabet, // e.g. for testing fonts. Translate with a sentence which can // serve the same purpose in your language. i18n("The quick brown fox jumps over the lazy dog"); ~~~ There are two main differences between disambiguation contexts and extracted comments. The first difference is that extracted comments *do not separate messages* in the translation catalog. For example, such two messages equipped with extracted comments: ~~~ // i18n: new file QString msg1 = i18n("New"); // i18n: new folder QString msg2 = i18n("New"); ~~~ will show up in the translation catalog as a single message with aggregate comments: ~~~ #. i18n: new file #. i18n: new folder msgid "New" msgstr "" ~~~ The same two messages equipped with disambiguation contexts: ~~~ QString msg1 = i18nc("new file", "New"); QString msg2 = i18nc("new folder", "New"); ~~~ will show up in the translation catalog as two messages: ~~~ msgctxt "new file" msgid "New" msgstr "" msgctxt "new folder" msgid "New" msgstr "" ~~~ The second difference is that a change in extracted comment *does not invalidate the existing translation*, i.e. it will not force translators to revisit the message and revise the translation (see the section \ref handle_update for details on how this invalidation happens with disambiguation contexts). Thus, for example, if there is a "message freeze" before the next release of a piece of software, during which programmers must not modify messages so that translators can thoroughly complete their work, it is allowed to modify the extracted comment, but it is not allowed to modify the disambiguation context. The Gettext manual suggests to use extracted comments as the default way of providing context for translators, and to use disambiguation contexts only when message separation is necessary. However, we (the people in the KDE community) suggest the opposite -- to use disambiguation context by default, and extracted comments only in special cases. This because there are two dangers associated with extracted comments: one is that programmer may fail to properly judge when two messages should be made separate for translation (and having to judge that all the time is a burden in the first place), and the other is that when the context change is such that translators really should revisit the message, they would not get any automatic signal about that. The message freeze advantage of extracted comments has not been observed to be very important. One special case when to an use extracted comment is when the context is a multi-sentence text explaining the purpose of the message, and the context is unlikely to change (in its meaning). Another case is when the context lists a fixed set of possible translations ("meta-messages", by which translators influence some aspect of text formatting), which may expand in the future, as new possibilities are introduced at request of translators into new languages. ### Extraction-Only Macros Sometimes it is convenient only to mark a message for extraction (into the catalog template, as described in \ref handle_extract), and to place the actual `i18n` call somewhere else. A typical case of this are global static initializers, where only POD types can be safely used. For this purpose `I18N*_NOOP` macros are provided. The `I18N_NOOP` macro is the counterpart to `*i18n` calls, and it is used like this: ~~~ typedef struct { const char *description; const char *regExp; } term; // Inert I18N_NOOP macros here... static const term items[] = { {I18N_NOOP("any character"), "."}, {I18N_NOOP("start of line"), "^"}, {I18N_NOOP("end of line"), "$"}, {I18N_NOOP("repeats, zero or more times"), "*"}, ... }; ... void populatePatternMenu (QMenu *menu) { for (uint i = 0; i < sizeof(items) / sizeof(items[0]); i++) { menu->addAction(new RegExpAction(menu, // ...actual i18n call here. i18n(items[i].description), items[i].regExp)); } } ~~~ The `I18NC_NOOP` macro is the counterpart to `*i18nc` calls: ~~~ typedef struct { const char *description, *abbrev; } unitDef; static const unitDef units[] = { {I18N_NOOP2_NOSTRIP("unit for 2^10 bytes", "KiB")}, {I18N_NOOP2_NOSTRIP("unit for 2^20 bytes", "MiB")}, ... } ... QString unitAbbrev = i18nc(units[i].description, units[i].abbrev); ~~~ There are also two deprecated macros: `I18N_NOOP2_NOSTRIP` is simply the old name of `I18NC_NOOP`; `I18N_NOOP2` takes the context argument but discards it, which means that the context must be repeated verbatim in the corresponding `i18nc` call. In general, `I18N*_NOOP` macros make it harder to follow i18n in the code, and should be avoided when possible. ## Connecting Calls to Catalogs Every `i18n` call must look for translations in exactly one translation catalog for a given language of translation. For this purpose, a group of catalogs which have the same source text but translations into different languages, is identified by a unique canonical name, called the *domain*. Therefore, every `i18n` call must be connected to a domain. This connection is established differently for applications and libraries, though the difference is only for convenience: if desired, the more verbose library method can be used for application code as well. ### Connecting to Catalogs in Application Code All `*i18n*` calls in an application can be connected to a single domain by calling the static `KLocalizedString::setApplicationDomain` method with the domain as the argument: ~~~ #include ... int main (int argc, char *argv[]) { ... KLocalizedString::setApplicationDomain("fooapp"); ... } ~~~ This call must be made in the code before any `i18n` call takes place, and right after creating the instance of `QCoreApplication` or one of its subclasses. `ki18n` calls can still be made before, but the respective `KLocalizedString::toString()` has to be delayed to after that. This is all there is to connecting calls and catalogs application's C++ source files. However, there may also be some non-code files that need connecting, and how to do this is some typical non-code files is described in the section \ref link_noncode. ### Connecting to Catalogs in Library Code `i18n` calls in libraries must be strictly connected to library's own translation domain no matter how the library is used, and this should be fully transparent to the library's client. In particular, if the client does not use Ki18n for internationalization of its own messages, library translation must still work as expected. Therefore, in library code, the call-domain connection is established in this way: ~~~ #define TRANSLATION_DOMAIN "foolib" #include ... void some_library_function () { ... QString msg = i18n("Greetings from Foolib!"); ... } ~~~ The definition of `TRANSLATION_DOMAIN` triggers the domain-specialization macro in `klocalizedstring.h`. It routes all `*i18n*` calls to their `*i18nd*` counterparts, which take the domain as their first argument. The `i18n` call from this example will thus expand into: ~~~ QString msg = i18nd("foolib", "Greetings from Foolib!"); ~~~ It is possible to use `*i18nd*` calls explicitly, but there should be no need for that. If there are any messages that should draw translations from a special domain, it is better style-wise to use the `ki18n("...").toString(domain)` construct. Definition of `TRANSLATION_DOMAIN` can be put into a private header file of the library, so that it does not have to be repeated at multiple locations. If there are some `i18n` calls in a *public* header file, definition of `TRANSLATION_DOMAIN` would propagate into and affect the application client code that uses Ki18n too. This is prevented by adding the following lines somewhere after the last `i18n` call in the public header: ~~~ #undef TRANSLATION_DOMAIN #include ~~~ This will undefine all expansions of `*i18n*` into `*i18nd*`, leaving the client's environment clean. If instead the public header contains only `I18N_NOOP*` macros, defining `TRANSLATION_DOMAIN` is unnecessary in the first place, since actual `i18n` calls happen somewhere else. ### Connecting to Catalogs in Non-Code Files Both KDE applications and libraries can include some non-code files which contain messages that need to be connected to a translation domain. This can be the same domain where messages from C++ code are found, or another domain, whatever seems more appropriate. In principle, each type of non-code file requires its own connection mechanism, and here it is explained how this works for typical types of non-code files found in KDE sources. It is assumed in the following that all messages in the non-code file are connected to the single domain. In other words, the connection is specified on the file level rather than on the message level. #### Qt Designer (.ui) files First, to have UI strings from `.ui` file passed through Ki18n, `uic` is run with `-tr tr2i18n`. This will replace all native Qt `tr` calls with Ki18n's `tr2i18n` calls in the resulting header file. Then, the generated header file needs to be post-processed to fix empty messages and include `klocalizedstring.h`. At this point, the `TRANSLATION_DOMAIN` can be defined just like in static C++ files. If CMake is used as the build system, a macro that performs all of the above is provided (`ki18n_wrap_ui`). Otherwise, one could use a shell snippet such as this: ~~~ domain=fooapp uifile=fooconfpage.ui uihfile=$uifile.h uic -tr tr2i18n $uifile -o $uihfile -sed -i 's/tr2i18n("")/QString::null/g' $uihfile -sed -i 's/tr2i18n("", "")/QString::null/g' $uihfile +sed -i 's/tr2i18n("")/QString()/g' $uihfile +sed -i 's/tr2i18n("", "")/QString()/g' $uihfile sed -i "1i\#define TRANSLATION_DOMAIN \"$domain\"\n#include " $uihfile ~~~ If strings contain KUIT markup (section \ref kuit_markup), `tr2i18n` in the lines above should be replaced with `tr2xi18n`. #### KXmlGui (.rc) files Since `.rc` files are interpreted at runtime, the translation domain connection is established simply by adding the `translationDomain` attribute to the top element: ~~~ ... ~~~ If the `.rc` file belongs to application rather than library source, it is not necessary to set `translationDomain`. If not set, translations will be looked up in the domain set with `KLocalizedString::setApplicationDomain` call in the code. If strings contain KUIT markup (section \ref kuit_markup), additionally the attribute `translationMarkup="true"` should be set. #### KConfigXT (.kcfg) files Instructions for building the configuration code from a `.kcfg` file are contained in the `.kcfgc` file of the same base name; `kconfig_compiler` is invoked with both files as arguments. Then, the domain connection is established simply by adding the `TranslationSystem` and `TranslationDomain` fields in the `.kcfgc` file, to select Ki18n as the translation system and the appropriate translation domain: ~~~ File=foolib.kcfg ... TranslationSystem=kde TranslationDomain=foolib ~~~ If the `.kcfg` file is part of an application rather than a library, the `TranslationDomain` field can be omitted in order to have messages looked up in the domain set by `KLocalizedString::setApplicationDomain` call in the code. If strings contain KUIT markup (section \ref kuit_markup), additionaly the field `TranslationMarkup=true` should be set. ## Handling Catalog Files For translators to start working, one or more translation catalog files should be prepared, based on the `i18n` calls in the source code. The procedure to do this is called *extraction* of messages. Extraction produces empty catalog files, called *templates*. These files are in the PO format, and have `.pot` extension. Section \ref handle_extract explains how to perform extraction. Once templates are ready, a translators make copies of them, with `.po` extension, and start filling them out with translations into respective languages. When translation is done, the translated catalog is committed into the source code repository. The build system is set up to install translated catalogs. Section \ref handle_install provides necessary steps for this. After some development has passed, the source repository will contain many translated catalogs which are out of date with respect to latest catalog templates. Of course, translators do not have to start translating from scratch, but there are specialized tools to carry over as much of existing translation as possible, so that only new and modified texts need to be considered. Section \ref handle_update shows how this is done. A usual application or a library has one translation catalog, but there can be more if there is higher modularity of the source. The following subsections refer to a single catalog wherever the extension to case with multiple catalogs is obvious, and mention multiple catalogs only where necessary. ### Extracting Templates The primary tool for collecting texts from `i18n` calls and writing out the catalog template is `xgettext`, from the official Gettext tools package. `xgettext` supports many programming languages and sublanguage environments, among which naturally C++ and Ki18n specifically. The extraction process from source code files is thus simple: `xgettext` runs with appropriate options over all files, and it writes out the catalog template. For the moment masking the complete list of options as `$EXTOPTS`, `xgettext` can be run for example like this at the top of Fooapp source to create the catalog template `fooapp.pot`: ~~~ find -name \*.cpp -o -name \*.h -o -name \*.qml | sort \ | xargs xgettext $EXTOPTS -o fooapp.pot ~~~ Or, a list of source files that should be extracted from can be assembled separately and fed to `xgettext:` ~~~ # ...create sources.list... xgettext $EXTOPTS -f sources.list -o fooapp.pot ~~~ One may want to assemble the list of source files by hand or semi-automatically in order to prioritize the order of translation (messages from most important files appearing first in the catalog), to exclude some portions of the source tree from extraction, and so on. `$EXTOPTS` that cover everything from Ki18n, and some generalities, should look like this: ~~~ --c++ --kde \ --from-code=UTF-8 \ -c i18n \ -ki18n:1 -ki18nc:1c,2 -ki18np:1,2 -ki18ncp:1c,2,3 \ -kki18n:1 -kki18nc:1c,2 -kki18np:1,2 -kki18ncp:1c,2,3 \ -kI18N_NOOP:1 -kI18NC_NOOP:1c,2 \ --copyright-holder= \ --msgid-bugs-address= ~~~ `--c++ --kde` options tell `xgettext` that source files are C++ with Ki18n. `--from-code=UTF-8` specifies the encoding of source files to be UTF-8, which must be so for Ki18n. `-c i18n` states that comments for extraction start with given keyword (`// i18n: ...`). The series of `-k` options informs `xgettext` of all possible translation call names and which of their arguments to extract. Finally, options `--copyright-holder` and `--msgid-bugs-address` automatically write the corresponding information into the catalog at proper place. If there are semantic markup calls in the code (section \ref kuit_markup), the following `-k` options should be added as well: ~~~ -kxi18n:1 -kxi18nc:1c,2 -kxi18np:1,2 -kxi18ncp:1c,2,3 \ -kkxi18n:1 -kkxi18nc:1c,2 -kkxi18np:1,2 -kkxi18ncp:1c,2,3 \ ~~~ `xgettext` unfortunately cannot be directly used to extract messages from the usual XML files appearing in Qt and KDE sources -- Designer (`.ui`), KXmlGui (`.rc`) and KConfigXT (`.kcfg`) files. Therefore the `kdesdk` package provides the `extractrc` script, which extracts XML messages as dummy `i18n` calls into a dummy C++ file, This file can then be included into the list of files for `xgettext` run. The usual invocation of `extractrc` is: ~~~ find -name \*.ui -o -name \*.rc -o -name \*.kcfg | sort \ | extractrc > rc.cpp # ...run xgettext with rc.cpp included in source files... rm rc.cpp ~~~ If the catalog being extracted is an application catalog, i.e. given as `KLocalizedString::setApplicationDomain` in the code, it should contain two meta-messages for translation credits which will be shown by `KAboutApplicationDialog`. These messages are also written as dummy `i18n` calls, usually into the same dummy C++ file with XML messages, with the following context and text: ~~~ echo 'i18nc("NAME OF TRANSLATORS", "Your names");' >> rc.cpp echo 'i18nc("EMAIL OF TRANSLATORS", "Your emails");' >> rc.cpp ~~~ The extraction command sequence can be written down as a small script, to be run periodically by the maintainer, or it can be integrated into the build system. For the code residing in the official KDE repositories a special form of the extraction script is mandated. This enables automatic overnight template extraction and feeding into dedicated translation section of KDE repositories. Details can be found at KDE Techbase. ### Placing and Installing Catalogs For an application or a library which uses a single catalog, the usual organization of catalogs in the source tree is this: ~~~ fooapp/ src/ doc/ po/ fooapp.pot aa.po bb.po cc.po ... ~~~ Here translated catalog files are named by their language codes (`aa`, `bb`, `cc`...). In case of multiple catalogs, one directory per catalog can be created under the `po/` directory: ~~~ fooapp/ src/ lib doc/ po/ fooapp/ fooapp.pot aa.po bb.po ... foolib/ foolib.pot aa.po bb.po ... ~~~ An alternative organization is to have one directory per language, and name catalog files by the translation domain. In multiple catalog situation this would look like: ~~~ fooapp/ src/ lib doc/ po/ templates/ fooapp.pot foolib.pot aa/ fooapp.po foolib.po bb/ fooapp.po foolib.po ... ~~~ Catalog templates are fully derived files, and therefore some maintainers do not like to keep them inside the repository. In that case, at least the tarball should contain the templates (i.e. they should be generated at packaging time), so that translators have somewhere to get them from. Another possibility is to upload the template to a *translation hub* (such as Transifex), which translators can use to upload translated catalogs back, and usually for some other features as well (assignment, review, etc). If the code resides in an official KDE repository, neither templates nor translated catalogs are kept inside the source tree. Instead, translated catalogs are fetched from an appropriate place when tarball is made, using a script provided for that purpose. Details can be found at KDE Techbase. No matter how the catalog files are named and organized inside the distribution tarball, they must be installed in exactly one way. The base name of the installed catalog must be their translation domain, and if the package is installed into `$PREFIX`, the installed directory tree must look like as follows: ~~~ $PREFIX/ share/ locales/ aa/ LC_MESSAGES/ fooapp.mo foolib.mo bb/ LC_MESSAGES/ fooapp.mo foolib.mo ... ~~~ Given that these directories are shared with other packages in the same prefix, by Gettext convention translation domains must be unique (like package names are). MO files are the compiled version of PO files, and they are produced using Gettext's `msgfmt` command: ~~~ msgfmt $SRCDIR/po/fooapp/aa.po -o $BUILDDIR/mo/aa/fooapp.mo ~~~ Compilation and installation of catalogs should naturally be integrated into the build system. In case CMake is used, KDE provides CMake macros for this purpose. #### Placing and Installing Scripting Modules Since Ki18n provides a run-time scripting capability for translators, some translators may also write the scripting module corresponding to the catalog. A scripting module is a directory named like the translation domain, and at least one JavaScript file inside, also with the same base name as the translation domain. Scripting modules can be placed like this in the source tree: ~~~ fooapp/ po/ fooapp.pot aa.po aa/ fooapp.js ... bb.po ... ~~~ or in the per-language directory variant: ~~~ fooapp/ po/ templates/ fooapp.pot aa/ fooapp.po fooapp/ fooapp.js ... bb/ fooapp.po ... ~~~ The installation location for scripting modules is like that for catalogs, only using `LC_SCRIPTS/` directory instead of `LC_MESSAGES/`: ~~~ $PREFIX/ share/ locales/ aa/ LC_SCRIPTS/ fooapp/ fooapp.js ... ~~~ When a translator inquires about adding a scripting module, or sends one in, the maintainer should check with the translator if perhaps the functions provided by the module are more widely applicable. If that is the case, they should rather become part of Ki18n's own scripting module, because then they will be accessible to all Ki18n-based translations in the given language. ### Updating Catalogs When new catalog template is extracted after some development has been done, existing translation should be updated against it. This is called *merging* with template, and it is performed by Gettext's `msgmerge` command. There are some merging options that can be examined here, but generally the best invocation of `msgmerge` is this: ~~~ msgmerge --update --backup=none --previous aa.po fooapp.pot ~~~ Options `--update --backup=none` mean to update the catalog in place, and not to make a backup file. Option `--previous` puts some additional information into every modified message, that translation editing tools can use to show to the translator all changes in the text. This command should be run once for every existing translation catalog. One thing to keep in mind is that a change in the context string of a message in the code (i.e. the first argument to `*i18nc*` calls), including adding or removing one, will also register as a modified message in the merged catalog. This will require that translators revisit it, which is exactly as intended: if the context has changed, especially if it was added, some changes in translation may be needed. However, this means that when a "message freeze" is declared so that translators can complete updating translations without disruption, contexts fall under same rules as text. There are a few possibilities for who and when should perform merging. For example, the maintainer can write a script that at the same time extracts the template and merges all catalogs, and run it periodically, committing updated catalogs to the repository for translators to pick up. This could even be integrated into the build system. Some maintainers do not like committing automatic changes, and instead expect translators to run the extraction-merging script for the language they maintain, update the translation, and commit only that updated catalog. This solution is cleaner with respect to repository history, but it may burden translators. When operating in an official KDE repository, maintainers do not have to deal with merging at all. The server-side automation which automatically extracts templates and provides them to translators, also performs merging. So the maintainer is left only to pick up whatever are the latest catalogs when making a tarball. ## Semantic Markup When composing user-interface text, some programmers ponder about the typographical conventions to use in certain contexts. For example, when a file name is inserted into the text, some typographical solutions that can be used are: ~~~ i18n("Cannot open %1 for reading.", filePath); i18n("Cannot open '%1' for reading.", filePath); i18n("Cannot open \"%1\" for reading.", filePath); ~~~ For the Qt widgets that have rich text capability, exposed as subset of HTML tags, additional solutions include: ~~~ i18n("Cannot open %1 for reading.", filePath); i18n("Cannot open %1 for reading.", filePath); i18n("Cannot open %1 for reading.", filePath); ~~~ The problem here is not so much to decide on one solution, as it is to follow it consistently through time and between contributors. One may also want to use two solutions, one in places where only plain text is allowed, and another where rich text is available. Wouldn't it then be easier to write everywhere: ~~~ xi18n("Cannot open %1 for reading.", filePath); ~~~ and have it automatically resolve into plain or rich text according to the UI context, using formatting patterns defined at one place? This approach is called *semantic* markup, because the author marks parts of the text according to what they *represent*. Ki18n implements such a semantic markup, called KUIT (KDE User Interface Text). It is accessed through the series of `xi18n*` and `kxi18n*` calls, which are the KUIT-aware counterparts of `i18n*` and `ki18n*` calls. Ordinary and KUIT-aware calls can be freely mixed within a given body of code. KUIT defines a number of semantic tags that are frequently of use, as listed in the section \ref kuit_tags. But, KUIT also allows the programmer to define custom tags, as well as to change visual formatting patterns for predefined tags. This capability should lessen one important issue of semantic markups: when the author is forced to choose between several tags none of which exactly fits the desired meaning; with KUIT, the author can simply define a custom tag in that case. ### Defining Tags Tags are defined and redefined per translation domain, so that changes will not affect markup resolution in any other domain. Changes are performed through the `KuitSetup` object associated with the domain, as returned by the `Kuit::setupForDomain` method. A tag is defined (or redefined) by defining (or redefining) its formatting patterns, with one call to `KuitSetup::setTagPattern` for each desired combination of tag name, attribute names, and visual format. Here is an example of defining the tag ``, which has an optional attribute `color=`, on the domain `foogame`: ~~~ KuitSetup *ks = Kuit::setupForDomain("foogame"); QString tagName; QStringList attribNames; tagName = "player"; attribNames.clear() ks->setTagPattern(tagName, attribNames, Kuit::PlainText, ki18nc("tag-format-pattern plain", "'%1'")); ks->setTagPattern(tagName, attribNames, Kuit::RichText, ki18nc("tag-format-pattern rich", "%1")); attribNames.append("color"); ks->setTagPattern(tagName, attribNames, Kuit::RichText, ki18nc("tag-format-pattern rich", "%1")); ~~~ The first two `setTagPattern` calls set up resolution of `` without attributes, into plain and rich text. The third call sets up resolution for ``, but only into rich text; since a plain text pattern is not defined for this tag-attribute combination, it will fall back to basic `` plain text pattern. A fallback is always defined, the elementary fallback being a no-op, where tag is simply removed. Formatting patterns must be wrapped for translation too, since translators may need to tweak them; *ordinary* (not markup-aware) `ki18nc` calls must be used here, since patterns themselves are not KUIT markup. The `%1` placeholder in the pattern will be replaced by the text wrapped with the tag, and `%2` and upwards with attribute values, in the order of appearance in attribute names list. If a simple substitution pattern is insufficient for formatting, additionally a formatting function of type `Kuit::TagFormatter` can be given. The result of this function is substituted into the pattern; alternatively an empty pattern can be given (as `KLocalizedString()`), in which case the result is used directly, no substitution is performed. The formatting function also receives the current element path, so that the resolution can depend on the markup tree context if needed. Anything in the function that may need translator input should be appropriately exposed through `i18nc*` or `ki18nc*` calls. In the section \ref kuit_tags it is stated that every KUIT tag is classified either as a phrase tag or as a structuring tag, and explained what that means for processing. A newly defined tag is by default a phrase tag; method `KuitSetup::setTagClass` can be used to change its class: ~~~ tagName = "list2"; ks->setTagPattern(tagName, ...); ks->setTagClass(tagName, Kuit::StructTag); ~~~ In a library, changes to the KUIT setup may need to be private, applicable only in library's own domain, but they may also need to be public, applicable in clients' domains. For changes that should be public, the library should define a public function which takes the domain as the argument and performs all the changes on that domain: ~~~ void updateKuitSetup (const char *domain) { KuitSetup *ks = Kuit::setupForDomain(domain); .... } ~~~ The client code should then call this function in its initialization. ### Selecting Visual Format The target visual format for any given `xi18n` call can be selected in two ways. The primary way is by UI markers in the message context, which were described in the section \ref uimark_ctxt. Every `@:` marker combination has a default target visual format assigned, as follows:
UI Marker Visual Format
(none) plain
\@action:\ plain
\@title:\ plain
\@option:\ plain
\@label:\ plain
\@item:\ plain
\@info, \@info:tooltip, \@info:whatsthis, \@info:usagetip rich
\@info:status, \@info:progress, \@info:credit plain
\@info:shell term
Target visual formats associated with UI markers can be changed using the `KUITSetup::setFormatForMarker` method: ~~~ KuitSetup *ks = Kuit::setupForDomain("fooapp"); // Set standalone @info (no minor component) to plain text: ks->setFormatForMarker("@info", Kuit::PlainText); // Set @info:tooltip to rich text: ks->setFormatForMarker("@info:tooltip", Kuit::RichText); // Set all @info: to plain text: ks->setFormatForMarker("@info:", Kuit::PlainText); ~~~ The second way to select the visual format is by using a `kxi18n*` call, and passing the format type to the `toString` method: ~~~ kxi18nc("@info", "Logging paused.").toString(Kuit::PlainText); ~~~ This will override any format implied by the UI marker if present. If a library is making modifications in visual format association with UI markers, and these changes should be available to clients, the same approach as in the section \ref kuit_def_tags should be used. ### Escaping While for `*i18n*` calls it was advised to keep each message text well-formed by itself with respect to Qt rich text markup, for `*xi18n*` calls well-formedness is mandatory. This means that markup-significant characters in plain-looking text need to be escaped, using standard XML entities: ~~~ xi18n("Installed Fooapp too old, need release >= 2.1.8."); xi18n("Set <themeId> as theme on startup"); ~~~ The exception is the ampersand (&) character, which in XML denotes the start of an entity, but in Qt denotes the accelerator marker. Therefore it is necessary to escape ampersand as `&` only when it is in position which would result in valid entity syntax: ~~~ // Escaping not needed because not in entity-like position: xi18n("Remove &all entries"); // Escaping not needed for the same reason wrt. markup, // but ampersand doubled to escape it wrt. Qt accelerator marker: xi18n("Look && Feel"); // Escaping wrt. markup necessary: xi18n("Delete &everything; see if I care!"); ~~~ The example for necessary escaping above is rather artificial, because in practice it is unlikely for ampersand to appear in entity-like position while not actually starting an entity. To assure the validity of markup when arguments are inserted into `xi18n`-wrapped text, all markup-significant characters in string arguments are automatically escaped. For example, this works as expected: ~~~ QString filePath("assignment03-.txt"); QString msg1 = kxi18n("Delete %1?", filePath) .toString(Kuit::PlainText); // msg1 == "Delete 'assignment03-.txt'?" QString msg2 = kxi18n("Delete %1?", filePath) .toString(Kuit::RichText); // msg2 == "Delete `assignment03-<yourname>.txt`?" ~~~ But, how then to compose a text where the arguments too should contain some KUIT markup? This is done by using non-finalization `kxi18n*` call to translate the argument text, and passing the returned `KLocalizedString` object directly as argument: ~~~ KLocalizedString stateDesc = kxi18n( "On indefinite hold."); QString msg = xi18nc("@info", "Task state:" "%1", stateDesc); // msg == "

Task state:

" // "

On indefinite hold.

" ~~~ If the argument and the text have different visual formats implied by their UI markers, the outermost format overrides inner formats. ### Predefined Tags All KUIT tags belong to one of the two classes: - phrase tags, which describe parts of sentences or whole sentences inserted into running text; - structuring tags, which split text into paragraph-level blocks. A text without any structuring tags is considered equivalent of one paragraph or sub-paragraph sentence or phrase. If at least one structuring tag appears in the text, then the text is considered multi-paragraph, and no content may appear outside of structuring tags. For example: ~~~ // Good: i18nc("@info", "You can configure the history sidebar here."); // BAD: i18nc("@info", "History Sidebar" "You can configure the history sidebar here."); // Good: i18nc("@info", "History Sidebar" "You can configure the history sidebar here."); ~~~ The current set of predefined tags is presented below. For each tag the following information is stated: the tag name (in superscript: Ki18n release of first appearance), available attributes (in superscript: \em * if mandatory, Ki18n release of first appearance), admissible subtags, and description.
Phrase Tags
\5.0
Name of an application. ~~~ i18nc("@action:inmenu", "Open with %1", appName); ~~~
\5.0
Line-breaking body of code, for short code or output listings. ~~~ i18nc("@info:whatsthis", "You can try the following snippet:" "\\begin{equation}\n" " C_{x_i} = \\frac{C_z^2}{e \\pi \\lambda}\n" "\\end{equation}\n" ""); ~~~
\5.0
Attributes: section=5.0
Name of a shell command, system call, signal, etc. Its man section can be given with the `section=` attribute. ~~~ i18nc("@info", "This will call %1 internally.", cmdName); i18nc("@info", "Consult the man entry of " "%1", cmdName); ~~~
\5.0
Attributes: address=5.0
Email address. Without attributes, the tag text is the address. If the address is explicitly given with the `address=` attribute, the tag text is the name or description attached to the address. In rich text, the phrase will be hyperlinked. ~~~ i18nc("@info", "Send bug reports to %1.", emailNull); i18nc("@info", "Send praises to the author.", emailMy); ~~~
\5.0
Attributes: strong=5.0
Emphasized word or phrase in the text. For strong emphasis, attribute `strong=` can be set to `[1|true|yes]`.
\5.0
Environment variable. A `$`-sign will be prepended automatically in formatted text. ~~~ i18nc("@info", "Assure that PATH is properly set."); ~~~
\5.0
Subtags: \, \
File or folder name or path. Slash (/) should be used as path separator, and it will be converted into native separator for the underlying platform. ~~~ i18nc("@info", "Cannot read %1.", filePath); i18nc("@info", "HOME/.foorc " "does not exist."); ~~~
\5.0
Subtags: \, \
Inline code, like a shell command line. ~~~ i18nc("@info:tooltip", "Execute svn merge on selected revisions."); ~~~
\5.0
Path to a graphical user interface element. If a path of UI elements is needed, elements should be separated with `|` or `->`, which will be converted into the canonical separator. ~~~ i18nc("@info:whatsthis", "If you make a mistake, click " "Reset to start again."); i18nc("@info:whatsthis", "The line colors can be changed under " "Settings->Visuals."); ~~~
\5.0
Attributes: url=5.0
Link to a URL-addressable resource. Without attributes, the tag text is the URL; alternatively, the URL can be given by `url=` attribute, and then the text serves as description. Separate URL and description are preferred if applicable. The phrase will be hyperlinked in rich text. ~~~ i18nc("@info:tooltip", "Go to %1 website.", urlKDE); i18nc("@info:tooltip", "Go to the KDE website.", urlKDE); ~~~
\5.0
Subtags: all phrase tags
An external message inserted into the text. ~~~ i18nc("@info", "The fortune cookie says: %1", cookieText); ~~~
\5.0
Line break. ~~~ i18nc("@info", "The server replied:" "%1", serverReply); ~~~
\5.0
Attributes: label=5.0
Subtags: all phrase tags
The sentence is a side note related to the topic. Prefix "Note:" will be added automatically; another prefix can be set with attribute `label=`. ~~~ i18nc("@info", "Probably the best known of all duck species is the Mallard. " "It breeds throughout the temperate areas around the world. " "Most domestic ducks are derived from Mallard."); ~~~
\5.0
A placeholder text. It could be something which the user should replace with actual text, or a generic item in a list. ~~~ i18nc("@info", "Replace name with your name."); i18nc("@item:inlistbox", "All images"); ~~~
\5.0
Combination of keyboard keys to press. Key names should be separated by "+" or "-", and the shortcut will be converted into canonical form. ~~~ i18nc("@info:whatsthis", "Cycle through layouts using Alt+Space."); ~~~
\5.0
Attributes: label=5.0
Subtags: all phrase tags
The sentence is a warning. Prefix "Warning:" will be added automatically; another prefix can be set with attribute `label=`. ~~~ i18nc("@info", "Really delete this key? " "This cannot be undone."); ~~~
Structuring Tags
\5.0
Subtags: all phrase tags
A list item.
\5.0
Subtags: \
List of items. List is considered an element of the paragraph, so `` tags must be inside `` tags.
\5.0
Subtags: all phrase tags, \
One paragraph of text.
\5.0
Subtags: all phrase tags
The subtitle of the text. Must come after ``. </tr></td> <tr><td> <b>\<title\></b><sup>5.0</sup><br/> <i>Subtags:</i> all phrase tags<br/> The title of the text. Must be the first tag in the text if present. </tr></td> </table> The criteria for adding new tags to the predefined set, particularly new phrase tags, are not very strict. If the tag is clearly useful to a class of applications, of which more than one are known to use Ki18n, it is reasonable to add it here. Adding synonymous tag names is also fine, where one finds that the original name is not sufficiently discoverable, or that it is too verbose for the given frequency of use. <a name="kuit_ents"> ### Predefined Entities KUIT defines a fixed set of XML entities, which means that unlike tags, entities cannot be added to, nor their character expansions changed. The standard XML entities are: <table> <tr><th>Entity</th><th>Expansion</th></tr> <tr><td><b>\<</b></td><td>less-than (`<`)</td></tr> <tr><td><b>\></b></td><td>greater-than (`>`)</td></tr> <tr><td><b>\&</b></td><td>ampersand (`&`)</td></tr> <tr><td><b>\'</b></td><td>single quote (`'`)</td></tr> <tr><td><b>\"</b></td><td>double quote (`"`)</td></tr> </table> The `&apos;` and `&quot;` are really needed only within attribute values (and even there they can be avoided by choosing the opposite quote sign for quoting the attribute value). Additional entities are (Ki18n release where they were introduced given in superscript): <table> <tr><th>Entity</th><th>Expansion</th></tr> <tr> <td><b>\ </b><sup>5.0</sup></td> <td></td>non-breaking space (` `) </tr> </table> The reason for not allowing custom entities can be demonstrated by the following example. An application programmer may think of defining the entity `&appname;`, which would be used everywhere in text in place of the actual application name. In that way, seemingly, it would be easy to play with various names or spellings without disrupting translations. The problem, however, is that in many languages the structure of the sentence depends on the grammar properties of the particular name (e.g. its grammar gender or number), and conversely, the name may need modification according to sentence structure (e.g. by grammar case). Thus, custom entities are not allowed because they are misused too easily. If something *really* needs to be inserted verbatim into text, argument substitution is always at hand. <a name="non_text"> ## Localizing Non-Text Resources It sometimes happens that a non-textual application resource needs localization. The most frequent example are images that contain some text, like splash screens. Ki18n also provides a rudimentary facility for this situation, the `KLocalizedString::localizedFilePath` static method. When called with a resource file path as the argument, this method will check what are the active languages, and look if there exists a localized version of the resource at path `<original-parent-dir>/l10n/<language>/<original-basename>`. For example, if the active language is `aa`, and a candidate image for localization is installed as: ~~~ $PREFIX/share/fooapp/splash.png ~~~ then a call to ~~~ QString splashPath = QStandardPaths::locate( QStandardPaths::GenericDataLocation, "splash.png"); splashPath = KLocalizedString::localizedFilePath(splashPath); ~~~ will check if there exist the file ~~~ $PREFIX/share/fooapp/l10n/aa/splash.png ~~~ and return that path if it does, or else the original path. Some KDE libraries will call `KLocalizedString::localizedFilePath` on their own behind the scene, for resources that may need localization but whose paths are not directly manipulated in application sources. An example here are icons handled through `KIcon` class, which are referred to in the code only by the icon name. <a name="refs"> ## Further References For details about the format of translation catalogs (PO) and various Gettext tools, the first stop is the <a href="http://www.gnu.org/software/gettext/manual/gettext.html"> Gettext manual</a>. <a href="http://techbase.kde.org/">KDE Techbase</a> contains a <a href="http://techbase.kde.org/Development/Tutorials/Localization"> series of tutorials</a> on preparing the KDE code for localization, and on the internationalization process in general.