Мультиязычные интерфейсы и локализация

1) Принципы

1. Язык — не скин. Меняются тексты, форматы, направление письма, иллюстрации, юридические блоки и даже навигация.
2. Сначала ключи, потом тексты. Структурируйте смысловые ключи и параметры — переводы приходят позже.
3. Псевдолокализация — до выхода. Ловите переполнения, «жестко пришитые» строки и скрытые англицизмы.
4. Фолбэки предсказуемы. `ru-UA → ru → en`. Никаких «тихих» провалов.
5. Безопасность. Никакого HTML из перевода в DOM без санитайза; плейсхолдеры только позиционные/именованные.
6. A11y-эквивалентность. Alt-тексты, aria-лейблы, сокращения — все локализуется.

2) Стратегия локалей

Системные коды: `language-REGION` (например, `pt-BR`, `en-GB`).
Выбор локали: профиль пользователя → настройка; запасной — авто-детект по браузеру/гео (с подтверждением).
Мульти-регион: отличайте язык от права: `es-ES` ≠ `es-MX` (разные законы/платежи/лимиты).
Фолбэк-цепочка: UI — ближайший язык; правовые тексты — строго региональная версия, иначе блок и запрос подтверждения.

3) Информационная архитектура и контент

Ключевые области: навигация, CTA, ошибки, формы, подсказки, уведомления, письма, PDF/баннеры.
Текстовые расширения: резерв ширины +30–40% (немецкий/финский). Лэйаут — эластичный (flex/grid).
Тон/стиль: словарь бренда (термины, без «перевода сленга» в критичных местах).
Изображения/иконки: избегайте текста в картинках; если он нужен — храните локальные версии.

4) Архитектура i18n

Ключи: `domain.section.intent` → `payments.withdraw.error.insufficient_funds`.
Плейсхолдеры: именованные (`{amount}`, `{minutes}`), форматируется вне строки.
ICU MessageFormat: множественность, род, согласование.
Файлы: по локали и доменам (`/i18n/{locale}/{domain}.json`), чанки грузятся лениво.
Сервер/клиент: универсальный рендер, локаль в cookie + HTTP-Vary.

json
{
"betslip": {
"placed": "Ставка на сумму {amount} {currency} принята",
"timeout": "Ожидаем подтверждение… ~{seconds, plural, one {# сек} few {# сек} many {# сек} other {# сек}}"
}
}

5) Форматирование: числа, даты, валюты, единицы

js const nf = new Intl.NumberFormat('uk-UA', { style:'currency', currency:'UAH' });
nf.format(2000); // 2 000,00 ₴

const df = new Intl.DateTimeFormat('tr-TR', { dateStyle:'medium', timeStyle:'short' });
df.format(new Date());

const pl = new Intl.PluralRules('ru-RU');

Минорные единицы: храните суммы в центах/копейках; форматируйте на клиенте.
Относительное время: `Intl.RelativeTimeFormat`.
Единицы: `Intl.NumberFormat({ style:'unit', unit:'meter' })`.
Календарь/неделя: 1-й день недели и формат даты — по локали.

6) RTL и направление письма

Поддержите `dir="rtl"` для `ar`, `he`, `fa`; используйте `dir="auto"` для пользовательского контента.
Инвертируйте иконки/chevron’ы; зеркальте карусели и степперы.
Числа/символы валют — LTR-окна (избегайте смешанного BiDi хаоса).
CSS-логические свойства (`inline-start/end`) вместо left/right.

7) Формы и ввод

Имена/адреса: допускайте апострофы/диакритику/двойные фамилии.
Телефоны: E.164 хранение; маски — мягкие, с поддержкой вставки.
Адресные форматы: порядок полей по стране; индекс/штат могут отсутствовать.
Клавиатуры: `inputmode`, `autocomplete` корректные для локали.
Плейсхолдеры: примеры на локальном языке/формате.

8) Псевдолокализация и тестирование

Автоматически заменяйте строки на `【Ĥěļļő】` + удлинение `＋＋＋` (~35%).
Включайте псевдолокаль в dev-сборку как `qps-ploc`.
Скриншоты с контекстом для переводчиков: подсветка плейсхолдеров и длинных текстов.
Тестируйте: обрезки, переносы, переполнения, «жестко пришитые» строки, RTL.

9) Уведомления, письма, шаблоны

Шаблон письма и темы — на каждую локаль; разделяйте тексты и верстку.
Даты/суммы в теме — форматируются по локали.
Ссылки «Настроить уведомления» — всегда на языке письма.
SMS: кратко, без многострочных кавычек; UTM — без локализации.

10) Безопасность и надежность

Никогда не интерпретируйте перевод как HTML, используйте безопасные вставки.
Плейсхолдеры — только данные, не разметка.
Логи/метрики — бессекретные, но с локалью для трейсинга проблем.
Фолбэк при недоступности файла переводов — «тихий» (покажите английский + телеметрия).

11) Производительность

Чанки переводов по маршрутам/доменам; предзагрузка для частых.
Кеш CDN с `ETag`/`Cache-Control`.
Избегайте ререндеров при смене локали — контекст i18n с мемоизацией.

12) Специфика iGaming

