Files
SHiNE-server/docs/UI-Design/I18N.md
T

21 KiB
Raw Blame History

Локализация 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.<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.