| **Navigation:**  [[abc library reference.htm|ABC Library Reference]] > TranslatorClass >====== TranslatorClass Overview {{c6h0009.jpg|C6H0009.jpg}} ====== | [[translatorclass.htm|{{btn_prev_n.gif|Previous page}}]][[abc library reference.htm|{{btn_home_n.gif|Return to chapter overview}}]][[translatorclass properties.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

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  identify text to translate .htm|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 [[translatorclass overview.htm#yi 52n|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 [[translatorclass overview.htm#yi 52n|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 [[global  properties.htm|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.

{{notebox.jpg|NoteBox.jpg}}

**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**