#include <QTrans.h>
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:
-fxtrans-language=<ll> where <ll> is a ISO639 two letter code sets that language to override the locale-determined one. This is useful for testing. -fxtrans-country=<cc> where <cc> is a ISO3166 two letter code sets that region to override the locale-determined one. This is useful for testing. -fxtrans-dump<n> causes the zero-based embedded translation file number <n> to be dumped to stdout. You can save this, extend it and place it next to the shared library as usual. Unfortunately, there is no way to know which number is the library or application due to the vagaries of C++ static data initialisation order (start with 0, increment from there).
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< ProvidedInfo > | ProvidedInfoList |
Static Public Member Functions | |
| static QTransString | tr (const char *context, const char *text, const char *hint=0) |
| static const FXString & | language (LanguageType=ISO639) |
| static const FXString & | country (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 |
Defines a list of QTrans::ProvidedInfo.
| static QTransString FX::QTrans::tr | ( | const char * | context, | |
| const char * | text, | |||
| const char * | hint = 0 | |||
| ) | [static] |
| 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. |
| 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
v1.5.6