CopperSpice API  1.7.2
QTranslator Class Reference

Provides internationalization support for text output. More...

Inheritance diagram for QTranslator:
QObject

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
 
- 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< QStringdynamicPropertyNames () const
 
virtual bool event (QEvent *event)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
template<typename 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 &objName=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 QMetaObjectmetaObject () const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const
 
QObject * parent () const
 
template<class T = QVariant>
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)
 
QThreadthread () 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)
 
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 QMetaObjectstaticMetaObject ()
 
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
 

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.

  1. Suffix is removed from the filename
  2. UI_LANGUAGE is truncated at the first "_", suffix is added back in
  3. UI_LANGUAGE is truncated at the first "_", suffix is removed
  4. 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");
  1. resources/MyApp-fr_CH.qm
  2. resources/MyApp-fr_CH
  3. resources/MyApp-fr.qm
  4. resources/MyApp-fr
  5. resources/MyApp-it_CH.qm
  6. resources/MyApp-it_CH
  7. resources/MyApp-it.qm
  8. resources/MyApp-it
  9. resources/MyApp.qm
  10. resources/MyApp.
  11. resources/MyApp-
  12. 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.

  1. Suffix is removed from the filename
  2. Using the given search_delimiters, the filename is searched in reverse and if found, this text is truncated, suffix is added back in
  3. Same filename is used, suffix is removed
  4. Filename is searched again for another search_delimiters and if found, additional text is removed, suffix is added back in
  5. 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");
  1. resources/MyApp-fr_ch.qm
  2. resources/MyApp-fr_ch
  3. resources/MyApp-fr.qm
  4. resources/MyApp-fr
  5. resources/MyApp.qm
  6. 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()