# Локализация SHiNE (текущее состояние MVP, 10.11.2026) ## Назначение SHiNE использует глобальный язык и JSON-словари. Архитектура и основные переводы RU/EN уже созданы; по ключам `ru.json` и `en.json` синхронизированы. Пользовательские подписи страниц, компонентов, полей профиля, тем, звонков и сервисных уведомлений теперь также вынесены в словари. Остаются технические исключения (журналы, названия городов, протокольные маркеры, резервные сообщения начальной загрузки до `initI18n()`); английский словарь прошёл редакторский проход: исправлены грубые машинные переводы, терминология и разметка встроенных HTML-фрагментов. Окончательная проверка всех редких состояний требует запуска приложения в браузере. Исторические заметки по этапам 1–5 ниже описывают развитие, а не текущие ограничения. С 10 ноября в основной PWA добавлен общий форматтер дат, времени, чисел и относительных дат. Диагностика PWA и меню канала больше не принимают решения по переводимым словам. ## Структура и контракты - `shine-UI/js/i18n/languages.json` — поддерживаемые языки (`default`, массив `languages`, каждый элемент `{ code, name }`). `name` указывается на родном языке. - `shine-UI/js/i18n/locales/{code}.json` — плоско-иерархические JSON-словари текстов с одинаковыми ключами, например `language.menu`. - `shine-UI/js/i18n/index.js` — единственная точка API: `initI18n`, `getLanguages`, `getLanguage`, `getLanguageName`, `setLanguage`, `onLanguageChange`, `t`. `initI18n()` загружает реестр и словари языка пользователя + fallback + ru/en (для мгновенного переключения) **до первого монтирования экрана** в `app.js`. Файлы запрашиваются с тем же build-hash, что и клиент. Словари кешируются в памяти. Если нет реестра, используется встроенный минимальный список ru/en; сетевые ошибки словарей не блокируют запуск. Правило первого выбора языка: 1. Глобальная ручная настройка `localStorage['shine-ui-language-v1']`, если язык поддерживается. 2. Первый поддерживаемый язык в `navigator.languages` (либо `navigator.language`): `ru-RU` → `ru`, `en-US` → `en`. 3. Язык по умолчанию из реестра: **английский (`en`)**. Прежняя настройка `entrySettings.language` более не является источником истины: ранее она наследовалась из профиля и не позволяла надёжно отличить ручной выбор от дефолта `ru`. Значение в `state.entrySettings.language` сохраняется временно для совместимости существующего UI, но в хранилище entry settings и снимках профилей больше не записывается. Переключение/выход из профиля не меняет язык. `setLanguage(code)` подгружает при необходимости JSON языка, меняет `document.documentElement.lang`, сохраняет выбор и уведомляет подписчиков. `app.js` — единственный владелец монтирования страниц, так что при смене языка вне экрана выбора вызывает общий `renderApp()`; экран выбора после применения сам переходит на предыдущий маршрут, без двойного монтирования. Перезагрузка страницы не требуется. `t('language.menu')` возвращает текст текущего языка. Если ключ отсутствует, используется английский словарь, затем русский, затем имя ключа; `t('key', { name: '...' })` заменяет `{name}`. Склонения и ICU MessageFormat на этапе 1 не добавляются. Строки переводов вставлять как текст (`textContent`), если данные могут быть недоверенными. Название пункта выбора языка **всегда** содержит английское `Language` после косой черты: `Язык / Language`, `Language / Language`; для новых языков также нужно добавить `language.menu` с локальной частью и `/ Language`. ## Правила сопровождения (актуальны для MVP) - Новый пользовательский текст — одновременно в `locales/ru.json` и `locales/en.json`, вызов через `t()` или `th()` для HTML (не для пользовательского HTML). Параметры `{name}`, `{amount}` должны совпадать. Для новых ключей использовать осмысленные имена, не `text_###`. - Долгоживущие массивы описаний полей и палитр создаются до `initI18n()`: их `label`/`placeholder` должны вычисляться через `get label()` / `get placeholder()` или соответствующие функции **в момент отображения**, а не через один `t()` при импорте модуля. Сырой технический id палитры, поля и статус транзакции остаются неизменными. - Для ошибок сервисов сохраняйте технический код и исходный текст для журнала. В пользовательском интерфейсе используйте `toUserMessage()`: неизвестные русскоязычные технические ошибки в режиме English показываются нейтральным переводимым сообщением. - Списки языков — в `languages.json`. Выбранный язык один на все профили. Стартовый выбор из браузера, при неизвестном — `en`. - `js/i18n/format.js`: `formatDate(value, options?)`, `formatTime(value, options?)`, `formatDateTime(value, options?)`, `formatNumber(value, options?)`, `formatRelative(value, unit, options?)`. Локаль берётся из выбранного языка и совпадающего браузерного региона при его наличии. Резервные локали: `ru-RU`, **`en-US`**. Для английских дат при `en-US` по умолчанию используется европейский порядок (в реализации `en-GB` для отображения даты), время 24-часовое; часовой пояс и точные значения не меняются. Отдельной настройки региона нет. - Вычислять форматированную строку **при отображении**, не хранить её как долгоживущую техническую константу. Для именования, сортировки и группировки использовать стабильный идентификатор (например, `YYYY-MM`), а не локализованную подпись месяца. - Управление программой — по кодам: `menuItem.id`, `manifestCode`, `swCode`, `installCode`, `subscriptionCode` и т. п., **никогда не по `item.label` / `t(...)` / `textContent`**. Переводы остаются только для вывода. Для старых локально сохранённых текстовых статусов допустима однократная нормализация в код при чтении (например, legacy push статусы). - В файлах транзакций, ответах API, ключах, адресах и пользовательских сообщениях язык не меняется. Отображение сумм может локализоваться, но парсинг ввода суммы и вычисления — нет. Дополнительный линтер для поиска русских строк пока не вводится. - После редакторской вычитки английского словаря проверять его в реальных экранах на обрезку надписей, правильность контекста и редкие сценарии. Технические логи, данные и протокольные значения не следует механически переводить как UI. - Если значение JSON содержит HTML-разметку, **сохранить все теги, вложенность, CSS-классы, `data-*` и остальные атрибуты из RU-оригинала**. Переводить только отображаемые пользователю текстовые узлы. Потеря закрывающего тега или изменение класса в словаре способно сломать UI на одном языке. Для английского использовать единые обозначения: Wallet, Sign in, Appearance, Notifications, Feed, Shining member, Turbo credits, blockchain snapshot. Проверки: `node --test shine-UI/tests/*.test.mjs`, `node --check` для изменённых JS, `python3 scripts/check_docs.py`. ## История этапов 1–5 Последующие разделы документируют прошлые шаги. Фразы «английский не готов» относятся к соответствующему **прошлому** этапу, не к текущему состоянию. Проверка инфраструктуры: `node --test shine-UI/tests/i18n-architecture.test.mjs` из корня репозитория. ## Этап 2 — русский словарь диалогов (09.11.2026) На этом этапе переносим русский текст основных подтверждений, браузерных `alert/confirm/prompt`, окна необходимости входа и общих диалоговых компонентов в раздел `dialogs` файла `locales/ru.json`. Это **не перевод интерфейса на английский**: в `en.json` пока нет соответствующих ключей. Для новых ключей `t()` ищет текущий словарь, затем словарь языка по умолчанию, затем **русский**. Это позволяет при выбранном English показывать нормальный русский текст вместо технического ключа. **Граница этапа:** обработаны литеральные подписи диалогов и часть шаблонных строк в вызовах `confirmDialog`, `openAuthRequiredModal`, `window.alert`, `window.confirm`, `window.prompt` и общих компонентах `confirm-dialog`, `auth-required-modal`, `sheet`. Не все собственные HTML-модальные окна страниц, не все строки, формируемые косвенно и не все ошибки сервера перенесены. В будущем их нужно переводить поэтапно. Тексты обычных экранов не менялись. Иерархия ключей: `dialogs.common.*`, `dialogs.components..*`, `dialogs.pages..*`, `dialogs.services..*`, `dialogs.app.*`. Часть ключей этого механического начального переноса именована `_001` и т. д. Их не нужно переименовывать без причины: они уже выступают идентификаторами. Новые ключи **называть по смыслу**, например `dialogs.pages.wallet_view.transfer_confirmation`. Пример: ```js import { t } from '../i18n/index.js'; await confirmDialog({ title: t('dialogs.pages.wallet_view.transfer_confirmation', { amount }), confirmLabel: t('dialogs.common.yes'), }); ``` ```json "transfer_confirmation": "Перевести {amount} SOL?" ``` Интерполяцию выполняет `t(key, variables)`, без множественных форм и ICU. Поля с пользовательскими данными не переводятся. Для проверки охвата этапа используется `shine-UI/tests/i18n-dialogs.test.mjs`; перед переводом на English проверять полный перечень ключей `ru.json`. ## Этап 3 — нестандартные модальные окна, русский (09.11.2026) Перенесены статические HTML-подписи, заголовки, кнопки, подсказки и accessibility-атрибуты собственных модальных окон в `dialogs.modals.<имя_файла>.*` словаря `ru.json`. Изменены окна чатов, каналов, вложений, палитры, доступа к серверам, разработчика и другие UI-диалоги. Это продолжение этапа 2: патч **накладывается поверх этапа 2**, а не вместо него. Английский для этих ключей пока не нужен — действует русский fallback. При переводе следующих окон не превращать в текстовые ключи идентификаторы состояния, параметры API и значения бизнес-логики; строки, приходящие от сервера или пользователя, остаются динамическими. Если текст собирается из динамических частей, для дальнейших языков предпочтителен единый ключ с `{variable}`, а не конкатенация фрагментов. Прежние ключи `label_###` сохранены для совместимости, но новые создавать с осмысленными именами. **Текущие границы:** этот этап охватывает статические надписи в HTML-шаблонах модальных окон и часть непосредственных подписей этих компонентов. Обычные экраны и все косвенно формируемые сообщения приложения на этом этапе не аудировались исчерпывающе. Общее правило для будущего агента — новые пользовательские надписи модальных окон сразу добавлять в `ru.json`; перевод `en.json` выполнять отдельным этапом. Проверить `node --test shine-UI/tests/i18n-architecture.test.mjs shine-UI/tests/i18n-dialogs.test.mjs`, затем синтаксис всех JS-модулей. Для конечной проверки также вручную открывать окна в браузере, в том числе с различными значениями динамических параметров. ## Этап 4 — аудит оставшихся диалогов и исправления (09.11.2026) Патч этапа 4 применяется **поверх этапа 3**. Проверены вызовы диалогов подтверждения, браузерные `alert/confirm/prompt`, собственные окна с `openSheet`, формы редактирования и настроек, предупреждения публичной истории, окна соединения устройств и легенда карты связей. Дополнительно перенесены в `ru.json` оставшиеся русские заголовки, подписи и составные предупреждения, в том числе со значениями `{name}`, `{amount}` и т. п. Новые ключи размещены преимущественно в `dialogs.remaining.*` и `dialogs.final.*`; уже использующиеся ключи предыдущих этапов оставлены без переименования. **Важные исправления совместимости:** - В `components/share-sheet.js` локальный DOM-элемент `t` переименован: иначе он перекрывал импортированную функцию перевода `t()` и мог ломать окно «Поделиться». - В `pages/channel-view.js` исправлен HTML-шаблон, где текст `${t('...')}` был обычной строкой и мог отображаться буквально. - Надписи, зависящие от языка, не следует вычислять при загрузке модуля, **до** `initI18n()`: использовать функции вроде `shiningSteps()` или `getPublicHistoryRememberLabel()` во время открытия окна. Это также важно при переключении языка без перезагрузки. - Не склеивать переводимую фразу из нескольких русских фрагментов: использовать один ключ с именованными параметрами. Недоверенные значения при вставке в `innerHTML` экранировать. Обязательная проверка при дальнейшем изменении диалогов: `node --test shine-UI/tests/i18n-architecture.test.mjs shine-UI/tests/i18n-dialogs.test.mjs shine-UI/tests/i18n-dialogs-coverage.test.mjs` и проверка синтаксиса изменённых JS. Тест охвата выявляет некоторые регрессии, но **не заменяет проверку открытия окон в браузере** с различными состояниями приложения. На данном этапе обычные тексты экранов, сообщения сервера и английские переводы ещё не покрыты полностью — это отдельные этапы. ## Этап 5 — русский и английский словари экранов Тексты страниц, компонентов и диалогов перенесены в `ru.json`; соответствующие ключи добавлены в `en.json`. Тексты в HTML-шаблонах вставляются через `th()`, которая экранирует перевод для HTML. Выбранный язык применяется при рендере страницы, а заголовки и статические наборы подписей вычисляются при обращении к ним, после загрузки словарей. Английские формулировки являются первым черновым переводом и требуют редакторской вычитки. Часть русских строк в служебном коде и отдельных нестандартных сценариях остаётся вне словарей; данные пользователей и протокольные значения переводить нельзя. При отсутствии ключа сохраняется русский fallback. Проверка `node --test shine-UI/tests/i18n-completeness.test.mjs` требует одинаковых ключей и параметров в двух словарях и проверяет статические обращения `t()`/`th()` в JavaScript. После правок запускать также весь набор `node --test shine-UI/tests/*.test.mjs`, проверку синтаксиса JS и `python3 scripts/check_docs.py`.