Skip to main content

OLED Localization Guide

Overview of Localization Steps​

This guide provides instructions for localizing an OLED display by creating custom fonts, updating relevant code files, and defining language settings. The localization process involves the following steps:

1. Create an Extended ASCII Custom Font​

Use a glyph editor to create a new font file. The easiest way is to use the online glyph editor from the OLED library (glyph editor source code).

  1. Copy and paste the existing font.
  2. Modify it according to the desired codepage and save the new font file in the graphics/font folder.

Note: The font file format differs from the common Adafruit GFX format.

2. Update the customFontTableLookup Function in Screen.h​

  1. Map the double-byte UTF-8 code to the corresponding extended ASCII character of the desired codepage by updating the customFontTableLookup function in the Screen.h file.
  2. Modify the switch (last) statement: Use the left byte from the UTF-8 code in the case label to map the character's right byte to its extended ASCII code by specifying an offset.

3. Define Language and Font in Screen.cpp​

Add language-specific font definitions using conditional compilation:

#ifdef OLED_{LANG_NAME}
#include "fonts/OLEDDisplayFonts{LANG_NAME}.h"
#endif

...

#ifdef OLED_{LANG_NAME}
#define FONT_SMALL ArialMT_Plain_10_{LANG_NAME}
#else
#define FONT_SMALL ArialMT_Plain_10
#endif

4. Configure Language Settings​

Primary Method: Define in variant/*/platformio.ini​

Language settings can be defined in the platformio.ini file under the appropriate variant directory:

build_flags =
${esp32_base.build_flags}
-D xxxxx
-D OLED_{LANG_NAME}
-I variants/xxxxx

Alternative: Define in userPrefs.h​

As an alternative to modifying platformio.ini, the language can be defined in userPrefs.h.

#define OLED_{LANG_NAME}

Both methods achieve the same result, and the choice depends on the specific project setup.