Class for producing and handling localized messages.
More...
#include <klocalizedstring.h>
Public Member Functions |
| KLocalizedString () |
| KLocalizedString (const KLocalizedString &rhs) |
KLocalizedString & | operator= (const KLocalizedString &rhs) |
| ~KLocalizedString () |
QString | toString () const |
QString | toString (const QStringList &languages) const |
QString | toString (const QString &domain) const |
QString | toString (KUIT::VisualFormat format) const |
KLocalizedString | withLanguages (const QStringList &languages) const |
KLocalizedString | withLocale (const KLocale *locale) const |
KLocalizedString | withDomain (const QString &domain) const |
KLocalizedString | withFormat (KUIT::VisualFormat format) const |
bool | isEmpty () const |
KLocalizedString | subs (int a, int fieldWidth=0, int base=10, QChar fillChar=QLatin1Char(' ')) const |
KLocalizedString | subs (uint a, int fieldWidth=0, int base=10, QChar fillChar=QLatin1Char(' ')) const |
KLocalizedString | subs (long a, int fieldWidth=0, int base=10, QChar fillChar=QLatin1Char(' ')) const |
KLocalizedString | subs (ulong a, int fieldWidth=0, int base=10, QChar fillChar=QLatin1Char(' ')) const |
KLocalizedString | subs (qlonglong a, int fieldWidth=0, int base=10, QChar fillChar=QLatin1Char(' ')) const |
KLocalizedString | subs (qulonglong a, int fieldWidth=0, int base=10, QChar fillChar=QLatin1Char(' ')) const |
KLocalizedString | subs (double a, int fieldWidth=0, char format= 'g', int precision=-1, QChar fillChar=QLatin1Char(' ')) const |
KLocalizedString | subs (QChar a, int fieldWidth=0, QChar fillChar=QLatin1Char(' ')) const |
KLocalizedString | subs (const QString &a, int fieldWidth=0, QChar fillChar=QLatin1Char(' ')) const |
KLocalizedString | subs (const KLocalizedString &a, int fieldWidth=0, QChar fillChar=QLatin1Char(' ')) const |
KLocalizedString | relaxSubs () const |
KLocalizedString | inContext (const QString &key, const QString &text) const |
Friends |
KLocalizedString KI18N_EXPORT | ki18n (const char *text) |
KLocalizedString KI18N_EXPORT | ki18nc (const char *context, const char *text) |
KLocalizedString KI18N_EXPORT | ki18np (const char *singular, const char *plural) |
KLocalizedString KI18N_EXPORT | ki18ncp (const char *context, const char *singular, const char *plural) |
KLocalizedString KI18N_EXPORT | ki18nd (const char *domain, const char *text) |
KLocalizedString KI18N_EXPORT | ki18ndc (const char *domain, const char *context, const char *text) |
KLocalizedString KI18N_EXPORT | ki18ndp (const char *domain, const char *singular, const char *plural) |
KLocalizedString KI18N_EXPORT | ki18ndcp (const char *domain, const char *context, const char *singular, const char *plural) |
KLocalizedString KI18N_EXPORT | kxi18n (const char *text) |
KLocalizedString KI18N_EXPORT | kxi18nc (const char *context, const char *text) |
KLocalizedString KI18N_EXPORT | kxi18np (const char *singular, const char *plural) |
KLocalizedString KI18N_EXPORT | kxi18ncp (const char *context, const char *singular, const char *plural) |
KLocalizedString KI18N_EXPORT | kxi18nd (const char *domain, const char *text) |
KLocalizedString KI18N_EXPORT | kxi18ndc (const char *domain, const char *context, const char *text) |
KLocalizedString KI18N_EXPORT | kxi18ndp (const char *domain, const char *singular, const char *plural) |
KLocalizedString KI18N_EXPORT | kxi18ndcp (const char *domain, const char *context, const char *singular, const char *plural) |
Detailed Description
Class for producing and handling localized messages.
KLocalizedString
handles translation and argument substitution and formatting of user-visible text.
KLocalizedString
instances are usually not constructed directly, but through one of the wrapper *i18n*
calls.
Constructor & Destructor Documentation
KLocalizedString::KLocalizedString |
( |
| ) |
|
|
explicit |
Construct an empty message.
Direct construction is used when another KLocalizedString
instance, obtained by one of ki18n*
calls, should later be assigned to directly constructed instance. Before the assignment happens, directly constructed instance is not valid for finalization by toString
methods.
- See Also
- isEmpty
KLocalizedString::~KLocalizedString |
( |
| ) |
|
Member Function Documentation
QString KLocalizedString::toString |
( |
| ) |
const |
Finalize the translation.
Creates translated QString
, with placeholders substituted by arguments given by KLocalizedString::subs
methods. Translated text is searched for and arguments are formatted based on the global locale.
If there was any mismatch between placeholders and arguments, in debug mode the returned string may contain error marks.
- Returns
- finalized translation
QString KLocalizedString::toString |
( |
const QStringList & |
languages | ) |
const |
Like toString
, but look for translation only in given languages.
Given languages override languages defined by the global locale, and any languages set earlier using withLanguages
. If languages
is empty, original message is returned.
- Parameters
-
languages | list of language codes (by decreasing priority) |
- Returns
- finalized translation
QString KLocalizedString::toString |
( |
const QString & |
domain | ) |
const |
Like toString
, but look for translation in the given catalog.
Given catalog overrides any set earlier using withDomain
.
- Parameters
-
domain | the canonical name of the catalog |
- Returns
- finalized translation
Like toString
, but resolve KUIT markup into given visual format.
Given visual format overrides that implied by the context UI marker or set earlier using withFormat
. If the message is not markup-aware, this is same as toString
without arguments.
- Parameters
-
format | the target visual format |
- Returns
- finalized translation
KLocalizedString KLocalizedString::withLanguages |
( |
const QStringList & |
languages | ) |
const |
Indicate to look for translation only in given languages.
- Parameters
-
languages | list of language codes (by decreasing priority) |
- Returns
- updated
KLocalizedString
Indicate to look for translation based on given locale.
- Parameters
-
locale | the locale for which translations are made |
- Returns
- updated
KLocalizedString
Indicate to look for translation in the given catalog.
- Parameters
-
domain | the canonical name of the catalog |
- Returns
- updated
KLocalizedString
Indicate to resolve KUIT markup into given visual format.
If the message is not markup-aware, this has no effect.
- Parameters
-
format | the target visual format |
- Returns
- updated
KLocalizedString
bool KLocalizedString::isEmpty |
( |
| ) |
const |
Check whether the message is empty.
The message is considered empty if the object was constructed via the default constructor.
Empty messages are not valid for finalization. The behavior of calling toString
on them is undefined. In debug mode, an error mark may appear in the returned string.
- Returns
true
if the message is empty, false
otherwise
KLocalizedString KLocalizedString::subs |
( |
int |
a, |
|
|
int |
fieldWidth = 0 , |
|
|
int |
base = 10 , |
|
|
QChar |
fillChar = QLatin1Char(' ') |
|
) |
| const |
Substitute an int argument into the message.
- Parameters
-
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
- updated
KLocalizedString
KLocalizedString KLocalizedString::subs |
( |
uint |
a, |
|
|
int |
fieldWidth = 0 , |
|
|
int |
base = 10 , |
|
|
QChar |
fillChar = QLatin1Char(' ') |
|
) |
| const |
Substitute an unsigned int argument into the message.
- Parameters
-
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
- updated
KLocalizedString
KLocalizedString KLocalizedString::subs |
( |
long |
a, |
|
|
int |
fieldWidth = 0 , |
|
|
int |
base = 10 , |
|
|
QChar |
fillChar = QLatin1Char(' ') |
|
) |
| const |
Substitute a long argument into the message.
- Parameters
-
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
- updated
KLocalizedString
KLocalizedString KLocalizedString::subs |
( |
ulong |
a, |
|
|
int |
fieldWidth = 0 , |
|
|
int |
base = 10 , |
|
|
QChar |
fillChar = QLatin1Char(' ') |
|
) |
| const |
Substitute an unsigned long argument into the message.
- Parameters
-
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
- updated
KLocalizedString
KLocalizedString KLocalizedString::subs |
( |
qlonglong |
a, |
|
|
int |
fieldWidth = 0 , |
|
|
int |
base = 10 , |
|
|
QChar |
fillChar = QLatin1Char(' ') |
|
) |
| const |
Substitute a long long argument into the message.
- Parameters
-
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
- updated
KLocalizedString
KLocalizedString KLocalizedString::subs |
( |
qulonglong |
a, |
|
|
int |
fieldWidth = 0 , |
|
|
int |
base = 10 , |
|
|
QChar |
fillChar = QLatin1Char(' ') |
|
) |
| const |
Substitute an unsigned long long argument into the message.
- Parameters
-
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
- updated
KLocalizedString
KLocalizedString KLocalizedString::subs |
( |
double |
a, |
|
|
int |
fieldWidth = 0 , |
|
|
char |
format = 'g' , |
|
|
int |
precision = -1 , |
|
|
QChar |
fillChar = QLatin1Char(' ') |
|
) |
| const |
Substitute a double argument into the message.
- Parameters
-
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
- updated
KLocalizedString
KLocalizedString KLocalizedString::subs |
( |
QChar |
a, |
|
|
int |
fieldWidth = 0 , |
|
|
QChar |
fillChar = QLatin1Char(' ') |
|
) |
| const |
Substitute a QChar
argument into the message.
- Parameters
-
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
- updated
KLocalizedString
KLocalizedString KLocalizedString::subs |
( |
const QString & |
a, |
|
|
int |
fieldWidth = 0 , |
|
|
QChar |
fillChar = QLatin1Char(' ') |
|
) |
| const |
Substitute a QString
argument into the message.
- Parameters
-
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
- updated
KLocalizedString
Substitute another KLocalizedString
into the message.
- Parameters
-
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
- updated
KLocalizedString
Relax matching between placeholders and arguments.
Normally the placeholders should start from %1 and have no gaps, and on finalization there must be exactly as many arguments supplied through subs
methods as there are unique plaecholders. If this is not satisfied, in debug mode warnings are printed and the finalized string may contain error marks.
This method relaxes the placeholder-argument matching, such that there must only be an argument available for every present unique placeholder (taking placeholder numbers to be 1-based indices into the argument list). This can come useful in some situations.
- Returns
- updated
KLocalizedString
KLocalizedString KLocalizedString::inContext |
( |
const QString & |
key, |
|
|
const QString & |
text |
|
) |
| const |
static void KLocalizedString::setApplicationCatalog |
( |
const QString & |
domain | ) |
|
|
static |
Set the given catalog as application's main catalog.
This function must be called in applications, in order to have any translations at all. It should never be called in libraries. This allows to check whether the application is translated into a given language, so that if it is not, translations from underlying libraries will not appear even if they are translated. This prevents mixing of translated and untranslated text in the user interface.
- Parameters
-
domain | the canonical name of the application catalog |
- See Also
- insertCatalog
static void KLocalizedString::setLanguages |
( |
const QStringList & |
languages | ) |
|
|
static |
Set the languages for which translations will be made.
This overrides the languages provided by the locale. Languages should be ordered with decreasing priority.
- Parameters
-
languages | ordered list of language codes |
- See Also
- setLocale
-
clearLanguages
static void KLocalizedString::clearLanguages |
( |
| ) |
|
|
static |
Clear override languages.
This clears the override languages, going back to those provided by the locale.
- See Also
- setLanguages
static bool KLocalizedString::isApplicationTranslatedInto |
( |
const QString & |
language | ) |
|
|
static |
Check whether the application catalog for the given language exists.
- Parameters
-
language | the language code to check |
- Returns
true
if the application catalog for language
exits, false
otherwise
- See Also
- setApplicationCatalog
static QString KLocalizedString::localizedFilePath |
( |
const QString & |
filePath | ) |
|
|
static |
Find a path to the localized file for the given original path.
This is intended mainly for non-text resources (images, sounds, etc). Text resources should be handled in more specific ways.
Possible localized paths are checked in turn by priority of set languages, in form of <dirname>/l10n/<lang>/<basename>
, where <dirname>
and <basename>
are those of the original path, and <lang>
is the language code.
- Parameters
-
filePath | path to the original file |
- Returns
- path to the localized file if found, original path otherwise
static QString KLocalizedString::removeAcceleratorMarker |
( |
const QString & |
label | ) |
|
|
static |
Remove accelerator marker from a UI text label.
Accelerator marker is not always a plain ampersand (&), so it is not enough to just remove it by QString::remove
. The label may contain escaped markers ("&&") which must be resolved and skipped, as well as CJK-style markers ("Foo (&F)") where the whole parenthesis construct should be removed. Therefore always use this function to remove accelerator marker from UI labels.
- Parameters
-
label | UI label which may contain an accelerator marker |
- Returns
- label without the accelerator marker
static QString KLocalizedString::translateQt |
( |
const char * |
context, |
|
|
const char * |
text, |
|
|
const char * |
comment, |
|
|
int |
n |
|
) |
| |
|
static |
Translate a message with Qt semantics.
This functions provides a capability to derive a Qt translator from QTranslator
and draw translations from PO catalogs. All catalogs added with insertQtCatalog
are looked through for translation, in undefined order. No Ki18n-specific processing is performed (formatting, scripting, etc).
- See Also
- QTranslator
- Deprecated:
- Use Qt's native i18n system, Qt Linguist, with roundtrip TS->PO->TS through Qt's
lupdate
and lconvert
commands.
static void KLocalizedString::insertQtCatalog |
( |
const QString & |
domain | ) |
|
|
static |
static void KLocalizedString::removeQtCatalog |
( |
const QString & |
domain | ) |
|
|
static |
Remove a catalog from Qt translation lookup.
To really remove the catalog, this function must be invoked at least as many times as insertQtCatalog
was invoked to add this catalog. This makes it safe to always use paired insertion/removal calls, without pulling out a catalog underneath an unrelated piece of code that uses it as well.
- Parameters
-
domain | the canonical name of the catalog to remove |
- See Also
- translateQt
-
insertQtCatalog
- Deprecated:
Friends And Related Function Documentation
Create non-finalized translated string.
- Parameters
-
- Returns
- non-finalized translated string
KLocalizedString KI18N_EXPORT ki18nc |
( |
const char * |
context, |
|
|
const char * |
text |
|
) |
| |
|
friend |
Create non-finalized translated string with context.
- Parameters
-
context | context of the string |
text | string to translate |
- Returns
- non-finalized translated string
KLocalizedString KI18N_EXPORT ki18np |
( |
const char * |
singular, |
|
|
const char * |
plural |
|
) |
| |
|
friend |
Create non-finalized translated string with plural.
- Parameters
-
singular | singular form of the string to translate |
plural | plural form of the string to translate |
- Returns
- non-finalized translated string
KLocalizedString KI18N_EXPORT ki18ncp |
( |
const char * |
context, |
|
|
const char * |
singular, |
|
|
const char * |
plural |
|
) |
| |
|
friend |
Create non-finalized translated string with context and plural.
- Parameters
-
context | context of the string |
singular | singular form of the string to translate |
plural | plural form of the string to translate |
- Returns
- non-finalized translated string
Create non-finalized translated string from domain.
- Parameters
-
domain | domain in which to look for translations |
text | string to translate |
- Returns
- non-finalized translated string
KLocalizedString KI18N_EXPORT ki18ndc |
( |
const char * |
domain, |
|
|
const char * |
context, |
|
|
const char * |
text |
|
) |
| |
|
friend |
Create non-finalized translated string from domain with context.
- Parameters
-
domain | domain in which to look for translations |
context | context of the string |
text | string to translate |
- Returns
- non-finalized translated string
KLocalizedString KI18N_EXPORT ki18ndp |
( |
const char * |
domain, |
|
|
const char * |
singular, |
|
|
const char * |
plural |
|
) |
| |
|
friend |
Create non-finalized translated string from domain with plural.
- Parameters
-
domain | domain in which to look for translations |
singular | singular form of the string to translate |
plural | plural form of the string to translate |
- Returns
- non-finalized translated string
KLocalizedString KI18N_EXPORT ki18ndcp |
( |
const char * |
domain, |
|
|
const char * |
context, |
|
|
const char * |
singular, |
|
|
const char * |
plural |
|
) |
| |
|
friend |
Create non-finalized translated string from domain with context and plural.
- Parameters
-
domain | domain in which to look for translations |
context | context of the string |
singular | singular form of the string to translate |
plural | plural form of the string to translate |
- Returns
- non-finalized translated string
Create non-finalized markup-aware translated string.
- Parameters
-
- Returns
- non-finalized translated string
KLocalizedString KI18N_EXPORT kxi18nc |
( |
const char * |
context, |
|
|
const char * |
text |
|
) |
| |
|
friend |
Create non-finalized markup-aware translated string with context.
- Parameters
-
context | context of the string |
text | string to translate |
- Returns
- non-finalized translated string
KLocalizedString KI18N_EXPORT kxi18np |
( |
const char * |
singular, |
|
|
const char * |
plural |
|
) |
| |
|
friend |
Create non-finalized markup-aware translated string with plural.
- Parameters
-
singular | singular form of the string to translate |
plural | plural form of the string to translate |
- Returns
- non-finalized translated string
KLocalizedString KI18N_EXPORT kxi18ncp |
( |
const char * |
context, |
|
|
const char * |
singular, |
|
|
const char * |
plural |
|
) |
| |
|
friend |
Create non-finalized KUIT markup aware translated string with context and plural.
- Parameters
-
context | context of the string |
singular | singular form of the string to translate |
plural | plural form of the string to translate |
- Returns
- non-finalized translated string
KLocalizedString KI18N_EXPORT kxi18nd |
( |
const char * |
domain, |
|
|
const char * |
text |
|
) |
| |
|
friend |
Create non-finalized markup-aware translated string from domain.
- Parameters
-
domain | domain in which to look for translations |
text | string to translate |
- Returns
- non-finalized translated string
KLocalizedString KI18N_EXPORT kxi18ndc |
( |
const char * |
domain, |
|
|
const char * |
context, |
|
|
const char * |
text |
|
) |
| |
|
friend |
Create non-finalized markup-aware translated string from domain with context.
- Parameters
-
domain | domain in which to look for translations |
context | context of the string |
text | string to translate |
- Returns
- non-finalized translated string
KLocalizedString KI18N_EXPORT kxi18ndp |
( |
const char * |
domain, |
|
|
const char * |
singular, |
|
|
const char * |
plural |
|
) |
| |
|
friend |
Create non-finalized markup-aware translated string from domain with plural.
- Parameters
-
domain | domain in which to look for translations |
singular | singular form of the string to translate |
plural | plural form of the string to translate |
- Returns
- non-finalized translated string
KLocalizedString KI18N_EXPORT kxi18ndcp |
( |
const char * |
domain, |
|
|
const char * |
context, |
|
|
const char * |
singular, |
|
|
const char * |
plural |
|
) |
| |
|
friend |
Create non-finalized markup-aware translated string from domain with context and plural.
- Parameters
-
domain | domain in which to look for translations |
context | context of the string |
singular | singular form of the string to translate |
plural | plural form of the string to translate |
- Returns
- non-finalized translated string
The documentation for this class was generated from the following file: