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).

Public Types

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

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


Member Typedef Documentation

Defines a list of QTrans::ProvidedInfo.


Member Enumeration Documentation

Enumerator:
ISO639  Two letter ISO639 standard.

Enumerator:
ISO3166  Two letter ISO3166 standard.


Member Function Documentation

static QTransString FX::QTrans::tr ( const char *  context,
const char *  text,
const char *  hint = 0 
) [static]

Returns:
The human language translated version of the text
Parameters:
context Usually the classname of where you are calling from
text The string to be translated in English. This must be a literal as its address is used to calculate which translation file to use.
hint Usually unused, needed to resolve ambiguities eg; masculine/feminine genders when translating from gender neutral English. Never write "m" or "f" - instead if it refers to a box, use "box" - thus it doesn't matter if a box is masculine or feminine.
Begins a translation of the text based upon the currently set user language.

static const FXString& FX::QTrans::language ( LanguageType  = ISO639  )  [static]

Returns the current language of the user currently using the application.

static const FXString& FX::QTrans::country ( CountryType  = ISO3166  )  [static]

Returns the country the computer believes it is currently in.

static void FX::QTrans::refresh (  )  [static]

Refreshes the internal cache of locale information. You should call this if you have reason to believe that the user's settings have changed. Note that the overrides taken precedence over any refreshes.

static void FX::QTrans::overrideLanguage ( const FXString iso639  )  [static]

Overrides the language setting to the specified ISO639 two letter code. Specifying a null string returns the system to the user locale.

static void FX::QTrans::overrideCountry ( const FXString iso3166  )  [static]

Overrides the country setting to the specified ISO3166 two letter code. Specifying a null string returns the system to the user locale.

static ProvidedInfoList FX::QTrans::provided (  )  [static]

Returns a list of supported languages by each currently loaded library. Not every library will provide the same languages so to determine what language choices to offer your user you should only offer those provided by all libraries. The list is ready sorted by module first, then by language and finally country


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

(C) 2002-2008 Niall Douglas. Some parts (C) to assorted authors.
Generated on Fri Jun 13 22:29:02 2008 for TnFOX by doxygen v1.5.6