Дисклеймеры и ответственная игра: формулировки зависят от страны (18+/21+, органы регуляции, линии помощи).
KYC/AML: юридически корректные термины (например, «Источник средств», «Бенефициарный владелец»), варианты падежей/родов.
Платежные методы: названия локальные (PIX, Papara, SEPA) и условия (ETA/комиссии) — строго по региону.
Коэффициенты и формат: `decimal/fractional/american` — локальные объяснения и пример.
Юридические тексты: неизменные региональные версии; запрет фолбэка на другую юрисдикцию.

13) Токены дизайн-системы (пример)

json
{
"i18n": {
"fallback": ["en"],
"rtl": ["ar", "he", "fa"],
"textExpansionPct": 0.35,
"screenshotHints": true
},
"typography": {
"lineHeight": { "ui": 1.4, "dense": 1.3 },
"hyphens": "auto",
"tabularNums": true
},
"layout": {
"minLabelWidth": 96,
"gap": { "sm": 8, "md": 12, "lg": 16 }
},
"a11y": {
"ariaMirroring": true,
"altTranslate": true,
"contrastAA": true
}
}

14) Сниппеты

ts import i18n from 'i18next';
import ICU from 'i18next-icu';
import { initReactI18next } from 'react-i18next';

i18n.use(ICU).use(initReactI18next).init({
lng: 'uk-UA',
fallbackLng: ['ru', 'en'],
load: 'languageOnly',
interpolation: { escapeValue: false },
resources: {} // пусто — грузим лениво
});

export async function loadNamespace(ns: string, lng = i18n.language){
const mod = await import(`/i18n/${lng}/${ns}.json`);
i18n.addResourceBundle(lng, ns, mod.default, true, true);
}

json
{
"notifications": "{count, plural, one {# уведомление} few {# уведомления} many {# уведомлений} other {# уведомления}}"
}

js const money = (v, c, l) => new Intl.NumberFormat(l, {style:'currency', currency:c}).format(v/100);
const rel = (v, unit, l) => new Intl.RelativeTimeFormat(l, {numeric:'auto'}).format(v, unit);
// money(250000,'EUR','de-DE') → 2.500,00 €

js const rtl = new Set(['ar','he','fa']);
document.documentElement.dir = rtl.has(locale.split('-')[0])? 'rtl': 'ltr';

js const pseudo = s => s.replace(/[aAeEiIoOuU]/g, m => ({a:'à',e:'ê',i:'ï',o:'ô',u:'û'}[m.toLowerCase()]        m)).replace(/([^\s])/g,'$1\u0301');

15) Пустые/ошибки/грейсфул деградации

Нет перевода ключа: показываем английский + логируем `missing_key`.
Нет файла локали: фолбэк и баннер «Часть интерфейса на английском».
Слишком длинный текст: мультистрочный, `line-clamp` по месту, tooltip с полным текстом.

16) Метрики и контроль качества

Coverage % по ключам/локалям (целевой ≥ 98%).
Time-to-Translate (TTT) для новых релизов.
Bug rate L10n: визуальные обрезки, RTL-дефекты, ошибочные форматы.
Reading ease (субъективный опрос) и NPS per locale.
Юридическая валидация по регионам (чеклист комплаенса).

17) Антипаттерны

Конкатенация строк в коде («Вы выиграли» + amount + «!») — ломает грамматику.
Текст в изображениях/иконках без локальных версий.
Жесткие ширины под английский.
Подмена права страны языком (использовать `es-ES` для Мексики).
Перевод через HTML из CMS без санитайза.
Один и тот же ключ с разными смыслами в разных местах.

18) QA-чек-лист

Строки и ключи

• Именованные плейсхолдеры; нет конкатенации.
• ICU-плурализация/род где нужно.
• Фолбэк-цепочка работает.

Лэйаут и доступность

• Запас ширины +30–40%; `line-clamp`, перенос слов.
• Alt/aria-лейблы локализованы.
• RTL зеркалит иконки/навигацию; числа читаемы.

Форматы

• Даты/валюты через `Intl.`; суммы из минорных единиц.
• Адрес/телефон/имя — гибкие правила по стране.

Безопасность/перформанс

• Переводы не исполняют HTML; XSS исключен.
• Ленивые чанки, кеш CDN, без лишних ререндеров.

iGaming-специфика

• Дисклеймеры/18+/линии помощи — по юрисдикции.
• Тексты KYC/AML юридически выверены.
• Платежные названия/ETA/комиссии — локальные.

19) Документация в дизайн-системе

Разделы: i18n Tokens, Guides (ICU/Plural/RTL), Patterns (Emails/SMS/Toasts), Legal Strings per Region.
Инструменты: псевдолокаль, скриншотер экранов, отчет coverage, линтер ключей.
Процесс: глоссарий, Translation Memory, контекстные скриншоты, ревью носителем языка.

Краткое резюме

Мультиязычный UI — это системная работа на уровне архитектуры, дизайна, контента и права. Организуйте ключи и фолбэки, используйте ICU и `Intl`, поддержите RTL, заранее прогоните псевдолокаль и обеспечьте юридическую корректность региональных формулировок. Тогда продукт будет чувствоваться родным — от коэффициентов и платежей до писем и справки — в каждой стране и для каждого пользователя.