The QTranslator class provides internationalization support for text output. More...

Inheritance diagram for QTranslator:

Public Methods
	QTranslator (QObject *parent=nullptr)

	~QTranslator ()

virtual bool	isEmpty () const

bool	load (const QLocale &locale, const QString &filename, const QString &prefix=QString (), const QString &directory=QString (), const QString &suffix=QString ())

bool	load (const QString &filename, const QString &directory=QString (), const QString &search_delimiters=QString (), const QString &suffix=QString ())

bool	load (const uchar *data, int len, const QString &directory=QString ())

virtual QString	translate (const char context, const char text, const char *comment=nullptr, std::optional< int > numArg=std::optional< int >()) const

virtual QString	translate (const QString &context, const QString &text, const QString &comment=QString (), std::optional< int > numArg=std::optional< int >()) const

Public Methods inherited from QObject
	QObject (QObject *parent=nullptr)

	~QObject ()

bool	blockSignals (bool block)

const QList< QObject * > &	children () const

bool	connect (const QObject *sender, const QString &signalMethod, const QString &location, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

bool	connect (const QObject *sender, const QString &signalMethod, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

bool	disconnect (const QObject *receiver, const QString &slotMethod=QString ()) const

bool	disconnect (const QString &signalMethod, const QString &location, const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const

bool	disconnect (const QString &signalMethod=QString (), const QObject *receiver=nullptr, const QString &slotMethod=QString ()) const

void	dumpObjectInfo ()

void	dumpObjectTree ()

QList< QString >	dynamicPropertyNames () const

virtual bool	event (QEvent *event)

virtual bool	eventFilter (QObject watched, QEvent event)

template<typename T >
T	findChild (const QString &childName=QString ()) const

template<class T >
QList< T >	findChildren (const QRegularExpression &regExp, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

template<class T >
QList< T >	findChildren (const QString &childName=QString (), Qt::FindChildOptions options=Qt::FindChildrenRecursively) const

bool	inherits (const QString &className) const

void	installEventFilter (QObject *filterObj)

bool	isWidgetType () const

bool	isWindowType () const

void	killTimer (int id)

const QMetaObject *	metaObject () const

void	moveToThread (QThread *targetThread)

QString	objectName () const

QObject *	parent () const

template<class T = QVariant>
T	property (const QString &name) const

void	removeEventFilter (QObject *obj)

void	setObjectName (const QString &name)

void	setParent (QObject *parent)

bool	setProperty (const QString &name, const QVariant &value)

bool	signalsBlocked () const

int	startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)

QThread *	thread () const

Additional Inherited Members
Public Signals inherited from QObject
void	destroyed (QObject *obj=nullptr)

void	objectNameChanged (const QString &objectName)

Public Slots inherited from QObject
void	deleteLater ()

Static Public Methods inherited from QObject
static bool	connect (const QObject sender, const QMetaMethod &signalMethod, const QObject receiver, const QMetaMethod &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

static bool	connect (const QObject sender, const QString &signalMethod, const QObject receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection, const QString &location=QString ())

static bool	connect (const QObject sender, const QString &signalMethod, const QString &location, const QObject receiver, const QString &slotMethod, Qt::ConnectionType type=Qt::AutoConnection)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool	connect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver receiver, SlotReturn (SlotClass::slotMethod)(SlotArgs...), Qt::ConnectionType type=Qt::AutoConnection)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool	connect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, T slotLambda, Qt::ConnectionType type=Qt::AutoConnection)

static bool	disconnect (const QObject sender, const QMetaMethod &signalMethod, const QObject receiver, const QMetaMethod &slotMethod)

static bool	disconnect (const QObject sender, const QString &signalMethod, const QObject receiver, const QString &slotMethod)

static bool	disconnect (const QObject sender, const QString &signalMethod, const QString &location, const QObject receiver, const QString &slotMethod)

static bool	disconnect (const QObject sender, std::nullptr_t, const QObject receiver, std::nullptr_t)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class SlotClass , class... SlotArgs, class SlotReturn >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver receiver, SlotReturn (SlotClass::slotMethod)(SlotArgs...))

template<class Sender , class SignalClass , class... SignalArgs, class Receiver >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, std::nullptr_t slotMethod=nullptr)

template<class Sender , class SignalClass , class... SignalArgs, class Receiver , class T >
static bool	disconnect (const Sender sender, void (SignalClass::signalMethod)(SignalArgs...), const Receiver *receiver, T slotMethod)

static QMetaObject &	staticMetaObject ()

static QString	tr (const char text, const char comment=nullptr, std::optional< int > numArg=std::optional< int >())

Protected Methods inherited from QObject
virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const QMetaMethod &signalMethod) const

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const QMetaMethod &signalMethod) const

bool	isSignalConnected (const QMetaMethod &signalMethod) const

int	receivers (const QString &signal) const

QObject *	sender () const

int	senderSignalIndex () const

virtual void	timerEvent (QTimerEvent *event)

Properties inherited from QObject
	objectName

Related Functions inherited from QObject
T	qobject_cast (QObject *object)

	QObjectList

Detailed Description

The QTranslator class provides internationalization support for text output. The purpose of this class is to load an existing translation file. Once the file has been successfully loaded then QCoreApplication::installTranslator() is called so the tr() methods will have access to the translations.

A translation file (.qm) contains strings in some source language and the counter part in a target language. Translation files are created using the Linguist application.

The following is an example showing how to load and install a translation file. The call to installTranslator() must occur before the call to tr().

int main(int argc, char *argv[]) {
   QApplication app(argc, argv);
 
   QTranslator translator;
   translator.load("myapp_de");
 
   app.installTranslator(&translator);
 
   QPushButton exit_button(QPushButton::tr("Exit Program"));
 
   exit_button.show();
   return app.exec();
}

