Українська локалізація yoradio: підтримка літер і переклад інтерфейсу

Це продовження статті Як зібрати і прошити yoradio на ESP32: детальний гайд для новачків. Якщо ви ще не зібрали і не запустили yoradio — почніть з першої статті, поверніться сюди, коли на дисплеї нарешті з'явиться назва станції англійською.

Тут ми будемо додавати повноцінну підтримку української мови: щоб назви станцій і треків із символами є, і, ї, ґ відображалися коректно, а не втрачалися, і щоб інтерфейс (меню, повідомлення, дні тижня, місяці) заговорив українською.

Чому базовий yoradio не показує українські літери

Офіційно yoradio підтримує тільки англійську і російську — це вибирається параметром L10N_LANGUAGE у файлі myoptions.h. Але навіть якщо поставити англійську і додати станцію з українською назвою в плейлист, ви побачите щось таке: замість "Радіо Промінь" на дисплеї буде "Радо Промнь". Літера і просто зникла. Те саме з є, ї, ґ.

Це відбувається тому, що текст на шляху від інтернет-потоку до дисплея проходить через три компоненти, і кожен з них про українські літери "не знає".

Перший компонент — конвертер UTF-8. Назви станцій і треків приходять у кодуванні UTF-8, де кирилична літера займає два байти. Дисплей же працює з однобайтовими кодуваннями. Тому в yoradio є функція utf8Rus() у файлі yoRadio/src/displays/tools/utf8Rus.cpp, яка перетворює UTF-8 → CP1251 (стандартне однобайтове кодування кирилиці). Але вона написана під російський алфавіт: обробляє тільки байти в межах U+0410–U+044F (А-я). Українські літери Є, І, Ї мають UTF-8 коди поза цим діапазоном, а Ґ — взагалі з іншим першим байтом (0xD2 замість 0xD0/0xD1). Функція їх мовчки викидає.

Другий компонент — файл шрифту glcdfont.c. Це растровий шрифт 5×7 пікселів з бібліотеки Adafruit_GFX, яким малюється більшість тексту на дисплеї. Стандартний файл містить гліфи для латиниці і російських літер (позиції 0xC0–0xFF у таблиці CP1251), але не має гліфів на позиціях, де в CP1251 живуть українські літери (0xA5 — Ґ, 0xAA — Є, 0xAF — Ї, 0xB2 — І, і так далі). Навіть якщо ми навчимо utf8Rus.cpp відправляти правильні байти, шрифт на них покаже пустоту або якийсь неочікуваний символ.

Третій компонент — файли локалізації інтерфейсу. Це набір рядків типу "Connecting...", "Volume", назви місяців і днів тижня. Вони лежать у yoRadio/locale/displayL10n_en.h та displayL10n_ru.h. Для української такого файлу немає.

Отже, щоб зробити повноцінну українську локалізацію, треба попрацювати з чотирма файлами: glcdfont.c, utf8Rus.cpp, displayL10n_ua.h, l10n.h — і додати одне визначення в myoptions.h. Далі — по кроках.

Готові файли для завантаження

Щоб не робити все з нуля, я підготував набір готових файлів. Просто завантажуйте архів, розпаковуйте, копіюйте на свої місця. Посилання:

Завантажити пакет української локалізації yoradio (ZIP)

У архіві:

glcdfont.c              — український шрифт з гліфами Є, І, Ї, Ґ
utf8Rus.cpp             — модифікована функція конвертації з підтримкою української
displayL10n_ua.h        — переклад інтерфейсу
l10n.h                  — модифікований диспетчер локалей
myoptions-patch.txt     — фрагмент для вставки у ваш myoptions.h

Далі опишу, куди що класти і чому саме так. Якщо просто хочете, щоб працювало — можете переходити відразу до розділу "Куди копіювати файли". Якщо цікаво, як воно влаштоване, і ви хочете розуміти, що саме змінюється, — читайте по порядку.

Резервна копія перед початком

Перед будь-якими змінами в системних файлах створіть резервну копію папки Documents\Arduino\yoRadio\ — просто скопіюйте її кудись з новою назвою на кшталт yoRadio_backup. Ще краще — заархівуйте оригінальну версію yoradio, яку ви скачали з GitHub, окремо. Якщо щось піде не так, буде до чого повернутися без повторного скачування.

Також зробіть бекап налаштувань з працюючого пристрою: збережіть з веб-інтерфейсу файли http://<ip_плати>/data/playlist.csv і http://<ip_плати>/data/wifi.csv. Покладіть їх в Documents\Arduino\yoRadio\data\data\ — після перепрошивки станції і збережені мережі підвантажаться назад.

