Qt 4.8
Public Functions | List of all members
QTranslator Class Reference

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

#include <qtranslator.h>

Inheritance diagram for QTranslator:
QObject

Public Functions

virtual bool isEmpty () const
 Returns true if this translator is empty, otherwise returns false. More...
 
bool load (const QString &filename, const QString &directory=QString(), const QString &search_delimiters=QString(), const QString &suffix=QString())
 Loads filename + suffix (".qm" if the suffix is not specified), which may be an absolute file name or relative to directory. More...
 
bool load (const QLocale &locale, const QString &filename, const QString &prefix=QString(), const QString &directory=QString(), const QString &suffix=QString())
 Loads filename + prefix + ui language name + suffix (". More...
 
bool load (const uchar *data, int len)
 Loads the QM file data data of length len into the translator. More...
 
 QTranslator (QObject *parent=0)
 Constructs an empty message file object with parent parent that is not connected to any file. More...
 
virtual QString translate (const char *context, const char *sourceText, const char *disambiguation=0) const
 Returns the translation for the key (context, sourceText, disambiguation). More...
 
QString translate (const char *context, const char *sourceText, const char *disambiguation, int n) const
 
 ~QTranslator ()
 Destroys the object and frees any allocated resources. More...
 
- Public Functions inherited from QObject
bool blockSignals (bool b)
 If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it). More...
 
const QObjectListchildren () const
 Returns a list of child objects. More...
 
bool connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
 
bool disconnect (const char *signal=0, const QObject *receiver=0, const char *member=0)
 
bool disconnect (const QObject *receiver, const char *member=0)
 
void dumpObjectInfo ()
 Dumps information about signal connections, etc. More...
 
void dumpObjectTree ()
 Dumps a tree of children to the debug output. More...
 
QList< QByteArraydynamicPropertyNames () const
 Returns the names of all properties that were dynamically added to the object using setProperty(). More...
 
virtual bool event (QEvent *)
 This virtual function receives events to an object and should return true if the event e was recognized and processed. More...
 
virtual bool eventFilter (QObject *, QEvent *)
 Filters events if this object has been installed as an event filter for the watched object. More...
 
template<typename T >
findChild (const QString &aName=QString()) const
 Returns the child of this object that can be cast into type T and that is called name, or 0 if there is no such object. More...
 
template<typename T >
QList< T > findChildren (const QString &aName=QString()) const
 Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects. More...
 
template<typename T >
QList< T > findChildren (const QRegExp &re) const
 
bool inherits (const char *classname) const
 Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false. More...
 
void installEventFilter (QObject *)
 Installs an event filter filterObj on this object. More...
 
bool isWidgetType () const
 Returns true if the object is a widget; otherwise returns false. More...
 
void killTimer (int id)
 Kills the timer with timer identifier, id. More...
 
virtual const QMetaObjectmetaObject () const
 Returns a pointer to the meta-object of this object. More...
 
void moveToThread (QThread *thread)
 Changes the thread affinity for this object and its children. More...
 
QString objectName () const
 
QObjectparent () const
 Returns a pointer to the parent object. More...
 
QVariant property (const char *name) const
 Returns the value of the object's name property. More...
 
Q_INVOKABLE QObject (QObject *parent=0)
 Constructs an object with parent object parent. More...
 
void removeEventFilter (QObject *)
 Removes an event filter object obj from this object. More...
 
void setObjectName (const QString &name)
 
void setParent (QObject *)
 Makes the object a child of parent. More...
 
bool setProperty (const char *name, const QVariant &value)
 Sets the value of the object's name property to value. More...
 
void setUserData (uint id, QObjectUserData *data)
 
bool signalsBlocked () const
 Returns true if signals are blocked; otherwise returns false. More...
 
int startTimer (int interval)
 Starts a timer and returns a timer identifier, or returns zero if it could not start a timer. More...
 
QThreadthread () const
 Returns the thread in which the object lives. More...
 
QObjectUserDatauserData (uint id) const
 
virtual ~QObject ()
 Destroys the object, deleting all its child objects. More...
 

Additional Inherited Members

- Public Slots inherited from QObject
void deleteLater ()
 Schedules this object for deletion. More...
 
- Signals inherited from QObject
void destroyed (QObject *=0)
 This signal is emitted immediately before the object obj is destroyed, and can not be blocked. More...
 
