---
id: oled-guide
title: OLED Localization Guide
sidebar_label: OLED Localization
sidebar_position: 3
---

## 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](https://rawgit.com/ThingPulse/esp8266-oled-ssd1306/master/resources/glyphEditor.html) from the OLED library ([glyph editor source code](https://github.com/ThingPulse/esp8266-oled-ssd1306/tree/master/resources)).

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:

```c
#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:

```text
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`.

```c
#define OLED_{LANG_NAME}
```

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