Translation Encoding

The input text string for this class must be encoded in UTF-8. If the string is using a different encoding you will need to call QString8::fromLatin1(), QString8::fromUtf16(), or use QTextCodec to convert to UTF-8 before calling translate().

Looking up Translations

A translation can be looked up directly using translate() when no translation file was installed.

Using Multiple Translations

Multiple translation files can be installed and they are accessed in the reverse order in which they were installed. The search for a given piece of text stops when a translation containing a match is found.

See also: QApplication::installTranslator(), QApplication::removeTranslator(), QObject::tr(), QApplication::translate()

Constructor & Destructor Documentation

QTranslator::QTranslator ( QObject * parent = nullptr )

explicit

Constructs an empty translation file with the given parent.

QTranslator::~QTranslator ( )

Destroys the object and frees any allocated resources.

Method Documentation

bool QTranslator::isEmpty ( ) const

virtual

Returns true if this translator is empty, otherwise returns false. This method works with stripped and unstripped translation files.

bool QTranslator::load	(	const QLocale &	locale,
		const QString &	filename,
		const QString &	prefix = `QString()`,
		const QString &	directory = `QString()`,
		const QString &	suffix = `QString()`
	)

Loads a translation file which must then be installed using QCoreApplication::installTranslator(). This method returns true if the translation is successfully loaded, otherwise it returns false. If a prior translation file was loaded for the given QTranslator it will be discarded before loading the new translation file.

Translation Filename

The file name is determined by concatenating these passed parameters.

filename + prefix + UI_LANGUAGE + suffix

These rules are used in creating the translation filename.

The UI_LANGUAGE is based on the locale. For example, in Switzerland the values might be "de-CH", "it-CH", or "fr-CH". Refer to QLocale::uiLanguages() for additional information.

If the suffix is empty the value of ".qm" will be used

If the directory is empty the application executable location is used

If this file does not exist, other file names will be tried based on a combination of the passed parameters using these rules in the order shown.

Suffix is removed from the filename
UI_LANGUAGE is truncated at the first "_", suffix is added back in
UI_LANGUAGE is truncated at the first "_", suffix is removed
UI_LANGUAGE is removed

Example

Given the following code, assume the system locale where the application is run, has been configured to support "fr-CH" and "it-CH". This would correspond to someone living in Switzerland who speaks French and Italian. CopperSpice will search for a translation file using the file names in the order shown.

load(QLocale::system(), "MyApp", "-", "resources", "qm");

resources/MyApp-fr_CH.qm
resources/MyApp-fr_CH
resources/MyApp-fr.qm
resources/MyApp-fr
resources/MyApp-it_CH.qm
resources/MyApp-it_CH
resources/MyApp-it.qm
resources/MyApp-it
resources/MyApp.qm
resources/MyApp.
resources/MyApp-
resources/MyApp

bool QTranslator::load	(	const QString &	filename,
		const QString &	directory = `QString()`,
		const QString &	search_delimiters = `QString()`,
		const QString &	suffix = `QString()`
	)

Loads a translation file which must then be installed using QCoreApplication::installTranslator(). This method returns true if the translation is successfully loaded, otherwise it returns false. If a prior translation file was loaded for the given QTranslator it will be discarded before loading the new translation file.

Translation Filename

The file name is determined by concatenating these passed parameters.

filename + suffix

These rules are used in creating the translation filename.

If the search_delimiters is empty the default value of "_" will be used
If the suffix is empty the value of ".qm" will be used
If the directory is empty the application executable location is used

If this file does not exist, other file names will be tried based on a combination of the passed parameters using these rules in the order shown.

Suffix is removed from the filename
Using the given search_delimiters, the filename is searched in reverse and if found, this text is truncated, suffix is added back in
Same filename is used, suffix is removed
Filename is searched again for another search_delimiters and if found, additional text is removed, suffix is added back in
Same filename is used, suffix is removed

Example

CopperSpice will search for a translation file using the file names in the order shown.

load("MyApp-fr_ch", "resources", "qm");

resources/MyApp-fr_ch.qm
resources/MyApp-fr_ch
resources/MyApp-fr.qm
resources/MyApp-fr
resources/MyApp.qm
resources/MyApp

bool QTranslator::load	(	const uchar *	data,
		int	len,
		const QString &	directory = `QString()`
	)

Loads the binary data of length len into the translator. The translator must then be installed using QCoreApplication::installTranslator(). This method returns true if the translation is successfully loaded, otherwise it returns false.

The pointer to the data must remain valid for the lifetime of this translator object.

QString QTranslator::translate	(	const char *	context,
		const char *	text,
		const char *	comment = `nullptr`,
		std::optional< int >	numArg = `std::optional<int>()`
	)		const

virtual

Returns the translation for the given context, text, and comment. If no translation is found the search will happen again with an empty comment. If there is still no translation an empty string is returned.

If a value for numArg was passed it will be substituted for the %n in the translated string. This value is also used to choose the appropriate plural form in the translation. An example of the translated text (shown in English for readability) would be "1 file found" versus "5 files found".

Refer to Handle Plurals for additional information.

See also: load()

QString QTranslator::translate	(	const QString &	context,
		const QString &	text,
		const QString &	comment = `QString()`,
		std::optional< int >	numArg = `std::optional<int>()`
	)		const

virtual

The documentation for this overload is identical to the version of translate() which declares the first three parameters as "const char *".

Public Methods

Additional Inherited Members

Detailed Description

Translation Encoding

Looking up Translations

Using Multiple Translations

Constructor & Destructor Documentation

Method Documentation

Translation Filename

Example

Translation Filename

Example