- Static Public Functions inherited from QObject
static bool connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
 Creates a connection of the given type from the signal in the sender object to the method in the receiver object. More...
 
static bool connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
 
static bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
 Disconnects signal in object sender from method in object receiver. More...
 
static bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
 
static uint registerUserData ()
 
static QString tr (const char *sourceText, const char *comment=0, int n=-1)
 
static QString trUtf8 (const char *sourceText, const char *comment=0, int n=-1)
 
- Static Public Variables inherited from QObject
static const QMetaObject staticMetaObject
 This variable stores the meta-object for the class. More...
 
- Protected Functions inherited from QObject
virtual void childEvent (QChildEvent *)
 This event handler can be reimplemented in a subclass to receive child events. More...
 
virtual void connectNotify (const char *signal)
 This virtual function is called when something has been connected to signal in this object. More...
 
virtual void customEvent (QEvent *)
 This event handler can be reimplemented in a subclass to receive custom events. More...
 
virtual void disconnectNotify (const char *signal)
 This virtual function is called when something has been disconnected from signal in this object. More...
 
 QObject (QObjectPrivate &dd, QObject *parent=0)
 
int receivers (const char *signal) const
 Returns the number of receivers connected to the signal. More...
 
QObjectsender () const
 Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns 0. More...
 
int senderSignalIndex () const
 
virtual void timerEvent (QTimerEvent *)
 This event handler can be reimplemented in a subclass to receive timer events for the object. More...
 
- Protected Variables inherited from QObject
QScopedPointer< QObjectDatad_ptr
 
- Static Protected Variables inherited from QObject
static const QMetaObject staticQtMetaObject
 

Detailed Description

The QTranslator class provides internationalization support for text output.

An object of this class contains a set of translations from a source language to a target language. QTranslator provides functions to look up translations in a translation file. Translation files are created using Qt Linguist.

The most common use of QTranslator is to: load a translation file, install it using QApplication::installTranslator(), and use it via QObject::tr(). Here's the main() function from the Hello tr() example:

int main(int argc, char *argv[])
{
QApplication app(argc, argv);
QTranslator translator;
translator.load("hellotr_la");
app.installTranslator(&translator);
QPushButton hello(QPushButton::tr("Hello world!"));
hello.resize(100, 30);
hello.show();
return app.exec();
}

Note that the translator must be created before the application's widgets.

Most applications will never need to do anything else with this class. The other functions provided by this class are useful for applications that work on translator files.

Looking up Translations

It is possible to look up a translation using translate() (as tr() and QApplication::translate() do). The translate() function takes up to three parameters:

For example, the "Cancel" in a dialog might have "Anuluj" when the program runs in Polish (in this case the source text would be "Cancel"). The context would (normally) be the dialog's class name; there would normally be no comment, and the translated text would be "Anuluj".

But it's not always so simple. The Spanish version of a printer dialog with settings for two-sided printing and binding would probably require both "Activado" and "Activada" as translations for "Enabled". In this case the source text would be "Enabled" in both cases, and the context would be the dialog's class name, but the two items would have disambiguations such as "two-sided printing" for one and "binding" for the other. The disambiguation enables the translator to choose the appropriate gender for the Spanish version, and enables Qt to distinguish between translations.

Using Multiple Translations

Multiple translation files can be installed in an application. Translations are searched for in the reverse order in which they were installed, so the most recently installed translation file is searched for translations first and the earliest translation file is searched last. The search stops as soon as a translation containing a matching string is found.

This mechanism makes it possible for a specific translation to be "selected" or given priority over the others; simply uninstall the translator from the application by passing it to the QApplication::removeTranslator() function and reinstall it with QApplication::installTranslator(). It will then be the first translation to be searched for matching strings.

See also
QApplication::installTranslator(), QApplication::removeTranslator(), QObject::tr(), QApplication::translate(), {I18N Example}, {Hello tr() Example}, {Arrow Pad Example}, {Troll Print Example}

Definition at line 59 of file qtranslator.h.

Constructors and Destructors

◆ QTranslator()

QTranslator::QTranslator ( QObject parent = 0)
explicit

Constructs an empty message file object with parent parent that is not connected to any file.

Definition at line 342 of file qtranslator.cpp.

343  : QObject(*new QTranslatorPrivate, parent)
344 {
345 }
Q_INVOKABLE QObject(QObject *parent=0)
Constructs an object with parent object parent.
Definition: qobject.cpp:753

