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 bool	isApplicationTranslatedInto (const QString &language)

static QStringList	languages ()

static QString	localizedFilePath (const QString &filePath)

static QString	removeAcceleratorMarker (const QString &label)

static void	setApplicationDomain (const QByteArray &domain)

static void	setLanguages (const QStringList &languages)

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 44 of file klocalizedstring.h.

Constructor & Destructor Documentation

◆ KLocalizedString() [1/2]

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

Definition at line 368 of file klocalizedstring.cpp.

◆ KLocalizedString() [2/2]

KLocalizedString::KLocalizedString ( const KLocalizedString & rhs )

Copy constructor.

Definition at line 389 of file klocalizedstring.cpp.

◆ ~KLocalizedString()

KLocalizedString::~KLocalizedString ( )

Destructor.

Definition at line 402 of file klocalizedstring.cpp.

Member Function Documentation

◆ addDomainLocaleDir()

void KLocalizedString::addDomainLocaleDir	(	const QByteArray &	domain,
		const QString &	path )

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 1387 of file klocalizedstring.cpp.

◆ applicationDomain()

QByteArray KLocalizedString::applicationDomain ( )

static

Get the application's main translation domain.

Returns the domain set by setApplicationDomain.

Definition at line 1215 of file klocalizedstring.cpp.

◆ availableApplicationTranslations()

QSet< QString > KLocalizedString::availableApplicationTranslations ( )

static

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 1254 of file klocalizedstring.cpp.

◆ availableDomainTranslations()

QSet< QString > KLocalizedString::availableDomainTranslations ( const QByteArray & domain )

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

See also: setApplicationDomain; availableApplicationTranslations

Definition at line 1259 of file klocalizedstring.cpp.

◆ clearLanguages()

void KLocalizedString::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 1238 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 1194 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 1180 of file klocalizedstring.cpp.

◆ isApplicationTranslatedInto()

bool KLocalizedString::isApplicationTranslatedInto ( const QString & language )

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 for language exits, false otherwise

See also: setApplicationDomain

Definition at line 1247 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 407 of file klocalizedstring.cpp.

◆ languages()

QStringList KLocalizedString::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 1222 of file klocalizedstring.cpp.

◆ localizedFilePath()

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

Definition at line 1356 of file klocalizedstring.cpp.

◆ operator=()

KLocalizedString & KLocalizedString::operator= ( const KLocalizedString & rhs )

Assignment operator.

Definition at line 394 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 1187 of file klocalizedstring.cpp.

◆ removeAcceleratorMarker()

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

Definition at line 1382 of file klocalizedstring.cpp.

◆ setApplicationDomain()

void KLocalizedString::setApplicationDomain ( const QByteArray & domain )

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 1206 of file klocalizedstring.cpp.

◆ setLanguages()

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; languages

Definition at line 1229 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 1166 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 1156 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 1138 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 1084 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 1102 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 1146 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 1120 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 1129 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 1093 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 1111 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 479 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 484 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 489 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 494 of file klocalizedstring.cpp.

◆ untranslatedText()

QByteArray KLocalizedString::untranslatedText ( ) const

Returns the untranslated text.

Since: 5.64

Definition at line 1201 of file klocalizedstring.cpp.

◆ 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 1070 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 1077 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 1063 of file klocalizedstring.cpp.

The documentation for this class was generated from the following files:

KDE's Doxygen guidelines are available online.

Class Picker

Quick Links

About KI18n

KLocalizedString

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ KLocalizedString() [1/2]

◆ KLocalizedString() [2/2]

◆ ~KLocalizedString()

Member Function Documentation

◆ addDomainLocaleDir()

◆ applicationDomain()

◆ availableApplicationTranslations()

◆ availableDomainTranslations()

◆ clearLanguages()

◆ ignoreMarkup()

◆ inContext()

◆ isApplicationTranslatedInto()

◆ isEmpty()

◆ languages()

◆ localizedFilePath()

◆ operator=()

◆ relaxSubs()

◆ removeAcceleratorMarker()

◆ setApplicationDomain()

◆ setLanguages()

◆ subs() [1/10]

◆ subs() [2/10]

◆ subs() [3/10]

◆ subs() [4/10]

◆ subs() [5/10]

◆ subs() [6/10]

◆ subs() [7/10]

◆ subs() [8/10]

◆ subs() [9/10]

◆ subs() [10/10]

◆ toString() [1/4]

◆ toString() [2/4]

◆ toString() [3/4]

◆ toString() [4/4]

◆ untranslatedText()

◆ withDomain()

◆ withFormat()

◆ withLanguages()