Куди копіювати файли з архіву

Розпакуйте архів і скопіюйте файли на такі шляхи (заміняйте існуючі, попередньо переконавшись, що маєте резервну копію).

Файл glcdfont.c копіюйте в:

Documents\Arduino\libraries\Adafruit_GFX_Library\glcdfont.c

Це той самий шлях, де ви вже раз міняли шрифт при першій установці yoradio (стандартний yoradio-шрифт замість оригінального Adafruit-шрифту). Тепер заміняєте його на український варіант.

Файл utf8Rus.cpp копіюйте в:

Documents\Arduino\yoRadio\src\displays\tools\utf8Rus.cpp

Файл displayL10n_ua.h копіюйте в:

Documents\Arduino\yoRadio\locale\displayL10n_ua.h

Файл l10n.h копіюйте в:

Documents\Arduino\yoRadio\src\displays\tools\l10n.h

Файл myoptions-patch.txt не копіюється — це просто фрагмент коду, який треба додати у ваш існуючий myoptions.h. Про це нижче окремим кроком.

Після заміни файлів перезапустіть Arduino IDE, щоб вона підтягла нові версії.

Що всередині — короткий огляд

Якщо вам цікаво, які саме зміни ви застосовуєте, ось стисло по кожному файлу.

glcdfont.c — український шрифт

Це растровий шрифт з гліфами всіх латинських і кириличних літер, плюс службові символи yoradio (іконки WiFi, гучномовця, градуса тощо). Оригінальна yoradio-версія містить російський алфавіт на позиціях 0xC0–0xFF стандартної CP1251-розкладки. Українська версія додатково має гліфи на позиціях:

0xA5 — Ґ    0xB4 — ґ
0xAA — Є    0xBA — є
0xAF — Ї    0xBF — ї
0xB2 — І    0xB3 — і

Ці позиції в CP1251 зарезервовані саме під українські літери, і саме на них наша модифікована функція utf8Rus() буде надсилати відповідні байти.

Оригінальний український glcdfont.c у форматі yoradio створив контриб'ютор форку yoRadio-Fusion-MOD — Артур Надольський зробив мовно-специфічні шрифти для кількох європейських мов, я взяв звідти саме український варіант і додатково перевірив на сумісність з оригінальним yoradio. Дякую йому за роботу.

utf8Rus.cpp — конвертація UTF-8 → CP1251

У модифікованій версії функція utf8Rus() навчена розпізнавати три додаткові випадки, яких не було в оригіналі.

Для двобайтових послідовностей з першим байтом 0xD0 (великі літери) додано обробку:

0xD0 0x84 (Є) → байт 0xAA
0xD0 0x86 (І) → байт 0xB2
0xD0 0x87 (Ї) → байт 0xAF

Для послідовностей з 0xD1 (малі літери):

0xD1 0x94 (є) → 0xBA
0xD1 0x96 (і) → 0xB3
0xD1 0x97 (ї) → 0xBF

Додана окрема гілка для першого байта 0xD2 (яка потрібна тільки для Ґ/ґ):

0xD2 0x90 (Ґ) → 0xA5
0xD2 0x91 (ґ) → 0xB4

Плюс дотримано правил uppercase-конверсії, які yoradio застосовує в скролах з параметром uppercase: true (це стосується назв станцій, треків, плейлисту). Тобто малі є/і/ї/ґ при uppercase перетворюються на великі Є/І/Ї/Ґ, не втрачаючись і не ламаючись.

Решта функції (обробка російського алфавіту, латиниці, службових символів) залишена без змін, тобто російськомовні і англомовні станції продовжать працювати як раніше.

displayL10n_ua.h — переклад інтерфейсу

Це прямий переклад стандартного displayL10n_en.h українською. Містить рядки: назви місяців і днів тижня (короткі і повні форми), повідомлення при завантаженні і підключенні, підписи в меню і на діалогах. Кодування — UTF-8 (як і всі yoradio-файли локалі).

Один нюанс, який варто знати: у файлі перейменована константа oct (жовтень) на oct_m. У новіших версіях ESP32 core є конфлікт зі стандартним ідентифікатором oct з бібліотеки <ios>, і компіляція падає з помилкою "reference to 'oct' is ambiguous". Це вже виправлено у моєму файлі, тобто нічого додатково робити не треба.

l10n.h — диспетчер локалей

Це маленький файл-роутер, який залежно від значення L10N_LANGUAGE підключає відповідний файл локалі. Оригінальна версія знає тільки про EN і RU. У модифікованій додано гілку для UA:

