Полностью поддерживает английский язык

This commit is contained in:
AidarKC
2026-11-10 14:02:34 +03:00
parent 405b9a91a7
commit 9c30b33b39
71 changed files with 2658 additions and 1445 deletions
+19 -3
View File
@@ -1286,18 +1286,27 @@ feature layout/states
## Локализация UI (обязательно для нового пользовательского текста)
- Перед правкой пользовательских диалогов прочитать `docs/UI-Design/I18N.md`.
- Перед правкой любых пользовательских надписей или дат прочитать `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.
- `ru.json` — базовый текст, `en.json` — английский. **Каждый новый пользовательский ключ добавлять сразу в оба файла** (включая ошибки, `title`, `aria-label`, `placeholder`, кнопки, сообщения сервисов). Английский словарь прошёл редакторскую вычитку основных пользовательских сообщений; при сбое загрузки работает fallback. Новые строки переводить естественным английским, а не дословной машинной калькой.
- После добавления английского перевода конкретного ключа он автоматически используется при выбранном 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`.
### Форматирование и язык-независимая логика (MVP, 10.11.2026)
- Единственный источник выбранного языка — `js/i18n/index.js` (`getLanguage()`, `setLanguage()`). Язык общий для всех профилей. Не создавать ещё одну настройку языка/региона.
- Для отображения **дат, времени, чисел и относительных дат** использовать `js/i18n/format.js`: `formatDate`, `formatTime`, `formatDateTime`, `formatNumber`, `formatRelative`. Не фиксировать `ru-RU` или `en-US` в компонентах. Форматтер узнаёт язык при вызове, поэтому не сохранять готовый `Intl.DateTimeFormat` на верхнем уровне модуля.
- Для английского, если в браузере нет подходящего региона, базовая локаль `en-US`; пользовательские даты — европейский порядок день–месяц–год, время — 24 часа; часовой пояс браузера. Никакой дополнительной региональной настройки в MVP.
- **Никогда не сравнивать отображаемую строку (`label`, `title`, `t(...)`, `textContent`) для управления логикой.** Меню — по `id`, статусы — по стабильным кодам (`found`, `missing`, `registered`), подписи — через словари. При сериализации технических данных сохранять существующие протокольные форматы.
- При изменениях ключей поддерживать одинаковые ключи и параметры в `ru.json` и `en.json`. Пользовательские тексты из API и личных сообщений не переводить автоматически. Отдельный новый сканер строк для MVP не внедрён.
- Редакторский проход английского словаря выполнен. Для новых UI-текстов используйте единообразную терминологию: Wallet, Sign in, Appearance, Notifications, Feed, Shining member, Turbo credits, blockchain snapshot. Редкие состояния всё равно требуют ручной проверки в браузере.
### Нестандартные модальные окна — этап 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`.
Для HTML-шаблонов модальных окон (`modal-card`, `role="dialog"`, `openSheet`) все новые видимые русские строки хранить в `js/i18n/locales/ru.json` в группе `dialogs.modals.<component>.<semantic_key>`, а в JavaScript использовать `t()`. Отдельные `aria-label`, `placeholder`, заголовки и кнопки тоже локализовать. Сохранять HTML-разметку, escape пользовательского контента и динамические параметры. Не встраивать в перевод технические константы, API-значения и тексты сообщений пользователей. Переводы для английского добавлять сразу вместе с ключом в `ru.json`; fallback предусмотрен только для сбоев и старых данных. Подробности: `docs/UI-Design/I18N.md`.
### Локализация диалогов — проверка после этапа 4
@@ -1306,4 +1315,11 @@ feature layout/states
- **Не вызывать `t()` на верхнем уровне модуля** при создании констант отображаемого текста: словари загружаются асинхронно, а язык можно переключить позже. Собирать данные окна во время открытия (`function steps() { return [...] }`).
- Для динамических сообщений один ключ с `{variable}`. Перед передачей в HTML экранировать недоверенные имена/данные; при текстовом DOM использовать `textContent`.
- Проверять, что `${t('...')}` находится внутри обратных кавычек (template literal), а не одинарной/двойной строки.
- Если в JSON-переводе есть встроенный HTML, сохранять структуру тегов, CSS-классы, `data-*` и все остальные атрибуты побуквенно как в русском оригинале. Переводить только видимый текст. Не превращать `<span class="x">...</span>` в повреждённый HTML.
- При правках локализации обновлять оба словаря и запускать `node --test shine-UI/tests/*.test.mjs`, `node --check` для изменённого JS и `python3 scripts/check_docs.py` из корня репозитория. Проверка `i18n-completeness.test.mjs` требует одинаковых ключей и параметров. Русский fallback сохраняется для повреждённого или недоступного английского словаря.
## Замечание для локализации (10.11.2026)
- Не вычислять `t()` при объявлении глобальной константы, если её текст зависит от текущего языка. Для экспортируемых `PALETTE_ROLES`, `PALETTE_PRESETS`, `profileFieldDefs` и других списков использовать ленивые геттеры `get label()` / `get placeholder()` либо вычисление при отрисовке.
- Все новые видимые строки (в том числе `aria-label`, сообщения звонков и подписи HTML-шаблонов) добавлять сразу в **оба** словаря. Для HTML-шаблонов использовать `th()`, если нужен экранированный текст.
- Не менять строки API, содержимое блокчейна, внутренние коды ошибок, сообщения пользователя и маркеры совместимости ради локализации. Сервисные ошибки переводить на границе UI; скрывать неизвестные технические фразы в английском интерфейсе вместо демонстрации русского текста.