Локализовать интерфейс 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
+24
View File
@@ -1283,3 +1283,27 @@ feature layout/states
```
Если изменение требует нарушить это правило — сначала остановиться и обосновать архитектурное исключение.
## Локализация UI (обязательно для нового пользовательского текста)
- Перед правкой пользовательских диалогов прочитать `docs/UI-Design/I18N.md`.
- Никакие новые видимые человеку строки в `confirmDialog`, `openAuthRequiredModal`, `window.alert/confirm/prompt` и общих модальных компонентах не прописывать напрямую. Добавлять ключ в `shine-UI/js/i18n/locales/ru.json`, использовать `import { t } from '../i18n/index.js'` (путь зависит от расположения файла) и `t('dialogs.<component>.<semantic_key>')`.
- Для динамических значений использовать именованные переменные: `t('dialogs.wallet.send_amount', { amount })`, а в словаре — `{amount}`. Никогда не интерполировать недоверенный HTML в `innerHTML`; при необходимости экранировать его.
- Ключи должны быть стабильными: не переименовывать без одновременной правки всех вызовов и словарей. Старые `title_001` и подобные ключи этапа 2 считаются действующими, но новые ключи следует называть по смыслу.
- `ru.json` — базовый русский текст (источник строк). Пока английский перевод диалогов не готов, отсутствие ключа в `en.json` должно приводить к русскому тексту, **не** к показу имени ключа. Системный язык и выбор English при этом сохраняются как на этапе 1.
- После добавления английского перевода конкретного ключа он автоматически используется при выбранном English. Новые языки регистрируются в `languages.json` и соответствующем `locales/<code>.json`.
- Смена языка не должна менять данные профилей, пользовательские сообщения, контракты API и формат блокчейна. Не изменять архитектуру рендера: `app.js` остаётся единственным владельцем экранов.
- Проверки: `node --test shine-UI/tests/i18n-architecture.test.mjs shine-UI/tests/i18n-dialogs.test.mjs`, синтаксис JS и `python3 scripts/check_docs.py`.
### Нестандартные модальные окна — этап 3
Для HTML-шаблонов модальных окон (`modal-card`, `role="dialog"`, `openSheet`) все новые видимые русские строки хранить в `js/i18n/locales/ru.json` в группе `dialogs.modals.<component>.<semantic_key>`, а в JavaScript использовать `t()`. Отдельные `aria-label`, `placeholder`, заголовки и кнопки тоже локализовать. Сохранять HTML-разметку, escape пользовательского контента и динамические параметры. Не встраивать в перевод технические константы, API-значения и тексты сообщений пользователей. Переводы для английского добавлять в `en.json` при соответствующем этапе, до этого русский fallback предусмотрен архитектурой. Подробности: `docs/UI-Design/I18N.md`.
### Локализация диалогов — проверка после этапа 4
- Локализовать не только `confirmDialog`, но и `openSheet`, собственные HTML-диалоги, `aria-label`, `title`, `placeholder`, тексты ошибок, подписи чекбоксов и сообщения, собираемые с динамическими параметрами. Искать также `window.alert/confirm/prompt`.
- Не объявлять переменные `t` в областях, где требуется `t()` из `i18n/index.js`: даже DOM-элемент с именем `t` перекроет функцию переводов.
- **Не вызывать `t()` на верхнем уровне модуля** при создании констант отображаемого текста: словари загружаются асинхронно, а язык можно переключить позже. Собирать данные окна во время открытия (`function steps() { return [...] }`).
- Для динамических сообщений один ключ с `{variable}`. Перед передачей в HTML экранировать недоверенные имена/данные; при текстовом DOM использовать `textContent`.
- Проверять, что `${t('...')}` находится внутри обратных кавычек (template literal), а не одинарной/двойной строки.
- При правках локализации обновлять оба словаря и запускать `node --test shine-UI/tests/*.test.mjs`, `node --check` для изменённого JS и `python3 scripts/check_docs.py` из корня репозитория. Проверка `i18n-completeness.test.mjs` требует одинаковых ключей и параметров. Русский fallback сохраняется для повреждённого или недоступного английского словаря.