FX::QTrans Class Reference

#include <QTrans.h>

List of all members.


Detailed Description

The central class for human language translation (Qt compatible).

QTrans translates text displayed to the user to their preferred language, falling back on English if no translation is available. To do this, it reads in a file at startup containing translations from English to whatever number of human languages - however the database can also be dynamically altered.

Usage of automatic human language conversion is very easy - simply wrap your literal strings with tr() which returns the converted text as an QTransString. If you use the n insert identifiers and arg() it permits easy substitution of run-time information into strings in a language neutral way ie; inserts can be reordered based on accurate translation requirements. Furthermore, the translation file can customise its translation based upon the values of the parameters - see the tutorial on writing translation files.

Even easier use of tr() can occur in subclasses of FXObject as this automatically adds the class name before calling tr() in QTrans for you (watch out you don't call FXObject::tr() in your constructor - virtual tables haven't been set yet!). In those classes which don't subclass FXObject, you must call the static method QTrans::tr() manually specifying the class name.

The python script CppMunge.py can extract all code using tr() and place the strings in a text file which you should call <exename>Trans.txt suitable for loading on startup. You should extend each string definition with an appropriate translation and place it in the same directory as the executable. You may optionally apply gzip to the file, thus calling it <exename>Trans.gz and it will be automatically decompressed on load. Alternatively you can embed the translation file into your executable using the provided reswrap utility and QTRANS_SETTRANSFILE(). See the tutorial for more details.

Note that QTrans is instantiated by FXProcess on startup. FXProcess provides special command line support for QTrans so that the following command line arguments when provided to the application have effect:

The last two are intended for end-users who are not programmers to easily extract and extend locale customisations of your application - even if they only have the binaries.

Note:
All QTrans functions are thread-safe

Implementation notes:

As noted above, embedded data is registered statically with QTrans which then loads it on FXProcess startup. However if QTrans is already created, it immediately loads in the data - plus if embedded data is destructed, it removes the data that was loaded from the particular containing module.

This means that you can embed translation files into your dynamically loaded shared libraries and when you kick them in or out of memory it correctly adds and removes the translations. QTrans determines which translation bank it should preferentially use by checking if the address of the string literal you wish to translate lies near to the static data initialised for that binary - thus where each module defines a different translation of the same English text, the correct one is found - however if a module doesn't define its own translation, the first registered translation is used instead (usually TnFOX itself, then the base executable - but it changes according to how you have set up your FXProcess static init dependencies).

Definition at line 198 of file QTrans.h.

Public Types

typedef QValueList< ProvidedInfoProvidedInfoList
 ISO639
 ISO3166
enum  LanguageType { ISO639 }
enum  CountryType { ISO3166 }

Public Member Functions

 ~QTrans ()

Static Public Member Functions

static QTransString tr (const char *context, const char *text, const char *hint=0)
static const FXStringlanguage (LanguageType=ISO639)
static const FXStringcountry (CountryType=ISO3166)
static void refresh ()
static void overrideLanguage (const FXString &iso639)
static void overrideCountry (const FXString &iso3166)
static ProvidedInfoList provided ()

Friends

class QTransInit
class QTrans_EmbeddedTranslationFile
class QTransString

Classes

struct  ProvidedInfo


The documentation for this class was generated from the following file:
(C) 2002-2009 Niall Douglas. Some parts (C) to assorted authors.
Generated on Fri Nov 20 18:37:46 2009 for TnFOX by doxygen v1.4.7