Navigation: ABC Library Reference > TranslatorClass >====== TranslatorClass Overview ====== | |
By default, the ABC Templates, the ABC Library, and the Clarion visual source code formatters generate American English user interfaces. However, Clarion makes it very easy to efficiently produce non-English user interfaces for your application programs.
The TranslatorClass provides very fast runtime translation of user interface text. The TranslatorClass lets you deploy a single application that serves all your customers, regardless of their language preference. That is, you can use the TranslatorClass to display several different user interface languages based on end user input or some other runtime criteria, such as INI file or control file contents.
Alternatively, you can use the Clarion translation files (*.TRN) to implement a single non-English user inteface at compile time.
TranslatorClass Concepts
The TranslatorClass and the ABUTIL.TRN file provide a way to perform language translation at runtime. That is, you can make your program display one or more non-English user interfaces based on end user input or some other runtime criteria such as INI file or control file contents. You can also use the TranslatorClass to customize a single application for multiple customers. The TranslatorClass operates on all user interface elements including window controls, window titlebars, tooltips, list box headers, and static report controls.
The ABUTIL.TRN File
The ABUTIL.TRN file contains translation pairs for all the user interface text generated by the ABC Templates and the ABC Library. A translation pair is simply two text strings: one text string for which to search and another text string to replace the searched-for text. At runtime, the TranslatorClass applies the translation pairs to each user interface element.
You can directly edit the ABUTIL.TRN file to add additional translation items. We recommend this method for translated text common to several applications. The translation pairs you add to the Translator GROUP declared in ABUTIL.TRN are automatically shared by any application relying on the ABC Library and the ABC Templates.
Translating Custom Text
The default ABUTIL.TRN translation pairs do not include any custom text that you apply to your windows and menus. To translate custom text, you simply add translation pairs to the translation process, either at a global level or at a local level according to your requirements. To help identify custom text, the TranslatorClass automatically identifies any untranslated text for you; you need only supply the translation. See ExtractText for more information.
Macro Substitution
The TranslatorClass defines and translates macro strings. A TranslatorClass macro is simply text delimited by percent signs (%), such as %mymacro%. You may use a macro within the text on an APPLICATION, WINDOW, or REPORT control or titlebar, or you may use a macro within TranslatorClass translation pairs text.
You define the macro with surrounding percent signs (%), and you define its substitution value with a TranslatorClass translation pair (without percent signs).
This macro substitution capability lets you
·translate a small portion (the macro) of a larger text string
·do multiple levels of translation (a macro substitution value may also contain a macro)
See the Conceptual Example for more information.
TranslatorClass Relationship to Other Application Builder Classes
The WindowManager, PopupClass, and PrintPreviewClass optionally use the TranslatorClass to translate text at runtime. These classes do not require the TranslatorClass; however, if you want them to do runtime translation, you must include the TranslatorClass in your program. See the Conceptual Example.
TranslatorClass ABC Template Implementation
The ABC Templates instantiate a global TranslatorClass object for each application that checks the Enable Run-Time Translation box on the Global Properties dialog. See Template Overview--Application Properties for more information.
The TranslatorClass object is called Translator, and each template-generated procedure calls on the Translator object to translate all text for its APPLICATION, WINDOW or REPORT. Additionally, the template-generated PopupClass objects (ASCIIViewer and BrowseBox templates) and PrintPreviewClass objects (Report template) use the Translator to translate menu text.
The ABC Templates use the TranslatorClass to apply user interface text defined at compile time. The templates do not provide a runtime switch between user interface languages.
TranslatorClass Source Files
The TranslatorClass source code is installed by default to the Clarion \LIBSRC folder. The TranslatorClass source code and its respective components are contained in:
ABUTIL.INC | TranslatorClass declarations | |
ABUTIL.CLW | TranslatorClass method definitions | |
ABUTIL.TRN | TranslatorClass default translation pairs |
TranslatorClass Conceptual Example
The following example shows a typical sequence of statements to declare, instantiate, initialize, use, and terminate a TranslatorClass object.
This example applies both default and custom translations to a “preferences” window. It also collects and stores untranslated text in a file so you don't have to manually collect the text to translate.
PROGRAM
INCLUDE('ABUTIL.INC') !declare TranslatorClass
MAP
END
MyTranslations GROUP !declare local translations
Items USHORT(4) !4 translations pairs
PSTRING('Company') ! item 1 text (macro)
PSTRING('Widget %CoType%') ! item 1 replacement text
PSTRING('&Sound') ! item 2 text
PSTRING('&xSoundx') ! item 2 replacement text
PSTRING('&Volume') ! item 3 text
PSTRING('&xVolumex') ! item 3 replacement text
PSTRING('OK') ! item 4 text
PSTRING('xOKx') ! item 4 replacement text
END
INIMgr INIClass !declare INIMgr object
Translator TranslatorClass !declare Translator object
CoType STRING('Inc.') !default company type
Sound STRING('ON ') !default preference value
Volume BYTE(3) !default preference value
PWindow WINDOW('%Company% Preferences'),AT(,,100,35),IMM,SYSTEM,GRAY
CHECK('&Sound'),AT(8,6),USE(Sound),VALUE('ON','OFF')
PROMPT('&Volume'),AT(31,19),USE(?VolumePrompt)
SPIN(@s20),AT(8,20,21,7),USE(Volume),HVSCROLL,RANGE(0,9),STEP(1)
BUTTON('OK'),AT(57,3,30,10),USE(?OK)
END
CODE
INIMgr.Init('.\MyApp.INI') !initialize INIMgr object
INIMgr.Fetch('Preferences','CoType',CoType) !get company type, default Inc.
Translator.Init !initialize Translator object:
! add default translation pairs
Translator.AddTranslation(MyTranslations) !add local translation pairs
Translator.AddTranslation('CoType',CoType) !add translation pair from INI
Translator.ExtractText='.\MyApp.trn' !collect user interface text
OPEN(PWindow)
Translator.TranslateWindow !translate controls & titlebar
ACCEPT
IF EVENT() = EVENT:Accepted
IF FIELD() = ?OK
INIMgr.Update('Preferences','Sound',Sound)
INIMgr.Update('Preferences','Volume',Volume)
POST(EVENT:CloseWindow)
. . .
Translator.Kill !write user inteface text