◆ ~QTranslator()

QTranslator::~QTranslator ( )

Destroys the object and frees any allocated resources.

Definition at line 363 of file qtranslator.cpp.

364 {
367  Q_D(QTranslator);
368  d->clear();
369 }
double d
Definition: qnumeric_p.h:62
static void removeTranslator(QTranslator *messageFile)
Removes the translation file translationFile from the list of translation files used by this applicat...
#define Q_D(Class)
Definition: qglobal.h:2482
The QTranslator class provides internationalization support for text output.
Definition: qtranslator.h:59
static QCoreApplication * instance()
Returns a pointer to the application&#39;s QCoreApplication (or QApplication) instance.

Functions

◆ isEmpty()

bool QTranslator::isEmpty ( ) const
virtual

Returns true if this translator is empty, otherwise returns false.

This function works with stripped and unstripped translation files.

Definition at line 1045 of file qtranslator.cpp.

Referenced by QCoreApplication::installTranslator().

1046 {
1047  Q_D(const QTranslator);
1048  return !d->unmapPointer && !d->unmapLength && !d->messageArray &&
1049  !d->offsetArray && !d->contextArray;
1050 }
double d
Definition: qnumeric_p.h:62
#define Q_D(Class)
Definition: qglobal.h:2482
The QTranslator class provides internationalization support for text output.
Definition: qtranslator.h:59

◆ load() [1/3]

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

Loads filename + suffix (".qm" if the suffix is not specified), which may be an absolute file name or relative to directory.

Returns true if the translation is successfully loaded; otherwise returns false.

If directory is not specified, the directory of the application's executable is used (i.e., as QCoreApplication::applicationDirPath()).

The previous contents of this translator object are discarded.

If the file name does not exist, other file names are tried in the following order:

  1. File name without suffix appended.
  2. File name with text after a character in search_delimiters stripped ("_." is the default for search_delimiters if it is an empty string) and suffix.
  3. File name stripped without suffix appended.
  4. File name stripped further, etc.

For example, an application running in the fr_CA locale (French-speaking Canada) might call load("foo.fr_ca", "/opt/foolib"). load() would then try to open the first existing readable file from this list:

  1. /opt/foolib/foo.fr_ca.qm
  2. /opt/foolib/foo.fr_ca
  3. /opt/foolib/foo.fr.qm
  4. /opt/foolib/foo.fr
  5. /opt/foolib/foo.qm
  6. /opt/foolib/foo

Definition at line 411 of file qtranslator.cpp.

