Skip to main content

Binary Translations

This section describes how to use binary translations in TouchGFX. Normally text translations are compiled into the application. This principle is efficient and easy to use.
Binary translations keep the text translation out of the application. The binary translations are generated in separate binary files which can be programmed to flash or for example stored on an sdcard. This gives more flexibility to application developers when handling a large number of translations.

Translations​

The Text class in TouchGFX contains a pointer array with a pointer to a translation table for each language in the application. A translation table is in principle a collection of all strings used in that language:

Mapping texts to specific languages

This table allows TouchGFX to find a given text in the selected language.

Mapping to a binary translation

When using binary translations at runtime you change the mapping from the compiled-in translation to a binary translation. The binary translations must be available in addressable memory (flash or RAM). It can for example be loaded from a disk or written to the flash during production.

Configuring the Text converter​

The TouchGFX text converter can be configured to generate binary translations. This is easily done in the TouchGFX Designer 4.13. Go to the Config tab, select "Text Configuration", and click "Binary translation files"

Enabling binary translation

When you generate the code the next time, the binary translations will be in the generated/texts/binary folder.

The translations compiled into the application are empty when binary translations are generated. Therefore no texts are shown unless you load binary translations.

Installing a binary translation​

When the application has the binary translation in memory, it can install it in TouchGFX. Now TouchGFX will use that translation. Depending on the application this can be done in different places or time (The FrontendApplication::FrontendApplication(Model& m, FrontendHeap& heap) constructor in gui/src/common/FrontApplication.cpp can e.g. be used).

Here is an example where we read a translation for English from a filesystem and install it as language "GB".

//read the translation into this global array
uint8_t translation[10000];
...

//read the translation from a file, or change array to a pointer that points
//to the translation data in internal or addressable external flash
FILE* file = fopen("generated/texts/binary/LanguageGb.bin", "rb");
if (file)
{
    //read data from file
    fread(translation, 1, 10000, file);
    fclose(file);

    //replace empty translation with the binary data
    Texts::setTranslation(GB, translation);

    //always change language to get TouchGFX changed from the
    //empty translation compiled in to the binary translation
    Texts::setLanguage(GB);
}

Note, it is necessary to change language after installing a translation. Otherwise TouchGFX will still use the previous translation. Read about changing language here.

It is also necessary to force a redraw of the current screen, or change screen, to see the new texts (if you are loading translations for the language that is used on the display). TouchGFX does not redraw anything automatically.

The current screen can be redrawn by invalidating the root container:

container.invalidate();

This will force a redraw. In some cases it is better to change the screen to get everything set up again from scratch (e.g. to recalculate TextArea sizes). You can change the screen by creating an interaction in TouchGFX Designer with the "Change Screen" action. See this article.