#if L10N_LANGUAGE == RU
  #define L10N_PATH "../../../locale/displayL10n_ru.h"
#elif L10N_LANGUAGE == UA
  #define L10N_PATH "../../../locale/displayL10n_ua.h"
#else
  #define L10N_PATH "../../../locale/displayL10n_en.h"
#endif

Логіка збережена: якщо в папці locale/ існує файл displayL10n_custom.h, він переможе всі інші (це стандартний механізм yoradio для кастомних локалей).

Оновлюємо myoptions.h

Це єдина зміна, яку треба зробити вручну у вашому власному файлі. Відкрийте Documents\Arduino\yoRadio\myoptions.h в будь-якому редакторі (можна прямо в Arduino IDE — файл відкриється як окрема вкладка).

Знайдіть рядок:

#define L10N_LANGUAGE     EN

Замініть його на:

#define UA                3
#define L10N_LANGUAGE     UA

Перший рядок оголошує UA як числовий макрос зі значенням 3 (у оригінальному yoradio EN=1, RU=2 — тому наступне вільне число 3). Другий рядок вказує використовувати UA як активну мову.

Чому не можна просто написати #define L10N_LANGUAGE UA без визначення UA? Формально код запрацює навіть без цього — препроцесор C++ трактує невідомі ідентифікатори в #if як нуль. Але це збіг, не інженерія: якби порядок EN/RU у визначеннях був іншим, ця сама логіка мовчки завантажила б не ту гілку. Правильно — явно оголосити UA, тоді порівняння L10N_LANGUAGE == UA стає однозначним і надійним. Визначаємо саме в myoptions.h, а не в options.h — тоді оновлення yoradio у майбутньому не затре наші зміни (options.h стандартно перезаписується при оновленні, myoptions.h — ні).

Все, myoptions.h більше змінювати не треба.

Перевіряємо, що displayL10n_custom.h відсутній

Якщо у вас у папці Documents\Arduino\yoRadio\locale\ раптом лежить файл displayL10n_custom.h (наприклад, ви створили його раніше з якоюсь метою) — приберіть або перейменуйте його. Диспетчер l10n.h спочатку перевіряє наявність custom-файлу, і якщо він є, використовує його замість усіх мовних файлів. Тобто ваш новий displayL10n_ua.h буде проігнорований, поки custom-файл існує.

Стандартна папка locale\ в чистому yoradio містить лише displayL10n_en.h і displayL10n_ru.h — якщо у вас саме така картина плюс новоскопійований displayL10n_ua.h, все правильно.

Компілюємо і заливаємо

Компіляція і заливка нічим не відрізняється від того, що ви робили при першій установці. Обов'язково відкрийте yoRadio.ino, переконайтеся, що плата виставлена на ESP32 Dev Module (або ESP32 Wrover Module — залежно від вашого модуля), а розділ пам'яті — Minimal SPIFFS або No OTA. Тисніть Upload (стрілка вправо).

ESP32 Sketch Data Upload цього разу робити не треба — файлова система (SPIFFS) не змінювалася. Ми правили тільки код прошивки, тому досить одного Upload.

Компіляція буде швидшою за першу — кеш скорочує час у кілька разів. Після заливки плата сама перезавантажиться.

Що має бути після перепрошивки

Відкрийте веб-інтерфейс http://<ip_плати>/. Додайте станцію з чітко українською назвою для перевірки. Наприклад:

Hit FM Ukrainian Dance — https://online.hitfm.ua/HitFM_UkrDance
Радіо Промінь — https://radio.nrcu.gov.ua/prominstream.ogg (Українське Радіо Промінь)
Радіо НВ — https://radionv.livecdn.mediahub.com.ua/radionv-live.aac

Виберіть станцію, натисніть play. На дисплеї має з'явитися назва без пропущених літер: "Радіо Промінь", "Радіо НВ" — саме в такому вигляді, з правильними і, є, ї.

При старті плати замість "Connecting..." тепер побачите "Підключення...". У меню (якщо у вас є доступ через кнопки або енкодер) назви пунктів теж будуть українською.

Годинник відображається цифрами, тому там нічого не міняється — цифри і в українській, і в англійській однакові. Дата (якщо ваш дисплей її показує) буде на кшталт "нд, 3 сер" — коротка форма дня тижня і місяця по-українськи.

Український інтерфейс yoradio - Радіо Промінь

Український інтерфейс yoradio - Радіоточка

український інтерфейс yoradio - список станцій

