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, const QChar &fillChar=QLatin1Char(' ')) const
KLocalizedString	subs (uint a, int fieldWidth=0, int base=10, const QChar &fillChar=QLatin1Char(' ')) const
KLocalizedString	subs (long a, int fieldWidth=0, int base=10, const QChar &fillChar=QLatin1Char(' ')) const
KLocalizedString	subs (ulong a, int fieldWidth=0, int base=10, const QChar &fillChar=QLatin1Char(' ')) const
KLocalizedString	subs (qlonglong a, int fieldWidth=0, int base=10, const QChar &fillChar=QLatin1Char(' ')) const
KLocalizedString	subs (qulonglong a, int fieldWidth=0, int base=10, const QChar &fillChar=QLatin1Char(' ')) const
KLocalizedString	subs (double a, int fieldWidth=0, char format= 'g', int precision=-1, const QChar &fillChar=QLatin1Char(' ')) const
KLocalizedString	subs (QChar a, int fieldWidth=0, const QChar &fillChar=QLatin1Char(' ')) const
KLocalizedString	subs (const QString &a, int fieldWidth=0, const QChar &fillChar=QLatin1Char(' ')) const
KLocalizedString	subs (const KLocalizedString &a, int fieldWidth=0, const QChar &fillChar=QLatin1Char(' ')) const
KLocalizedString	relaxSubs () const
KLocalizedString	inContext (const QString &key, const QString &text) const

Static Public Member Functions
static void	setApplicationCatalog (const QString &domain)
static void	setLanguages (const QStringList &languages)
static void	clearLanguages ()
static bool	isApplicationTranslatedInto (const QString &language)
static QString	localizedFilePath (const QString &filePath)
static QString	removeAcceleratorMarker (const QString &label)
static QString	translateQt (const char context, const char text, const char *comment, int n)
static void	insertQtCatalog (const QString &domain)
static void	removeQtCatalog (const QString &domain)

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 ( const KLocalizedString & rhs )

Copy constructor.

KLocalizedString::~KLocalizedString ( )

Destructor.

Member Function Documentation

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

Assignment operator.

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

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

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

KLocalizedString KLocalizedString::withLocale ( const KLocale * locale ) const

Indicate to look for translation based on given locale.

Parameters

locale the locale for which translations are made

Returns: updated KLocalizedString

KLocalizedString KLocalizedString::withDomain ( const QString & domain ) const

Indicate to look for translation in the given catalog.

Parameters

domain the canonical name of the catalog

Returns: updated KLocalizedString

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

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`,
		const 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`,
		const 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`,
		const 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`,
		const 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`,
		const 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`,
		const 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`,
		const 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`,
		const 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`,
		const 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

KLocalizedString KLocalizedString::subs	(	const KLocalizedString &	a,
		int	fieldWidth = `0`,
		const 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

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

KLocalizedString KLocalizedString::inContext	(	const QString &	key,
		const QString &	text
	)		const

Add dynamic context to the message.

See Dynamic Contexts for use cases.

Parameters

key	context key
text	context value

Returns: updated KLocalizedString

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

Add another catalog to search for Qt translations.

Parameters

domain the canonical name of the catalog to add

See Also: translateQt; removeQtCatalog

Deprecated:

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

KLocalizedString KI18N_EXPORT ki18n ( const char * text )

friend

Create non-finalized translated string.

Parameters

text	string to translate

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

KLocalizedString KI18N_EXPORT ki18nd	(	const char *	domain,
		const char *	text
	)

friend

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

KLocalizedString KI18N_EXPORT kxi18n ( const char * text )

friend

Create non-finalized markup-aware translated string.

Parameters

text	string to translate

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:

klocalizedstring.h

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation