Локализовать интерфейс SHiNE на русский и английский

This commit is contained in:
AidarKC
2026-11-09 16:45:21 +03:00
parent 526941eb33
commit 405b9a91a7
133 changed files with 12464 additions and 3296 deletions
+88
View File
@@ -0,0 +1,88 @@
# Локализация 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; сетевые ошибки словарей не блокируют запуск.
Правило первого выбора языка:
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`.
## Следующие этапы
Последовательно переводить разделы интерфейса, заменяя строковые литералы на `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`.
Пример:
```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`.
+1
View File
@@ -7,6 +7,7 @@
Галерея сохранена без изменений и ещё не отражает итоговое сочетание решений. Для последующего переноса источником истины служит `DESIGN.md`, а не детали одного старого варианта. Эта галерея не является описанием текущего кода приложения.
- [Локализация UI (этап 1)](I18N.md) — языковой движок, приоритет системного языка и глобальные настройки.
- [Заявления о статусах и предупреждения о блокчейне](PROFILE_DECLARATIONS_AND_CONSENT.md) — действующие сценарии профиля, лайков и подтверждений на 06.11.2026.
## Как посмотреть