GTRANS

The GTRANS module allows to manage language translations. The language of an application can be changed dynamically during run-time using the GTRANS module.

API reference

The API reference of the GTRANS module can be found here.

Intended usage

Each translation is specified by a transTable struct which is essentially a table of strings:

typedef struct transTable {
    unsigned numEntries;     // The number of strings that this table contains
    const char** strings;    // The translated strings
} transTable;

A translatable application needs to have a base language. All translations happen relative to that base language. The base language is specified using gtransSetBaseLanguage(). The current language of the application is set using gtransSetLanguage(). The actual translations take place by calling gtransString(). A string contained in the translation table of the base language is passed to gtransString(). The function returns the corresponding string of the current language that was set using gtransSetLanguage() or the passed string if none was found.

A wrapper macro named gt() around gtransString() is available to make writing and reading translatable applications easier:

#define gt(str) gtransString(str)

Optimization

Calling gt() (or gtransString() directly) uses the strcmp() function of the standard C library to compare strings. This operation can take a lot of time. For performance critical applications or low-resource systems the application translation speed can be optimized by using gtransIndex() (instead of gtransString()) which directly takes the index of the string in the translation table. However, this introduces the limitation that each string in each of the translation tables need to be at the same position (the same index). Using gtransString() allows to have translation tables of unequal sizes due to the nature of the translation being based on string comparison rather than index accessing of the table.

Example

Complete examples can be found under /demos/modules/gtrans/ in the uGFX library directory.

Basic Example

The following code is a very simple usage example showing how the GTRANS module is used. This is a very minimalistic example with no dependencies other than the GDISP module to interface a display.

/*
 * Copyright (c) 2012, 2013, Joel Bodenmann aka Tectu <joel@unormal.org>
 * Copyright (c) 2012, 2013, Andrew Hannam aka inmarket
 *
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *    * Redistributions of source code must retain the above copyright
 *      notice, this list of conditions and the following disclaimer.
 *    * Redistributions in binary form must reproduce the above copyright
 *      notice, this list of conditions and the following disclaimer in the
 *      documentation and/or other materials provided with the distribution.
 *    * Neither the name of the <organization> nor the
 *      names of its contributors may be used to endorse or promote products
 *      derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
#include <stdio.h>
#include "gfx.h"
 
#define COLOR_BACKGROUND    Silver
#define COLOR_TEXT          Black
 
font_t font;
 
// English Translation
static const char* EnglishStrings[] = {
    "Welcome",
    "The temperature is %d degrees",
    "Goodbye",
    "This is a translated uGFX application"
};
static const transTable EnglishTranslation = { sizeof(EnglishStrings)/sizeof(EnglishStrings[0]), EnglishStrings };
 
// German translation
static const char* GermanStrings[] = {
    "Herzlich Willkommen",
    "Die Temperatur beträgt %d Grad",
    "Auf Wiedersehen",
    "Das ist eine übersetzte uGFX Anwendung"
};
static const transTable GermanTranslation = { sizeof(GermanStrings)/sizeof(GermanStrings[0]), GermanStrings };
 
// French translation
static const char* FrenchStrings[] = {
    "Bienvenue",
    "La température est de %d degrés",
    "Au revoir",
    "Ceci est une application traduit uGFX"
};
static const transTable FrenchTranslation = { sizeof(FrenchStrings)/sizeof(FrenchStrings[0]), FrenchStrings };
 
void updateText()
{
    coord_t width = 400;
    coord_t height = 30;
 
    // Translate some basic strings
    gdispFillStringBox(20,  20, width, height, gt("Welcome"), font, COLOR_TEXT, COLOR_BACKGROUND, justifyLeft);
    gdispFillStringBox(20,  60, width, height, gt("This is a translated uGFX application"), font, COLOR_TEXT, COLOR_BACKGROUND, justifyLeft);
    gdispFillStringBox(20, 100, width, height, gt("Goodbye"), font, COLOR_TEXT, COLOR_BACKGROUND, justifyLeft);
 
    // A more complex example using string formatting
    char buffer[128];
    sprintf(buffer, gt("The temperature is %d degrees"), 18);
    gdispFillStringBox(20, 140, width, height, buffer, font, COLOR_TEXT, COLOR_BACKGROUND, justifyLeft);
}
 
int main(void)
{
    // Initialize the uGFX library
    gfxInit();
    gdispClear(COLOR_BACKGROUND);
 
    // Take the first font we find
    font = gdispOpenFont("*");
 
    // Set the base language of the application
    gtransSetBaseLanguage(&EnglishTranslation);
 
    // Loop through the languages
    while (TRUE) {
        // English
        gtransSetLanguage(&EnglishTranslation);
        updateText();
        gfxSleepMilliseconds(3000);
 
        // German
        gtransSetLanguage(&GermanTranslation);
        updateText();
        gfxSleepMilliseconds(3000);
 
        // French
        gtransSetLanguage(&FrenchTranslation);
        updateText();
        gfxSleepMilliseconds(3000);
    }
 
    return 0;
}

Example with widgets

The following example demonstrates how the language of an application using widgets can be translated using GTRANS. The user can select the language using buttons.

ToDo