easy-png-tools2/docs/plan-preview-i18n.md

План: i18n в preview (новый UI)

Статус: готов к реализации (вопросы §5 решены). Соответствует беклог-задаче «добавить i18n в preview» (docs/backlog.md). Реализация не начата.

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

Новый UI (web/src/routes/** кроме v1, web/src/lib/components/** кроме v1) переходит на существующий модуль lib/i18n: переключатель RU/EN в шапке работает по-настоящему, все строки локализованы, ошибки уже локализуются. Инфраструктура i18n уже есть и проверена (v1-ветка) — задача в том, чтобы подключить к ней preview и закрыть пробелы словарей.

До начала локализации v1 изолируется: у v1 появляется полная замороженная копия lib/i18n → lib/v1/i18n, у нового UI — своя независимая ветка lib/i18n, которую дальше меняем без оглядки на v1 (Фаза 0). Переключённая локаль (localStorage) остаётся общей для обеих версий — язык переживает переход между страницами.

2. Текущее состояние (исследование)

Уже есть

• lib/i18n/locale.svelte.ts — состояние локали (runes), персист в localStorage, обновление document.documentElement.lang.
• lib/i18n/t.ts — перевод по точечному ключу с фолбэком на базовую локаль и интерполяцией {var}.
• lib/i18n/dict.ts — тип Dict, BASE_LOCALE = "en" (база — английский, ru — перевод), LOCALES = ["ru", "en"].
• lib/i18n/ru.ts (~1351 строка) и en.ts (188 строк) — полные переводы инструментов v1 по id (title/description/params/options/results).
• lib/i18n/tool-strings.ts — хелперы для v1 (toolTitle/toolDescription/ paramLabel/optionLabel/searchDoc).
• lib/i18n/matching.ts — кросс-языковой поиск (ё→е, диакритика, скоринг).
• Тесты: i18n.test.ts, tools-i18n.test.ts, matching.test.ts, smoke-i18n.test.ts, search-coverage.test.ts.
• +layout.svelte уже вызывает initLocale() на клиенте.

Пробелы в новом UI

• LangToggle.svelte — заглушка с локальным let lang = $state("RU"), не связана с locale.svelte.ts.
• Новый UI почти целиком на хардкод-английском:
  • ~150+ строк по ~30 компонентам и маршрутам (заголовки, кнопки, аria, плейсхолдеры, подписи секций);
  • 122 инструмента с английскими title/description в lib/registry/*.ts;
  • ~60+ подписей опций select;
  • ~30 заголовков layout-групп (title: "Canvas", "Background", …);
  • вердикты анализаторов — raw English строки ("Yes — valid PNG signature."), при том что v1 возвращает ключи словаря ("verifyYes") и рендерит их через tools[id].results;
  • labelOf(id) в SchemaFields.svelte генерирует подписи полей из field ID (keepAspect → "Keep Aspect");
  • категории в catalog.ts (GROUP_LABELS) — English uppercase, хотя в dict уже есть ключи categories.X.
• Из всех новых компонентов t() вызывает только SchemaToolView.svelte, и только для ошибок (ToolError.key).

Совпадение регистров

• Новый registry и старый v1 registry используют одинаковые id инструментов (resize-png, flip-png, …) — переводы title/description из v1 ru.ts служат исходником для новой ветки lib/i18n/ru.ts (копирование данных при наполнении Фазы 2, не общий модуль).
• Расхождение: param ids в ru.ts (width/height/keepAspect) не равны field ids новоно schema (size dimension, anchor). Нужны новые переводы полей.
• ru.ts tools[id].results для анализаторов уже содержит ключи (verifyYes, grayscaleNo, orientationPortrait и т.д.).

Архитектурные ограничения

• Изоляция old↔new (isolation/no-mixed-imports): сейчас lib/i18n/ — shared. По решению задачи (Фаза 0) i18n форкается: v1 получает полную копию lib/v1/i18n, а lib/i18n переходит в ветку «new» (правило изоляции запретит старому коду импортить новый i18n). До форка в общем модуле два скрытых v1-импорта: dict.ts тянет CategoryId из ../v1/categories, tool-strings.ts — $lib/v1/registry; после форка оба живут только в копии. Новому UI нужен параллельный schema-tool-strings.ts поверх $lib/registry.
• Tone detection в SchemaTextResult.svelte: /^(yes|true)/i по value — сломается при русских вердиктах («Да», «Нет»).
• tools-i18n.test.ts покрывает только v1 TOOLS; нужен аналог для нового registry.
• known-issues.spec.ts: test.fixme("error message is localized, not a raw i18n key").

3. Как делаем

Принципы:

• Мелкие атомарные коммиты (правило AGENTS.md); самому не коммитить — коммитит разработчик после ревью.
• Изменения «снизу вверх»: сначала общий слой i18n, потом словари, потом UI.
• Каждый этап заканчивается зелёными pnpm --dir web lint + pnpm --dir web check + тесты.
• Решения по §5 зафиксированы и учитываются с первых правок словарей.

4. Фазы

Фаза 0: Форк i18n для v1 + подготовка общего слоя

Выполняется строго до остальных фаз, без изменения поведения UI. Цель — два независимых i18n-слоя: v1 получает замороженную копию, новый UI — свою ветку, которую дальше меняем свободно. На выходе фазы — зелёные lint, check, test, test:rules.

• 0.1 Форк: скопировать web/src/lib/i18n/ → web/src/lib/v1/i18n/ (полный снимок: dict.ts, en.ts, ru.ts, t.ts, locale.svelte.ts, matching.ts, tool-strings.ts + все 5 тестов). v1 работает дальше только с копией — поздние правки нового i18n её не затрагивают.
• 0.2 Привести копию к v1-канону (относительные пути от нового места):
  • копия dict.ts: импорт CategoryId ../v1/categories → ../categories (= lib/v1/categories);
  • копии тестов (tools-i18n.test.ts, search-coverage.test.ts, smoke-i18n.test.ts): ../v1/registry → ../registry (= lib/v1/registry);
  • импорт $lib/v1/registry в копии tool-strings.ts остаётся валидным;
  • перепроверить остальные относительные и $lib-пути в копии.
• 0.3 Переключить импорты старого UI: все $lib/i18n/* в routes/v1/** и lib/v1/components/** (39 импортов в 23 файлах) → $lib/v1/i18n/*.
• 0.4 Очистить новый lib/i18n/ от v1-специфики, иначе isolation поймает new→old:
  • удалить tool-strings.ts (завязан на v1-типы ParamDef/ToolEntry; для нового UI вместо него schema-tool-strings.ts, см. 0.8);
  • удалить v1-центричные тесты tools-i18n.test.ts, search-coverage.test.ts, smoke-i18n.test.ts (они импортируют ../v1/registry; живут только в копии);
  • остаются: dict.ts, en.ts, ru.ts, t.ts, locale.svelte.ts, matching.ts, i18n.test.ts, matching.test.ts.
• 0.5 Обновить правило изоляции и конфиги:
  • isolation/no-mixed-imports.js: добавить lib/i18n/** в DEFAULT_NEW (копия по-прежнему old через lib/v1/**);
  • eslint-plugins/__tests__/no-mixed-imports.test.ts: кейсы «old → i18n чисто» (строки 83–89) и «lib/i18n — shared» (строки 99–105) обновить под новую классификацию: old→новый i18n = нарушение; добавить фикстуру __fixtures__/src/lib/v1/i18n/t.ts для кейса old-копия;
  • eslint.config.js: в allowDefaultProject добавить фикстуру eslint-plugins/__fixtures__/src/lib/v1/i18n/t.ts; поправить комментарий изоляции «Общее (core/, i18n/, theme)» → «Общее (core/, theme)»;
  • eslint-plugins/README.md: убрать i18n из списка shared (§ Isolation).
• 0.6 Новый lib/i18n/dict.ts: CategoryId переключить с ../v1/categories на ../categories (новый структурно-идентичный тип) — скрытых v1-зависимостей в новом i18n не остаётся.
• 0.7 Проверка форка: pnpm --dir web lint, check, test (v1-копия тестов подхватывается vitest include: src/**/*.test.ts), test:rules; смоук: v1-страницы и оба переключателя RU/EN работают как раньше, языки обеих версий согласованы.
• 0.8 Добавить lib/i18n/schema-tool-strings.ts поверх $lib/registry (новый тип ToolEntry):
  • toolTitle(tool), toolDescription(tool) с фолбэком на registry English;
  • fieldLabel(field, id) — перевод по ключу из fields-секции словаря (см. решение C), фолбэк на labelOf(id);
  • groupLabel(title) — перевод по ключу из groups-секции словаря (см. решение A);
  • verdictText(toolId, key) — рендер вердикта по ключу;
  • verdictTone(key) — success|danger|info по имени ключа (*Yes/*No/*Portrait/*Landscape) — не по строке.
• 0.9 Расширить тип Dict (только новая ветка lib/i18n):
  • секция preview не заводится: строки нового UI живут в собственных категориях — расширяем существующие (catalog, header, dropZone, sourceCard, resultCard, paramsCard, textResult, ui) и заводим две маленькие новые: actions (Generate / Open image / Download result…) и textSource (placeholder, Try sample…);
  • новая глобальная секция fields: Record<string, string> — переводы подписей полей по ключу из схемы (решение C);
  • новая глобальная секция groups: Record<string, string> — переводы заголовков групп полей (решение A).

Фаза 1: Словари — наполнение (только новая ветка lib/i18n, v1 не трогаем)

• 1.1 Заполнить en.ts и ru.ts секциями actions, textSource, fields, groups и ключами недостающих строк в существующих секциях.
• 1.2 Проинвентаризировать разницу между 122 инструментами нового registry и ключами ru.tools: для инструментов без перевода (нет в v1) добавить title/description в ru.ts новой ветки (по категориям — несколько коммитов).
• 1.3 Добавить в ru.ts ключи fields/groups для используемых в схемах ключей полей и заголовков групп (по ходу проставления ключей в schema, Фаза 5).
• 1.4 Добавить tools[id].options[fieldId][value] для select-полей, чьи опции нужно локализовать.
• 1.5 Тест полноты (задел на Фазу 6): для каждого ключа label в schema есть перевод в обоих словарях.

Фаза 2: LangToggle → реальный locale

• 2.1 LangToggle.svelte: убрать локальный lang, подключить getLocale(), setLocale(), LOCALES. Модель — language switch из routes/v1/+layout.svelte.
• 2.2 Проверить e2e navigation.spec.ts «language toggle marks the active button» — должен проходить без изменений.

Фаза 3: Routes + layout

• 3.1 +layout.svelte: breadcrumbs через t(), динамический lang.
• 3.2 +page.svelte, list-tools/+page.svelte: footer-строка → t("header.footerNote").
• 3.3 tools/[id]/+page.svelte: «Tool not found», fallback title → t().

Фаза 4: Компоненты — основной блок (коммиты кучками по смыслу)

Все текстовые подписи в компонентах — информативные, сохраняем и переводим на t/хелперы. Каждый коммит: замена строк + lint/check.

• SchemaToolView.svelte: title/description → toolTitle()/toolDescription(), перевести TOOL SETTINGS, «Configure output» и «This tool has no schema yet.».
• SchemaSourceTile.svelte: перевести figcaption SOURCE, «choose an image»/«no source…» и alt.
• SchemaResultTile.svelte: перевести figcaption RESULT, «no result yet» и alt; суффикс «parts» — в PreviewTile.
• SchemaPreview.svelte: перевести панельный лейбл PREVIEW PANEL и meta-капшены SOURCE / RESULT / FORMAT; значения «parts»/«text» → t().
• SchemaActions.svelte: Generating…, Generate, Open image, Download result.
• SchemaFields.svelte: Reset, «updates automatically», labelOf(field.id) → fieldLabel(field).
• SchemaTextSource.svelte: placeholder, Try sample, Render text.
• SchemaTextResult.svelte: перевести лейбл RESULT у вердикта, Copy / Download .txt; tone detection → verdictTone().
• CatalogToolbar.svelte: фильтры → t("categories.all") + t("categories.X"), поисковый placeholder.
• CatalogHeader.svelte: перевести heading/lead и счётчик «TOOLS AVAILABLE».
• CatalogGroup.svelte: перевести суффикс счётчика «TOOLS».
• Dropzone.svelte: текст зоны → t("dropZone.pickDefault").
• Schema field controls (по одному или группой): Width/Height, From/To, Backing plate, Opacity, Font/Size/Color/Bold, Sans/Serif/Mono, Angle, «+ Add color», «Remove color».
• TopNav.svelte, ThemeToggle.svelte, CodeBlock.svelte, StepCard.svelte, Footer.svelte.

Фаза 5: Вердикты + ключи в schema

• 5.1 Анализаторы в registry/analyze.ts: возвращают ключи ("verifyYes" вместо raw English).
• 5.2 SchemaPreview.svelte: рендер вердикта через verdictText(tool.id, key).
• 5.3 Layout groups в registry/*.ts (решение A): title → ключ (title: "groups.canvas"); в SchemaFields.svelte — groupLabel(title). В Dict — глобальная секция groups.
• 5.4 Лейблы полей в registry/*.ts (решение C): на поле в схеме проставляется label-ключ (field.number({ label: "fields.thickness", … })), вывод в UI — fieldLabel(field) = t(label). В Dict — глобальная секция fields.
• 5.5 Категории в catalog.ts: GROUP_LABELS → t("categories.X") (ключи уже есть в dict).

Фаза 6: Тесты

• 6.1 tools-i18n.test.ts — полнота словарей для текущего registry: title/description ru для всех инструментов, каждый label-ключ схемы есть в fields, каждый groups-ключ есть в groups, без лишних ключей.
• 6.2 Фикс known-issues.spec.ts test.fixme — ошибки локализуются.
• 6.3 В новой ветке lib/i18n появится собственный smoke-i18n.test.ts (аналог v1: переключение локали, html lang, контент без смеси языков) — v1-копия теста не трогается.

Фаза 7: Кросс-языковой поиск

Переключить поиск в новом каталоге с toLowerCase() на scoreDoc()/normalizeForSearch() из matching.ts (входит в объём, см. решение D). Последний шаг, аккуратный отдельный коммит.

Фаза 8: Линтер словарей (i18n key linter)

Замена ручной проверки ключей на автоматическую. Инфраструктура уже есть: eslint-plugins/ умеет читать соседние файлы (isolation/no-mixed-imports) и гоняться фикстурами (test:rules).

• 8.1 Новое правило i18n/dict-consistency в web/eslint-plugins/. Применяется к файлам-словарям (конвенция: экспортируют Dict, лежат в lib/i18n/); новые локали подхватываются автоматически — правка правила не нужна.
• 8.2 Проверки — только warn, никогда error (пропущенный перевод не валит сборку):
  • Паритет дерева ключей: каждый ключ (dot-path a.b.c) присутствует во всех остальных локалях, не только против BASE. Нет — missing key "x.y" in en.
  • Пустые значения: "" и строка из одних пробелов — empty value "x.y" in en.
  • Паритет плейсхолдеров: у одинакового ключа набор {name} одинаковый во всех локалях — поймать потерянную при переводе переменную.
• 8.3 Цель — zero-warn. Сейчас en.ts неполный (в tools только результаты-помощники, остальной английский — из реестра), поэтому после включения будет много warn'ов: доводим en.ts до полноты ru.ts (секции + tools полностью, source — registry-English, без дрейфа). До достижения цели допускается allowlist-механизм в ядре правила для осознанных отклонений.
• 8.4 Тесты правила — фикстуры в web/eslint-plugins/__fixtures__/, док в web/eslint-plugins/README.md; включение в eslint.config.js как "warn".

Фаза 9: Множественные числа (plural-формы)

• 9.1 Тип значения словаря расширяем: string | PluralForms, где PluralForms = { other: string } & Partial<{ one, few, many }> по CLDR-правилам локали (ru: обязательны one/few/many; other — всегда, как фолбэк). Новая функция tPlural(path, n) в lib/i18n/: выбирает категорию через Intl.PluralRules(locale).select(n) и подставляет её с интерполяцией {n}.
• 9.2 Первые потребители: «часть/части/частей» (split-into-parts-png), счётчики инструментов (catalog.toolsCount), «N параметров», «N файлов».
• 9.3 Паритет в линтере (Фаза 8): если ключ — plural-объект в одной локали, он обязан быть plural-объектом во всех остальных (тип-паритет; string в одной из локалей — warn). Набор форм между локалями не сравнивается дословно — он проверяется по правилам конкретной локали (other обязателен; en: one/other, ru: one/few/many).
• 9.4 Открытый вопрос на этапе реализации: неоднозначность «объект-секция» (Record<string, string>) vs plural-объект в дереве словаря. Варианты: отдельная секция plurals в словаре, конвенция имён ключей, вывод типа из контекста. Фаза начинается с проработки этого вопроса, не с кода.

5. Решения

• A. Layout groups: заголовки групп храним i18n-ключами прямо в схеме (title: "groups.canvas"), перевод — в глобальной секции groups словаря (Dict.groups: Record<string, string>). В UI — groupLabel(title) = t(title) с фолбэком на сырой ключ.
• C. Лейблы полей: в схеме задаём i18n-ключ (field.number({ label: "fields.thickness", … })), в UI выводится перевод — fieldLabel(field) = t(label). Ключи — глобальная секция fields словаря, фолбэк на текущий labelOf(id) для несопоставленных.
• D. Объём: переводим всё сразу — и каркас, и контент реестра, и вердикты, и кросс-языковой поиск (Фаза 7). Крупные изменения кода разбиваем на небольшие атомарные шаги/коммиты.

6. Проверки

• pnpm --dir web lint
• pnpm --dir web exec svelte-check --tsconfig ./tsconfig.json
• pnpm --dir web test
• pnpm --dir web test:rules (если менялся eslint/isolation-конфиг)
• Смоук: переключатель RU/EN на новом UI; страницы каталога/инструмента, ошибка, вердикт — без смеси языков; html lang следует за локалью.