User Tools

Site Tools


translatorclass_overview.htm
Navigation:  ABC Library Reference > TranslatorClass >====== TranslatorClass Overview C6H0009.jpg ====== Previous pageReturn to chapter overviewNext 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 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.

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

translatorclass_overview.htm.txt · Last modified: 2021/04/15 15:57 by 127.0.0.1