414 {
415  Q_D(QTranslator);
416  d->clear();
417 
418  QString fname = filename;
419  QString prefix;
420  if (QFileInfo(filename).isRelative()) {
421 #ifdef Q_OS_SYMBIAN
422  //TFindFile doesn't like path in the filename
423  QString dir(directory);
424  int slash = filename.lastIndexOf(QLatin1Char('/'));
425  slash = qMax(slash, filename.lastIndexOf(QLatin1Char('\\')));
426  if (slash >=0) {
427  //so move the path component into the directory prefix
428  if (dir.isEmpty())
429  dir = filename.left(slash + 1);
430  else
431  dir = dir + QLatin1Char('/') + filename.left(slash + 1);
432  fname = fname.mid(slash + 1);
433  }
434  if (dir.isEmpty())
436  else
437  prefix = QFileInfo(dir).absoluteFilePath(); //TFindFile doesn't like dirty paths
438  if (prefix.length() > 2 && prefix.at(1) == QLatin1Char(':') && prefix.at(0).isLetter())
439  prefix[0] = QLatin1Char('Y');
440 #else
441  prefix = directory;
442 #endif
443  if (prefix.length() && !prefix.endsWith(QLatin1Char('/')))
444  prefix += QLatin1Char('/');
445  }
446 
447 #ifdef Q_OS_SYMBIAN
448  QString nativePrefix = QDir::toNativeSeparators(prefix);
449 #endif
450 
451  QString realname;
452  QString delims;
453  delims = search_delimiters.isNull() ? QString::fromLatin1("_.") : search_delimiters;
454 
455  for (;;) {
456  QFileInfo fi;
457 
458 #ifdef Q_OS_SYMBIAN
459  //search for translations on other drives, e.g. Qt may be in Z, while app is in C
460  //note this uses symbian search rules, i.e. y:->a:, followed by z:
461  TFindFile finder(qt_s60GetRFs());
462  QString fname2 = fname + (suffix.isNull() ? QString::fromLatin1(".qm") : suffix);
463  TInt err = finder.FindByDir(
464  qt_QString2TPtrC(fname2),
465  qt_QString2TPtrC(nativePrefix));
466  if (err != KErrNone)
467  err = finder.FindByDir(qt_QString2TPtrC(fname), qt_QString2TPtrC(nativePrefix));
468  if (err == KErrNone) {
469  fi.setFile(qt_TDesC2QString(finder.File()));
470  realname = fi.canonicalFilePath();
471  if (fi.isReadable() && fi.isFile())
472  break;
473  }
474 #endif
475 
476  realname = prefix + fname + (suffix.isNull() ? QString::fromLatin1(".qm") : suffix);
477  fi.setFile(realname);
478  if (fi.isReadable() && fi.isFile())
479  break;
480 
481  realname = prefix + fname;
482  fi.setFile(realname);
483  if (fi.isReadable() && fi.isFile())
484  break;
485 
486  int rightmost = 0;
487  for (int i = 0; i < (int)delims.length(); i++) {
488  int k = fname.lastIndexOf(delims[i]);
489  if (k > rightmost)
490  rightmost = k;
491  }
492 
493  // no truncations? fail
494  if (rightmost == 0)
495  return false;
496 
497  fname.truncate(rightmost);
498  }
499 
500  // realname is now the fully qualified name of a readable file.
501  return d->do_load(realname);
502 }
double d
Definition: qnumeric_p.h:62
bool isLetter() const
Returns true if the character is a letter (Letter_* categories); otherwise returns false...
Definition: qchar.cpp:653
const QChar at(int i) const
Returns the character at the given index position in the string.
Definition: qstring.h:698
int length() const
Returns the number of characters in this string.
Definition: qstring.h:696
QString absoluteFilePath() const
Returns an absolute path including the file name.
Definition: qfileinfo.cpp:534
The QString class provides a Unicode character string.
Definition: qstring.h:83
#define Q_D(Class)
Definition: qglobal.h:2482
Q_DECL_CONSTEXPR const T & qMax(const T &a, const T &b)
Definition: qglobal.h:1217
static QString applicationDirPath()
Returns the directory that contains the application executable.
QString left(int n) const Q_REQUIRED_RESULT
Returns a substring that contains the n leftmost characters of the string.
Definition: qstring.cpp:3664
void setFile(const QString &file)
Sets the file that the QFileInfo provides information about to file.
Definition: qfileinfo.cpp:468
QString canonicalFilePath() const
Returns the canonical path including the file name, i.e.
Definition: qfileinfo.cpp:551
The QTranslator class provides internationalization support for text output.
Definition: qtranslator.h:59
bool isNull() const
Returns true if this string is null; otherwise returns false.
Definition: qstring.h:505
QString mid(int position, int n=-1) const Q_REQUIRED_RESULT
Returns a string that contains n characters of this string, starting at the specified position index...
Definition: qstring.cpp:3706
int lastIndexOf(QChar c, int from=-1, Qt::CaseSensitivity cs=Qt::CaseSensitive) const
Definition: qstring.cpp:3000
static QString fromLatin1(const char *, int size=-1)
Returns a QString initialized with the first size characters of the Latin-1 string str...
Definition: qstring.cpp:4188
bool isFile() const
Returns true if this object points to a file or to a symbolic link to a file.
Definition: qfileinfo.cpp:971
bool isReadable() const
Returns true if the user can read the file; otherwise returns false.
Definition: qfileinfo.cpp:896
bool endsWith(const QString &s, Qt::CaseSensitivity cs=Qt::CaseSensitive) const
Returns true if the string ends with s; otherwise returns false.
Definition: qstring.cpp:3796
The QFileInfo class provides system-independent file information.
Definition: qfileinfo.h:60
static QString toNativeSeparators(const QString &pathName)
Returns pathName with the &#39;/&#39; separators converted to separators that are appropriate for the underly...
Definition: qdir.cpp:812
The QLatin1Char class provides an 8-bit ASCII/Latin-1 character.
Definition: qchar.h:55

◆ load() [2/3]

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

