jpirnayandZach Nelson
d53c8b0e0e
## Summary * **What is the goal of this PR?** Reduce the flash footprint of the i18n string data and tooling improvements to `gen_i18n.py`. * **What changes are included?** ### 1. `lib/I18n/I18n.cpp` — use offset-based lookup `I18n::get()` previously dereferenced a `const char* const*` pointer array. It now uses a two-field `LangStrings` struct (a flat char blob + a `uint16_t` offset table) generated for each language: ```cpp // before const char* const* strings = getStringArray(_language); return strings[index]; // after const LangStrings lang = getLanguageStrings(_language); return lang.data + lang.offsets[index]; ``` Lookup cost is unchanged — still O(1), one array load and one addition. ### 2. `scripts/gen_i18n.py` — new generated layout Each language's string data is now emitted as: - **`STRINGS_XX_DATA[]`** — a single `const char[]` blob of all strings concatenated with `\0` separators. - **`OFFSETS_XX[]`** — a `uint16_t` array of one byte-offset per `StrId` into the blob. Previously each language had a `const char* const STRINGS_XX[]` pointer array (4 bytes/entry on ESP32-C3). #### Flash savings | Table type | Size per language | 19 languages | |---|---|---| | `const char*` pointer array (before) | `339 × 4 = 1,356 B` | **25,764 B** | | `uint16_t` offset table (after) | `339 × 2 = 678 B` | **12,882 B** | | **Saved** | | **12,882 B (~12.6 KB)** | String data size is unchanged — 133,092 B across 19 languages. **Total: 158,856 B → 145,974 B** (pointer tables → offset tables). ### 3. Build-time stripping of unused strings `gen_i18n.py` now scans the `src/` and `lib/` trees for `STR_*` references and, during a PlatformIO build, automatically omits the 52 strings that are defined in YAML but never referenced in code. This further reduces the compiled output from 339 → 287 string keys per language. --- ## `gen_i18n.py` CLI reference ``` python gen_i18n.py [translations_dir [output_dir]] [options] ``` | Argument / Flag | Default | Description | |---|---|---| | `translations_dir` | `lib/I18n/translations` | Path to the per-language YAML files | | `output_dir` | `lib/I18n/` | Where to write the generated `.h` / `.cpp` files | | `--src-dirs DIR [DIR …]` | `src lib` | Directories scanned for `STR_*` usage | | `--strip-unused` | off | Remove unreferenced `STR_*` keys from generated output | | `--verbose` / `-v` | off | Print per-key INFO/WARNING messages and `Generated:` lines | The PlatformIO build (SCons `pre:` hook) calls `main(strip_unused=True)` automatically, so unused strings are always stripped from firmware builds without any manual flag. **Default run output** (no flags) shows a per-language summary table: ``` Language Code Own Fallback Unused Data (B) ------------------ ---- --- -------- ------ -------- English EN 339 0 52 5,266 Belarusian BE 310 29 52 9,673 … Total: 339 | Used in code: 287 | Never used: 52 Flash (now): 133,092 B strings + 12,882 B offset tables (uint16_t) = 145,974 B Flash (before): 133,092 B strings + 25,764 B pointer tables (ptr32) = 158,856 B Saved by offset tables: 12,882 B ``` --- ### AI Usage Did you use AI tools to help write this code? **YES** (GitHub Copilot) --------- Co-authored-by: Zach Nelson <zach@zdnelson.com>
This directory is intended for project specific (private) libraries.
PlatformIO will compile them to static libraries and link into the executable file.
The source code of each library should be placed in a separate directory
("lib/your_library_name/[Code]").
For example, see the structure of the following example libraries `Foo` and `Bar`:
|--lib
| |
| |--Bar
| | |--docs
| | |--examples
| | |--src
| | |- Bar.c
| | |- Bar.h
| | |- library.json (optional. for custom build options, etc) https://docs.platformio.org/page/librarymanager/config.html
| |
| |--Foo
| | |- Foo.c
| | |- Foo.h
| |
| |- README --> THIS FILE
|
|- platformio.ini
|--src
|- main.c
Example contents of `src/main.c` using Foo and Bar:
```
#include <Foo.h>
#include <Bar.h>
int main (void)
{
...
}
```
The PlatformIO Library Dependency Finder will find automatically dependent
libraries by scanning project source files.
More information about PlatformIO Library Dependency Finder
- https://docs.platformio.org/page/librarymanager/ldf.html