Language

This tutorial aims on explaining how to use the language API of the META.

Basic Idea

The basic idea is that, instead of strings, you have a different variable type that you just pass on to the already used functions that localize stuff. This different variable type is of type const MultiLang[]. Here is a simple example which will print "Hello World" in whatever language to the display:

const MultiLang helloWorld[] = {
    { LANG_EN, "Hello World" },
    { LANG_FR, "Bonjour le monde" },
    { LANG_DE, "Hallo Welt" },
};

gb.display.print(helloWorld);

As you can see, first we define the variable helloWorld which is of type const MultiLang[]. This array is populated with all the language entries we have available for our game/program, in our case English (EN), French (FR) and German (DE).

Now, when is which language used? Always, when possible, the user-set language in the loader is used. So, if the user sets, in the loader, their gamebuino to French, all the games will output French text instead of English one! If a game doesn't offer the language specified, e.g. a game doesn't support French in this example, it would fall back to the English text.

Other Uses

You can uses these MultiLang variables basically anywhere you'd expect within the library - when printing to the screen, and when using the GUI functions. Should you want to call something that requires a string and doesn't support MultiLang, you can still use gb.language.get like the follows:

const MultiLang lang_fox[] = {
    { LANG_EN, "Fox" },
    { LANG_FR, "Renard" },
    { LANG_DE, "Fuchs" },
};
const char* fox = gb.language.get(lang_fox);

And then you can use the variable fox like it is just a normal string and pass it on to other functions etc.

Intermediate usage

Now, there are special characters, like ö, à, â etc. Most of these characters are available! We are using the ISO 8859-1 charset and all these characters are available! However, this also means, that the file holding the multilang definitions with these accents needs to be either saved in the ISO-8859-1 charset (or compatible, e.g. Windows-1252), otherwise you'll have to manually input the hex, e.g. an ö being \xF6.

Recommended is, to have all your language variable definitions, in a separate .cpp file (encoded as ISO-8859-1) and have a .h include which lists all available language variables. You can see this approach in the loader with the language.cpp and language.h files.

When putting the language definitions into an external file, however, you will get compilation errors, as the compiler isn't able to detect anymore how many languages you are using in one of these language variables. For that you can set in your config-gamebuino.h (more info here) the setting LANGUAGE_DEFAULT_SIZE, e.g.

#define LANGUAGE_DEFAULT_SIZE 3

Another option is to manually pass the number of languages to gb.language.get:

const char* string = gb.language.get(lang_string, 3);

Advanced usage

Going beyond, you might need to be able to detect what the currently set language is. This might be useful if you do other fancy stuff, like swapping out sprites that contain text, have compressed text blobs etc. For that, you can use gb.language.getCurrentLang:

Gamebuino_Meta::LangCode langCode = gb.language.getCurrentLang();
if (langCode == LANG_EN) {
    // our language is English
} else if (langCode == LANG_DE) {
    // our language is German
}

Please note that this method should only be used in the rarest cases, as gb.language.get provides automatic fallback options etc. If you use this, it is also highly advised that you implement your own fallback options.

Now, you might wonder what languages are available: Basically any language! That being said, these are the only ones which you can currently set in the loader:

• English LANG_EN
• French LANG_FR
• German LANG_DE
• Spanish LANG_ES
• Dutch LANG_NL

Any questions / comments / suggestions, be sure to drop a comment down below!