class KLocalizedString |
|
|
klocalizedstring.h I18N_NOOP marks a string to be translated without translating it. Do not use this unless you know you need it. #q2.11.2 Example usage where say_something() returns either "hello" or "goodbye": (void) I18N_NOOP("hello"); (void) I18N_NOOP("goodbye"); ... mystring = i18n(say_something());If the string is too ambiguous to be translated well to a non-english language, use this instead of I18N_NOOP to separate lookup string and english. Example usage where say_something() returns either "hello" or "goodbye": (void) I18N_NOOP2("greeting", "hello"); (void) I18N_NOOP2("greeting", "goodbye"); ... mystring = i18nc("greeting", say_something());You need to call i18nc(context, stringVar) later on, not just i18n(stringVar). Class for producing and handling localized messages KLocalizedString handles translation and specific needs of argument substitution and formatting in localized message strings. Topics: - gen_usage - spec_usage - subs_notes - other_ref General Usage This class should mostly not be used directly, but through wrapper i18n calls which return QString, for localization of user visible messages in applications. For the most frequent message type, the one without any arguments, you would use simply: QString msg = i18n("Just plain info"); If there are arguments to be substitued into the message, you just add them after the message string: QString msg = i18n("%1 has scored %2", playerName, score);There can be up to some final number of arguments added like this (i18n is realized by overloaded templates). If you overrun this number, use ki18n* series of calls (described below). You can use several types as arguments, see subs methods. Sometimes a short message can be ambiguous in English, then you would use the context version, i18nc. There the first string is context, and the second is the message which really gets displayed: QString msg = i18nc("Player name - score", "%1 - %2", playerName, score); While English diferentiates plural forms only between 1 and else, in other languages it might not be that simple, or it might be simpler. To handle this properly, use plural call, i18np: QString msg = i18np("One image in album %2", "%1 images in album %2", numImages, albumName);Note that the plural form shall be decided by first integer-valued argument, (numImages in the example above). In rare cases when there are two integer arguments, you should take care to order them properly. Finally, message might need both context and plural, which is provided by i18ncp call: QString msg = i18ncp("Personal file", "One file", "%1 files", numFiles); Be carefull not to use literal string as first argument after message text in basic i18n() call. In debug mode, it will even trigger the static assert, giving error at compile time. This is in order to prevent misnamed calls: it may happen that you add context or plural to previously basic message, but forget to change the name of the call. Specialized Usage There are some situations where i18n* calls are not sufficient or convenient. For one, if you need to substitute many arguments. Or, if you find that you need to defer the substitution. For this you can use the ki18n call which returns a KLocalizedString, substitute arguments using its subs methods, and finalize the translation by calling its toString method. 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(); Another case is when you want extra formatting of arguments, like field width or number of decimals. subs methods can take these formatting parameters. In particular, you should never use some custom way to format arguments, as subs methods will also properly localize them: QString s = i18n("Rounds: %1", myNumberFormat(n, 8)); // bad, number not localized QString s = ki18n("Rounds: %1").subs(n, 8).toString(); // good, number localized There are also context, plural and context-plural variants: QString s = ki18nc("No function", "None").toString(); QString s = ki18np("File found", "%1 files found").subs(n).toString(); QString s = ki18ncp("Personal file", "One file", "%1 files").subs(n).toString(); If you need translation using locale (ie. KLocale object) other than the default, you can use overloaded toString method which takes pointer to a locale: KLocale *myLocale; ... ki18n("Welcome").toString(myLocale); Placeholder Substitution Hopefully, for the most part placeholders are being substituted the way you would intuitively expect them to be. Nevertheless:
Further References KDE Techbase contains a series of tutorials on preparing the code for localization (and on internationalization process in general), where the intended patterns of usage of i18n API are covered in great detail. All i18n'd messages, whether sent to widgets expecting plain text or allowing Qt rich text (HTML), support the new KDE semantic markup for user interface text, KUIT in short. Semantic markup both increases the consistency of visual presentation for the end user, and provides extra information to translators, so that translations can be of higher quality. KUIT is documented in an Techbase article as well.
See also KLocale
Author Chusslove Illich \ |
|
Constructs an empty message, which is not valid for finalization. Usefull when you later need to assign KLocalizedString obtained by one of ki18n* calls. See also isEmpty() |
|
Copy constructor. |
|
|
Checks whether the message is empty. This will happen if you just constructed the object via default constructor. Empty messages are not valid for finalization; if you use toString() on them, you will get error mark instead of empty QString (in debug mode). Returns true if the message is empty, else false |
|
Internal Called from KLocale on addition or removal of catalogs. |
|
Substitutes an int argument into the message.
a - the argument fieldWidth - width of the formatted field, padded by spaces. Positive value aligns right, negative aligns left base - the radix used to represent the number as a string. Valid values range from 2 to 36 fillChar - the character used to fill up the empty places when field width is greater than argument width Returns resultant KLocalizedString |
|
Substitutes a double argument into the message.
a - the argument fieldWidth - width of the formatted field, padded by spaces. Positive value aligns right, negative aligns left format - type of floating point formating, like in QString.arg precision - number of digits after the decimal separator fillChar - the character used to fill up the empty places when field width is greater than argument width Returns resultant KLocalizedString |
|
Substitutes a QChar argument into the message.
a - the argument fieldWidth - width of the formatted field, padded by spaces. Positive value aligns right, negative aligns left fillChar - the character used to fill up the empty places when field width is greater than argument width Returns resultant KLocalizedString |
|
Substitutes a QString argument into the message.
a - the argument fieldWidth - width of the formatted field, padded by spaces. Positive value aligns right, negative aligns left fillChar - the character used to fill up the empty places when field width is greater than argument width Returns resultant KLocalizedString |
|
Finalizes the translation, creates QString with placeholders substituted. Translations is obtained from default locale. If there was any mismatch between placeholders and arguments returned string will contain error marks (in debug mode). Returns finalized translation |
|
Finalizes the translation, creates QString with placeholders substituted. Translations is obtained from given locale. If locale is 0, original message is used instead of translated. If there was any mismatch between placeholders and arguments returned string will contain error marks (in debug mode).
locale - locale from which translations are to be taken Returns finalized translation |