112 lines
9.2 KiB
Markdown
112 lines
9.2 KiB
Markdown
# План: i18n — русский и английский
|
|
|
|
> **СТАТУС: ВЫПОЛНЕН 25.08.2026.** Базовая локаль — английский (реестр), русский
|
|
> — перевод в словаре; строки инструментов в реестре переведены на английский в
|
|
> рамках этапа C.
|
|
|
|
## 1. Что получается
|
|
|
|
Сайт работает на двух языках: русский (базовый) и английский. Переключатель в
|
|
шапке, выбор сохраняется в localStorage, тег `html lang` обновляется на клиенте.
|
|
Переведено всё: каркас интерфейса, карточки инструментов, цепочки, поиск, тексты
|
|
ошибок. Поиск находит инструменты по запросу на любом из двух языков независимо
|
|
от активной локали.
|
|
|
|
Каталог и поведение не меняются: ни новых инструментов, ни изменений логики
|
|
существующих.
|
|
|
|
## 2. Решения
|
|
|
|
- Без сегментов языка в URL. Статика пререндерится на русском; переключение на
|
|
клиенте, выбор живёт в localStorage. hreflang/canonical и вторая копия страниц
|
|
для поисковиков — не в этой волне.
|
|
- Ядро не знает о локалях. Ошибки в core выбрасываются стабильными кодами
|
|
(например ERR_BAD_HEX); перевод кода в человекочитаемый текст происходит в
|
|
слое исполнителя/UI.
|
|
- Английский — базовая локаль и фолбэк: строки инструментов в реестре записаны
|
|
по-английски. Переводы живут в секции tools словарей по ключу id инструмента
|
|
(title, description, подписи параметров, подписи опций select,
|
|
тексты-результаты анализаторов); сейчас перевод — русский в ru.ts. Доступ из
|
|
компонентов только через хелперы
|
|
toolTitle/toolDescription/paramLabel/optionLabel. Так каждая строка имеет
|
|
единственный источник: en — реестр, переводы — словари.
|
|
|
|
## 3. Структура i18n-модуля
|
|
|
|
- web/src/lib/i18n/locale.svelte.ts — состояние активной локали (runes), персист
|
|
в localStorage (ключ locale, guard на SSR), обновление
|
|
document.documentElement.lang.
|
|
- web/src/lib/i18n/t.ts — функция перевода с фолбэком на базовый язык и
|
|
интерполяцией переменных вида {n}.
|
|
- web/src/lib/i18n/ru.ts и en.ts — словари одного типа Dict; тип экспортируется
|
|
из ru.ts, en.ts обязан ему соответствовать — пропущенные ключи ловятся на
|
|
компиляции.
|
|
- Секции словаря: header, home, catalog, toolPage, chain, sourceCard,
|
|
resultCard, paramsCard, textInput, textResult, download, infoPanel, dropZone,
|
|
search, ui (aria кнопок слайдера и пипетки), categories, errors, tools.
|
|
|
|
## 4. Этапы и проверки
|
|
|
|
Каждый этап заканчивается зелёными test/check/build и ревью.
|
|
|
|
- A. Инфраструктура — модуль состояния, функция перевода с фолбэком и
|
|
интерполяцией, словари-скелеты со всеми секциями (заполнены header и
|
|
categories как пилот), переключатель RU/EN в шапке, реактивный lang. Тесты:
|
|
фолбэк на ru при отсутствии ключа в en, интерполяция, персист локали.
|
|
- B. Каркас интерфейса — перенос всех хардкод-строк компонентов и маршрутов в
|
|
словари: layout (шапка, футер), главная (герой, «вернуть последний», title),
|
|
каталог, карточки источника/результата/параметров, текстовый вход и результат,
|
|
«Показать маску», DropZone/DropOverlay, кнопка скачивания (busyText),
|
|
InfoPanel плюс форматирование чисел через тег локали вместо жёсткого ru-RU,
|
|
ToolPage (легенды, «Шаг n», ошибки шага), ChainToolBlock, placeholder и пустой
|
|
результат поиска, страницы инструмента (title, 404). Обёрточные сообщения
|
|
исполнителя («Ошибка исполнения в воркере») — тоже здесь.
|
|
- C. Контент реестра — переводы 69 инструментов
|
|
(title/description/labels/options) в tools-секции словаря en; компоненты
|
|
получают строки через хелперы toolTitle/toolDescription/paramLabel/optionLabel
|
|
с фолбэком на реестр. Тест целостности: у каждого инструмента есть непустые
|
|
перевод title/description, полный набор param-ключей и подписи всех опций
|
|
select; лишние ключи словарей отсутствуют.
|
|
- D. Поиск по любому языку — нормализация запроса и полей: нижний регистр, ё→е,
|
|
снятие диакритики через NFD; скоринг против активной и базовой локали сразу,
|
|
лучший балл побеждает; сортировка совпадений через Intl.Collator активной
|
|
локали. Тесты нормализации: ё/е, диакритика, английский запрос при русской
|
|
локали и наоборот.
|
|
- E. Ошибки на кодах — около 40 мест throw в core, registry, pipeline заменяются
|
|
на коды; исполнитель переводит код в текст активной локали, неизвестные
|
|
сообщения показываются как есть. Пять тестов, матчащих русские подстроки
|
|
ошибок (executor, pipeline, registry, io, alpha), переходят на коды — это
|
|
упрощает ассерты. Русские describe/it в тестах не трогаем.
|
|
- F. Итог — полный прогон, смоук чеклист §6, архивация плана.
|
|
|
|
## 5. Смоук-чеклист
|
|
|
|
1. Переключение RU/EN в шапке мгновенно меняет язык без перезагрузки; после
|
|
перезагрузки выбор сохранён.
|
|
2. Тег html lang соответствует активной локали.
|
|
3. Главная, каталог, страница инструмента, цепочка из трёх звеньев — везде
|
|
переведено, без смеси языков.
|
|
4. Форма параметров: подписи полей и опции select переведены у произвольных пяти
|
|
инструментов из разных категорий.
|
|
5. Битый вход (некорректный HEX в тонировании, нулевой размер) показывает ошибку
|
|
на активном языке.
|
|
6. Поиск: «повер» находит повороты при русской локали; «rotate» находит их же;
|
|
при английской локали наоборот. Диакритика и ё не мешают совпадению.
|
|
7. Числа в панели информации отформатированы по локали.
|
|
8. Скачивание, пипетка, маски, слайдеры работают одинаково на обеих локалях —
|
|
функциональность не задета.
|
|
|
|
## 6. Критерии готовности
|
|
|
|
- Оба словаря типобезопасны и полны; тест целостности секции tools зелёный.
|
|
- Ни одного пользовательского русского строки вне словарей (кроме тестовых
|
|
describe/it).
|
|
- test/check/build зелёные, смоук пройден.
|
|
|
|
## 7. Что сознательно не делаем
|
|
|
|
- Сегменты языка в URL, prerender обеих локалей, hreflang/canonical.
|
|
- Транслитерация поисковых запросов ru-en.
|
|
- Третьи и дальнейшие языки (структура позволяет, добавление — отдельная волна).
|
|
- Перевод описаний коммитов, README и документации docs/.
|