Перейти к содержанию

ADR 0033: Интернационализация (i18n) — ресурсы .NET, Avalonia, ортогонально TOML

Статус: Proposed (направление зафиксировано; объём языков и миграция строк — по плану).
Дата: 2026-04-11

Связанные ADR

ADR Роль
0028 пользовательский settings.toml
0029 канон конфигурации vs UI
0032 HUD: шаблоны и ключи — не замена i18n
0027 документация и discoverability

Контекст

Текст интерфейса и сообщений сейчас в основном захардкожен в коде (в т.ч. русские строки). Для нескольких языков, смены языка в рантайме и нормального переводческого контура нужны устойчивые правила, а не дублирование длинных фраз в settings.toml или только в VM.

Путаница, которую нужно снять заранее:

  • Конфигурация (0028, 0029) — канонические ключи, числа, флаги; язык UI — настройка, но не хранилище всех переведённых строк продукта.
  • HUD и шаблоны (0032) — семантика «что показывать» может жить в TOML; формулировки для пользователя по умолчанию должны приходить из слоя локализации, а не из необязательной простыни в конфиге.

Решение (намерение)

  1. Базовый стек: .NET embedded resources (.resx) и согласованная с документацией Avalonia схема: ресурсы как источник строк для XAML и кода, установка Culture / CurrentUICulture при старте и при смене языка пользователем; генератор к ресурсам (например PublicResXFileCodeGenerator) — по соглашению репозитория, чтобы ключи были доступны из разметки и тестов.

  1. Разделение ролей:
  2. Переводимые строки UI — в ресурсах (по культурам: Resources.resx, Resources.ru.resx, …). Каталог ключей стабилен для переводчиков и CI.
  3. settings.toml — не основной файл перевода всего интерфейса; допустимы ключи выбора (например предпочитаемая культура), опциональные переопределения отдельных текстов power-user’ом — только если явно спроектировано и не ломает единый каталог переводов (см. п. 4).

  1. Код и MVVM: строки, которые формируются в ViewModel / сервисах, получать через тот же слой ресурсов или абстракцию в духе IStringLocalizer<T> / обёртки над ResourceManager — чтобы не размножать литералы и облегчить тесты (подмена культуры в тестах).

  1. Множественное число, падежи, пол: не кодировать «русские правила» вручную в каждой VM. Предпочтительно отдельные ключи ресурсов для вариантов (*_one, *_few, *_many / языкозависимая схема) или проверенная библиотека с правилами CLDR/ICU — выбор на этапе реализации первого неанглийского языка с нетривиальными plural rules; до этого достаточно простых ключей.

  1. Границы: этот ADR не требует немедленной миграции всех существующих строк; не заменяет ADR про конфигурацию; не описывает продуктовый User Guide (0027) — только встроенный UI приложения.

Последствия

  • Появление структуры *.resx, политики имён ключей, возможного шага CI «нет пропавших ключей».
  • Смена языка в рантайме потребует обновления привязок/уведомлений VM там, где текст не из {x:Static}.

Отклонённые / отложенные альтернативы

  • Все строки только в TOML — плохо для перевода, дубли, риск правок «в конфиге» вместо каталога; противоречит духу 0029 как «настройки», а не полный словарь продукта.
  • Только сторонний формат (gettext, Fluent) без оценки — отложено; переход возможен, если ResX перестанет устраивать команду или инструменты перевода.

Открытые вопросы

  • Список целевых языков v1 и порядок (сначала инфраструктура + английский, затем русский и др.).
  • Единый префикс ключей или разбиение по сборкам/фичам (Features/*).
  • Интеграция с палитрой команд и XML-доками 0018 — как не разъехаться в языках подсказок.