Що робити, якщо не вийшло

Якщо компіляція падає з помилкою — швидше за все не всі файли скопійовані на місце або застосовані не всі зміни. Пройдіться по чеклісту:

glcdfont.c в Adafruit_GFX_Library замінений на український
utf8Rus.cpp у папці src\displays\tools\ замінений на модифікований
displayL10n_ua.h лежить у папці locale\
l10n.h у папці src\displays\tools\ замінений на модифікований
у myoptions.h є рядки #define UA 3 і #define L10N_LANGUAGE UA
у locale\ немає файлу displayL10n_custom.h
Arduino IDE перезапущено після заміни файлів

Якщо помилка "reference to 'oct' is ambiguous" — значить, замість мого файлу displayL10n_ua.h у вас якийсь інший, де ця константа не перейменована. Візьміть файл з мого архіву або в проблемному файлі перейменуйте oct на oct_m (у двох місцях: в оголошенні const char oct[] та в масиві mnths[]).

Якщо компіляція пройшла, але на дисплеї українські літери виглядають як абракадабра або порожні квадрати — швидше за все не замінений glcdfont.c у папці Adafruit_GFX, або IDE не перезапущено після заміни. Перевіряйте, копіюйте ще раз, перезапускайте IDE.

Якщо все скомпілювалося і залилося, але інтерфейс залишається англійським — перевірте myoptions.h. Ймовірно, L10N_LANGUAGE не переведений на UA, або вище є повторне визначення, яке його перекриває. Пошукайте по файлу — L10N_LANGUAGE має бути тільки одне.

Що НЕ буде працювати

Кілька моментів, про які варто попередити.

Веб-інтерфейс залишиться англійським. Локалізація стосується тільки того, що відображається на дисплеї. Веб-інтерфейс yoradio (плеєр, редактор плейлиста, налаштування) написаний в data-файлах на JavaScript і не використовує ті ж рядки, що дисплей. Щоб перекласти веб — окрема робота, там треба лізти в файли HTML/JS у папці yoRadio\data\www\. Це набагато об'ємніше і не приносить великої користі (веб-інтерфейс однаково зрозумілий).

Не всі шрифти в yoradio 5×7. Годинник у більшості конфігурацій використовує окремі GFX-шрифти зі своєї папки yoRadio\src\displays\fonts\. Але вони містять тільки цифри і двокрапку — літер там немає, тому нашого модифікованого шрифту вистачає для всього тексту, який справді треба відобразити. Якщо у вашій конфігурації якийсь спеціальний елемент виводиться іншим шрифтом і там треба буде показувати кирилицю (наприклад, свій кастомний віджет), доведеться правити ще й той шрифт окремо. Але це нестандартна ситуація.

Оновлення yoradio. При наступному оновленні прошивки (коли автор випустить нову версію) вам треба буде повторно застосувати чотири зміни: utf8Rus.cpp, displayL10n_ua.h, l10n.h, і плюс глянути, чи не мігрувала функція utf8Rus кудись ще. Файл glcdfont.c у бібліотеці Adafruit_GFX перезаписується тільки якщо ви оновлюєте саму бібліотеку — в такому разі теж треба буде замінити його знову. Тому свою збережену копію українського glcdfont.c зберігайте разом з проектом.

Подяки і посилання

Файли glcdfont.c та displayL10n_ua.h взяті з форку https://github.com/ArturNadolski/yoRadio-Fusion-MOD/. Це не єдиний внесок цього форку в екосистему yoradio: там є цілий набір мовних шрифтів (польська, угорська, грецька, чеська та інші), плюс низка інших доопрацювань. Якщо цікаво — гляньте цей репозиторій.

Патч utf8Rus.cpp і модифікація l10n.h — моя робота, зроблено спеціально для цього гайда і протестовано на робочій збірці з ST7789 SPI 320×240 і I2S DAC.

Офіційний yoradio: https://github.com/e2002/yoradio
Автор проекту — e2002.

Якщо натрапили на помилки в моєму пакеті або є ідеї, як покращити локалізацію — пишіть у коментарях під цією статтею.

Наостанок

Готово. У вас на руках повноцінне українське інтернет-радіо на ESP32, яке коректно відображає рідні назви станцій, показує день тижня і місяць українською, і не втрачає жодної літери. З урахуванням того, що офіційно проект підтримує тільки дві мови — це відчутне поліпшення, і саме такі маленькі доопрацювання роблять open-source проекти по-справжньому корисними для локальних спільнот.

Слухайте українське радіо на своєму залізі!