16 KiB
Локализация SHiNE — этап 1 (09.11.2026)
Назначение
Первый этап вводит инфраструктуру локализации без массового перевода экранов. UI остаётся на vanilla JavaScript. В этом этапе переведены только элементы выбора языка и подпись текущего языка в настройках; другие экраны, уведомления и серверные сообщения по-прежнему преимущественно русские. Полнота английского перевода не заявляется.
Структура и контракты
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; сетевые ошибки словарей не блокируют запуск.
Правило первого выбора языка:
- Глобальная ручная настройка
localStorage['shine-ui-language-v1'], если язык поддерживается. - Первый поддерживаемый язык в
navigator.languages(либоnavigator.language):ru-RU→ru,en-US→en. - Язык по умолчанию из реестра: английский (
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.
Следующие этапы
Последовательно переводить разделы интерфейса, заменяя строковые литералы на t('namespace.key'), и дополнять оба словаря; не переносить сообщения пользователей или контрактные идентификаторы API/блокчейна в локализацию. При добавлении языка требуется запись в languages.json, его locales/{code}.json и полный перевод существующих ключей. Желательно добавить автоматическую проверку равенства ключей при расширении словарей.
Проверка инфраструктуры: 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.<component>.*, dialogs.pages.<page>.*, dialogs.services.<service>.*, dialogs.app.*. Часть ключей этого механического начального переноса именована <field>_001 и т. д. Их не нужно переименовывать без причины: они уже выступают идентификаторами. Новые ключи называть по смыслу, например dialogs.pages.wallet_view.transfer_confirmation.
Пример:
import { t } from '../i18n/index.js';
await confirmDialog({
title: t('dialogs.pages.wallet_view.transfer_confirmation', { amount }),
confirmLabel: t('dialogs.common.yes'),
});
"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.