KLocalizedString
#include <KLocalizedString>
Public Member Functions | |
KLocalizedString () | |
KLocalizedString (const KLocalizedString &rhs) | |
~KLocalizedString () | |
KLocalizedString | ignoreMarkup () const |
KLocalizedString | inContext (const QString &key, const QString &value) const |
bool | isEmpty () const |
KLocalizedString & | operator= (const KLocalizedString &rhs) |
KLocalizedString | relaxSubs () const |
KLocalizedString | subs (const KLocalizedString &a, int fieldWidth=0, QChar fillChar=QLatin1Char(' ')) const |
KLocalizedString | subs (const QString &a, int fieldWidth=0, QChar fillChar=QLatin1Char(' ')) const |
KLocalizedString | subs (double a, int fieldWidth=0, char format='g', int precision=-1, QChar fillChar=QLatin1Char(' ')) const |
KLocalizedString | subs (int 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 (QChar a, int fieldWidth=0, 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 (uint 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 |
QString | toString () const |
QString | toString (const char *domain) const |
QString | toString (const QStringList &languages) const |
QString | toString (Kuit::VisualFormat format) const |
QByteArray | untranslatedText () const |
KLocalizedString | withDomain (const char *domain) const |
KLocalizedString | withFormat (Kuit::VisualFormat format) const |
KLocalizedString | withLanguages (const QStringList &languages) const |
Static Public Member Functions | |
static void | addDomainLocaleDir (const QByteArray &domain, const QString &path) |
static QByteArray | applicationDomain () |
static QSet< QString > | availableApplicationTranslations () |
static QSet< QString > | availableDomainTranslations (const QByteArray &domain) |
static void | clearLanguages () |
static void | insertQtDomain (const char *domain) |
static bool | isApplicationTranslatedInto (const QString &language) |
static QStringList | languages () |
static QString | localizedFilePath (const QString &filePath) |
static QString | removeAcceleratorMarker (const QString &label) |
static void | removeQtDomain (const char *domain) |
static void | setApplicationDomain (const char *domain) |
static void | setLanguages (const QStringList &languages) |
static QString | translateQt (const char *context, const char *text, const char *comment, int n) |
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.
For detailed information on how to use KI18n functions please refer to Programmer's Guide.
Definition at line 98 of file klocalizedstring.h.
Constructor & Destructor Documentation
◆ KLocalizedString() [1/2]
|
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
Definition at line 345 of file klocalizedstring.cpp.
◆ KLocalizedString() [2/2]
KLocalizedString::KLocalizedString | ( | const KLocalizedString & | rhs | ) |
Copy constructor.
Definition at line 366 of file klocalizedstring.cpp.
◆ ~KLocalizedString()
|
default |
Destructor.
Member Function Documentation
◆ addDomainLocaleDir()
|
static |
Load locales for a domain from a specific location This is useful for resources which have their translation files outside of the usual $XDG_DATA_DIRS/locales location.
- Parameters
-
the domain to load resources from \path the full file path to the locale directory
Definition at line 1462 of file klocalizedstring.cpp.
◆ applicationDomain()
|
static |
Get the application's main translation domain.
Returns the domain set by setApplicationDomain
.
Definition at line 1199 of file klocalizedstring.cpp.
◆ availableApplicationTranslations()
- Since
- 5.0
Get the languages for which there exists the translation catalog file for the set application translation domain.
The application domain is set by setApplicationDomain
. If the application domain was not set, empty set is returned. If the application domain was set, the language set will always contain at least the source code language (en_US
).
- Returns
- set of language codes for existing translation catalogs
- See also
- setApplicationDomain
Definition at line 1238 of file klocalizedstring.cpp.
◆ availableDomainTranslations()
|
static |
- Since
- 5.0
Get the languages for which a translation catalog file for the passed translation domain exists.
If the translation domain was not specified in the domain parameter an empty set is returned.
If the application domain was set, the language set will always contain at least the source code language (en_US
).
- Parameters
-
domain query for translations of a specific domain, if an empty QByteArray is passed, an empty set will be returned
- Returns
- set of language codes for existing translation catalogs
Definition at line 1243 of file klocalizedstring.cpp.
◆ clearLanguages()
|
static |
Clear override languages.
This clears the override languages, going back to those provided by the locale.
- See also
- setLanguages
- languages
Definition at line 1222 of file klocalizedstring.cpp.
◆ ignoreMarkup()
KLocalizedString KLocalizedString::ignoreMarkup | ( | ) | const |
Do not resolve KUIT markup.
If the message is markup-aware (constructed by one of *xi18n*
calls), this function can be used to make it non-markup-aware. This may be useful for debugging markup.
- Returns
- updated
KLocalizedString
Definition at line 1178 of file klocalizedstring.cpp.
◆ inContext()
KLocalizedString KLocalizedString::inContext | ( | const QString & | key, |
const QString & | value | ||
) | const |
Add dynamic context to the message.
See dyn_ctxt for use cases.
- Parameters
-
key context key value context value
- Returns
- updated
KLocalizedString
Definition at line 1164 of file klocalizedstring.cpp.
◆ insertQtDomain()
|
static |
Add another domain to search for Qt translations.
- Parameters
-
domain the translation domain to add
- See also
- translateQt
- removeQtDomain
- Deprecated:
- Since 5.0
Definition at line 1429 of file klocalizedstring.cpp.
◆ isApplicationTranslatedInto()
|
static |
Check whether the translation catalog file in the given language for the set application translation domain exists.
- Parameters
-
language the language code to check
- Returns
true
if the translation catalog forlanguage
exits,false
otherwise
- See also
- setApplicationDomain
Definition at line 1231 of file klocalizedstring.cpp.
◆ isEmpty()
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
Definition at line 381 of file klocalizedstring.cpp.
◆ languages()
|
static |
Get the languages for which translations will be made.
Returned languages are ordered with decreasing priority.
- Returns
- languages ordered list of language codes
- See also
- setLanguages
- clearLanguages
- Since
- 5.20.0
Definition at line 1206 of file klocalizedstring.cpp.
◆ localizedFilePath()
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
Definition at line 1332 of file klocalizedstring.cpp.
◆ operator=()
KLocalizedString & KLocalizedString::operator= | ( | const KLocalizedString & | rhs | ) |
Assignment operator.
Definition at line 371 of file klocalizedstring.cpp.
◆ relaxSubs()
KLocalizedString KLocalizedString::relaxSubs | ( | ) | const |
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
Definition at line 1171 of file klocalizedstring.cpp.
◆ removeAcceleratorMarker()
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
Definition at line 1358 of file klocalizedstring.cpp.
◆ removeQtDomain()
|
static |
Remove a domain from Qt translation lookup.
To really remove the domain, this function must be invoked at least as many times as insertQtDomain
was invoked to add this domain. This makes it safe to always use paired insertion/removal calls, without pulling out a domain underneath an unrelated piece of code that uses it as well.
- Parameters
-
domain the translation domain to remove
- See also
- translateQt
- insertQtDomain
- Deprecated:
- Since 5.0
Definition at line 1448 of file klocalizedstring.cpp.
◆ setApplicationDomain()
|
static |
Set the given domain as application's main domain.
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.
This function should be called right after creating the instance of QCoreApplication or one of its subclasses. At that time the locale setup has been made, including what is hooked into the QCoreApplication startup, like KXMLGUI's language switching support. So the initialisation done by this function sees all the data it should.
- Parameters
-
domain the translation domain of the application
Definition at line 1190 of file klocalizedstring.cpp.
◆ setLanguages()
|
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
- languages
Definition at line 1213 of file klocalizedstring.cpp.
◆ subs() [1/10]
KLocalizedString KLocalizedString::subs | ( | const KLocalizedString & | a, |
int | fieldWidth = 0 , |
||
QChar | fillChar = QLatin1Char(' ') |
||
) | const |
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
Definition at line 1150 of file klocalizedstring.cpp.
◆ subs() [2/10]
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
Definition at line 1140 of file klocalizedstring.cpp.
◆ subs() [3/10]
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 formatting, 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
Definition at line 1122 of file klocalizedstring.cpp.
◆ subs() [4/10]
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
Definition at line 1068 of file klocalizedstring.cpp.
◆ subs() [5/10]
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
Definition at line 1086 of file klocalizedstring.cpp.
◆ subs() [6/10]
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
Definition at line 1130 of file klocalizedstring.cpp.
◆ subs() [7/10]
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
Definition at line 1104 of file klocalizedstring.cpp.
◆ subs() [8/10]
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
Definition at line 1113 of file klocalizedstring.cpp.
◆ subs() [9/10]
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
Definition at line 1077 of file klocalizedstring.cpp.
◆ subs() [10/10]
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
Definition at line 1095 of file klocalizedstring.cpp.
◆ toString() [1/4]
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
Definition at line 453 of file klocalizedstring.cpp.
◆ toString() [2/4]
QString KLocalizedString::toString | ( | const char * | domain | ) | const |
Like toString
, but look for translation in the given domain.
Given domain overrides any set earlier using withDomain
.
- Parameters
-
domain the translation domain
- Returns
- finalized translation
Definition at line 458 of file klocalizedstring.cpp.
◆ toString() [3/4]
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
Definition at line 463 of file klocalizedstring.cpp.
◆ toString() [4/4]
QString KLocalizedString::toString | ( | Kuit::VisualFormat | format | ) | const |
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
Definition at line 468 of file klocalizedstring.cpp.
◆ translateQt()
|
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 of given domain. All domains added with insertQtDomain
are checked 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
andlconvert
commands.
Definition at line 1364 of file klocalizedstring.cpp.
◆ untranslatedText()
QByteArray KLocalizedString::untranslatedText | ( | ) | const |
◆ withDomain()
KLocalizedString KLocalizedString::withDomain | ( | const char * | domain | ) | const |
Indicate to look for translation in the given domain.
- Parameters
-
domain the translation domain
- Returns
- updated
KLocalizedString
Definition at line 1054 of file klocalizedstring.cpp.
◆ withFormat()
KLocalizedString KLocalizedString::withFormat | ( | Kuit::VisualFormat | format | ) | const |
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
Definition at line 1061 of file klocalizedstring.cpp.
◆ withLanguages()
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
Definition at line 1047 of file klocalizedstring.cpp.
The documentation for this class was generated from the following files:
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon May 8 2023 04:01:19 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006
KDE's Doxygen guidelines are available online.