Loads filename + prefix + ui language name + suffix (".

Since
4.8

qm" if the suffix is not specified), which may be an absolute file name or relative to directory. Returns true if the translation is successfully loaded; otherwise returns false.

The previous contents of this translator object are discarded.

If the file name does not exist, other file names are tried in the following order:

  1. File name without suffix appended.
  2. File name with ui language part after a "_" character stripped and suffix.
  3. File name with ui language part stripped without suffix appended.
  4. File name with ui language part stripped further, etc.

For example, an application running in the locale with the following ui languages - "es", "fr-CA", "de" might call load(QLocale::system(), "foo", ".", "/opt/foolib", ".qm"). load() would replace '-' (dash) with '_' (underscore) in the ui language and then try to open the first existing readable file from this list:

  1. /opt/foolib/foo.es.qm
  2. /opt/foolib/foo.es
  3. /opt/foolib/foo.fr_CA.qm
  4. /opt/foolib/foo.fr_CA
  5. /opt/foolib/foo.de.qm
  6. /opt/foolib/foo.de
  7. /opt/foolib/foo.fr.qm
  8. /opt/foolib/foo.fr
  9. /opt/foolib/foo.qm
  10. /opt/foolib/foo.
  11. /opt/foolib/foo

On operating systems where file system is case sensitive, QTranslator also tries to load a lower-cased version of the locale name.

Definition at line 718 of file qtranslator.cpp.

723 {
724  Q_D(QTranslator);
725  d->clear();
726  QString fname = find_translation(locale, filename, prefix, directory, suffix);
727  return !fname.isEmpty() && d->do_load(fname);
728 }
double d
Definition: qnumeric_p.h:62
The QString class provides a Unicode character string.
Definition: qstring.h:83
#define Q_D(Class)
Definition: qglobal.h:2482
bool isEmpty() const
Returns true if the string has no characters; otherwise returns false.
Definition: qstring.h:704
The QTranslator class provides internationalization support for text output.
Definition: qtranslator.h:59
static QString find_translation(const QLocale &locale, const QString &filename, const QString &prefix, const QString &directory, const QString &suffix)

◆ load() [3/3]

bool QTranslator::load ( const uchar data,
int  len 
)

Loads the QM file data data of length len into the translator.

The data is not copied. The caller must be able to guarantee that data will not be deleted or modified.

Definition at line 740 of file qtranslator.cpp.

741 {
742  Q_D(QTranslator);
743  d->clear();
744  return d->do_load(data, len);
745 }
double d
Definition: qnumeric_p.h:62
#define Q_D(Class)
Definition: qglobal.h:2482
static const char * data(const QByteArray &arr)
The QTranslator class provides internationalization support for text output.
Definition: qtranslator.h:59

◆ translate() [1/2]

QString QTranslator::translate ( const char *  context,
const char *  sourceText,
const char *  disambiguation = 0 
) const
virtual

Returns the translation for the key (context, sourceText, disambiguation).

If none is found, also tries (context, sourceText, ""). If that still fails, returns an empty string.

If you need to programatically insert translations in to a QTranslator, this function can be reimplemented.

See also
load()

Definition at line 1009 of file qtranslator.cpp.

Referenced by translate(), and QCoreApplication::translate().

1010 {
1011  Q_D(const QTranslator);
1012  return d->do_translate(context, sourceText, disambiguation, -1);
1013 }
double d
Definition: qnumeric_p.h:62
#define Q_D(Class)
Definition: qglobal.h:2482
The QTranslator class provides internationalization support for text output.
Definition: qtranslator.h:59

◆ translate() [2/2]

QString QTranslator::translate ( const char *  context,
const char *  sourceText,
const char *  disambiguation,
int  n 
) const

Definition at line 1031 of file qtranslator.cpp.

1033 {
1034  Q_D(const QTranslator);
1035  // this step is necessary because the 3-parameter translate() overload is virtual
1036  if (n == -1)
1037  return translate(context, sourceText, disambiguation);
1038  return d->do_translate(context, sourceText, disambiguation, n);
1039 }
double d
Definition: qnumeric_p.h:62
#define Q_D(Class)
Definition: qglobal.h:2482
The QTranslator class provides internationalization support for text output.
Definition: qtranslator.h:59
virtual QString translate(const char *context, const char *sourceText, const char *disambiguation=0) const
Returns the translation for the key (context, sourceText, disambiguation).

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