style: format docs markdown

2026-09-09 04:13:13 +05:00
parent 46da54140c
commit 64e35f4fdf
36 changed files with 2092 additions and 1187 deletions
@@ -1,52 +1,106 @@
 # План: i18n — русский и английский

-> **СТАТУС: ВЫПОЛНЕН 25.08.2026.** Базовая локаль — английский (реестр), русский — перевод в словаре; строки инструментов в реестре переведены на английский в рамках этапа C.
+> **СТАТУС: ВЫПОЛНЕН 25.08.2026.** Базовая локаль — английский (реестр), русский
+> — перевод в словаре; строки инструментов в реестре переведены на английский в
+> рамках этапа C.

 ## 1. Что получается

-Сайт работает на двух языках: русский (базовый) и английский. Переключатель в шапке, выбор сохраняется в localStorage, тег `html lang` обновляется на клиенте. Переведено всё: каркас интерфейса, карточки инструментов, цепочки, поиск, тексты ошибок. Поиск находит инструменты по запросу на любом из двух языков независимо от активной локали.
+Сайт работает на двух языках: русский (базовый) и английский. Переключатель в
+шапке, выбор сохраняется в 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 — реестр, переводы — словари.
+- Без сегментов языка в 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.
+- 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 в тестах не трогаем.
+- 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 в шапке мгновенно меняет язык без перезагрузки; после перезагрузки выбор сохранён.
+1. Переключение RU/EN в шапке мгновенно меняет язык без перезагрузки; после
+   перезагрузки выбор сохранён.
 2. Тег html lang соответствует активной локали.
-3. Главная, каталог, страница инструмента, цепочка из трёх звеньев — везде переведено, без смеси языков.
-4. Форма параметров: подписи полей и опции select переведены у произвольных пяти инструментов из разных категорий.
-5. Битый вход (некорректный HEX в тонировании, нулевой размер) показывает ошибку на активном языке.
-6. Поиск: «повер» находит повороты при русской локали; «rotate» находит их же; при английской локали наоборот. Диакритика и ё не мешают совпадению.
+3. Главная, каталог, страница инструмента, цепочка из трёх звеньев — везде
+   переведено, без смеси языков.
+4. Форма параметров: подписи полей и опции select переведены у произвольных пяти
+   инструментов из разных категорий.
+5. Битый вход (некорректный HEX в тонировании, нулевой размер) показывает ошибку
+   на активном языке.
+6. Поиск: «повер» находит повороты при русской локали; «rotate» находит их же;
+   при английской локали наоборот. Диакритика и ё не мешают совпадению.
 7. Числа в панели информации отформатированы по локали.
-8. Скачивание, пипетка, маски, слайдеры работают одинаково на обеих локалях — функциональность не задета.
+8. Скачивание, пипетка, маски, слайдеры работают одинаково на обеих локалях —
+   функциональность не задета.

 ## 6. Критерии готовности

 - Оба словаря типобезопасны и полны; тест целостности секции tools зелёный.
- Ни одного пользовательского русского строки вне словарей (кроме тестовых describe/it).
+- Ни одного пользовательского русского строки вне словарей (кроме тестовых
+  describe/it).
 - test/check/build зелёные, смоук пройден.

 ## 7. Что сознательно не делаем