Translation¶

Overview¶

LVGL supports two ways of handling translations:

lv_i18n: A comprehensive tool that extracts translatable strings from C files into YAML files, and generates C translation files from them. It also supports plural forms. See its README for details.
lv_translation: A simpler yet more flexible solution that allows adding translations statically or dynamically. This is the method documented here.

Add Translations¶

Static Translations¶

If most translations are known at compile time, they can be defined using string arrays:

This method uses only a little extra RAM, as only the pointers to the strings are stored.

Dynamic Translations¶

If translations are only available at runtime (e.g., from files, serial ports, or online sources), they can be added dynamically.

This approach involves memory allocation. See the example at the bottom of this page for reference.

Select a Language¶

Once translations are registered, use:

lv_translation_set_language("language")

to set the current language. The parameter must match one of the language names provided during registration.

Translate Strings¶

To retrieve a translation for a given tag, use:

lv_translation_get("tag")
or the shorthand: lv_tr("tag")

These return a translated string which can be used with widgets:

Fallbacks¶

If a tag exists but the translation for the selected language is missing the tag itself will be returned.

If the tag is not found at all, the tag itself will be used as a fallback as well.

Example¶

Simple translation example¶

#include "../../lv_examples.h"
#if LV_USE_TRANSLATION && LV_BUILD_EXAMPLES

static void add_static(void)
{
    static const char * languages[] = {"en", "de", "es", NULL};
    static const char * tags[] = {"tiger", "lion", "rabbit", "elephant", NULL};
    static const char * translations[] = {
        "The Tiger", "Der Tiger", "El Tigre",
        "The Lion", "Der Löwe", "El León",
        "The Rabbit", "Das Kaninchen", "El Conejo",
        "The Elephant", "Der Elefant", "El Elefante",
    };

    lv_translation_add_static(languages, tags, translations);
}

static void add_dynamic(void)
{
    lv_translation_pack_t * pack = lv_translation_add_dynamic();
    lv_translation_add_language(pack, "en");
    lv_translation_add_language(pack, "de");

    lv_translation_tag_dsc_t * tag;
    tag = lv_translation_add_tag(pack, "table");
    lv_translation_set_tag_translation(pack, tag, 0, "It's a table");
    lv_translation_set_tag_translation(pack, tag, 1, "Das is ein Tish");

    tag = lv_translation_add_tag(pack, "chair");
    lv_translation_set_tag_translation(pack, tag, 0, "It's a chair");
    lv_translation_set_tag_translation(pack, tag, 1, "Das ist ein Stuhl");
}

/**
 * Create and use translations
 */
void lv_example_translation_1(void)
{
    add_static();
    add_dynamic();

    lv_translation_set_language("de");

    lv_obj_t * label;

    label = lv_label_create(lv_screen_active());
    lv_label_set_text(label, lv_tr("tiger"));

    label = lv_label_create(lv_screen_active());
    lv_label_set_text(label, lv_tr("chair"));
    lv_obj_set_y(label, 50);
}

#endif /*LV_USE_TRANSLATION && LV_BUILD_EXAMPLES*/

API¶

lv_translation.h

lv_translation_private.h