Локализация компонентов

Локализация в библиотеке FAST Element строится вокруг идеи отделения текстового содержимого и культурных настроек от логики и визуальной структуры компонента. Такой подход позволяет использовать один и тот же компонент в разных языковых и региональных контекстах без модификации исходного кода.

FAST Element не навязывает конкретный механизм локализации, но предоставляет удобный слой абстракции через биндинги и реактивность. Текстовые ресурсы обычно выносятся в отдельные словари, а компоненты получают доступ к этим данным через свойства, контекст или DI-контейнер.

Реактивное обновление позволяет переключать язык динамически: при изменении локали компонент автоматически перерисовывает привязанные текстовые узлы и атрибуты.

Формат словарей

Словари часто организуются в виде простых объектов:

{
  ru: {
    greeting: "Здравствуйте",
    dateFormat: "DD.MM.YYYY"
  },
  en: {
    greeting: "Hello",
    dateFormat: "MM/DD/YYYY"
  }
}

Ключи отражают смысловые единицы: приветствие, подписи полей, сообщения об ошибках, сообщения интерфейса. Желательно избегать в словарях конкретных текстов, завязанных на визуальный контекст или порядок элементов. Это различие облегчает повторное использование словарей.

Связывание словарей с компонентом

Компонент получает доступ к словарю через свойство locale или контекст. Внутри шаблона текст подставляется с помощью биндинга:

<span>${x => x.t("greeting")}</span>

Метод t() выполняет поиск по активному словарю и возвращает строку. При изменении локали реактивность FAST инициирует обновление привязанного узла.

Контекст локали

FAST предоставляет механизм контекста, который позволяет объявить локаль на уровне корневого приложения и унаследовать её всеми дочерними компонентами. Такой подход исключает необходимость передавать параметры локали вручную вниз по дереву.

Контекст локали может определять:

  • активный язык;
  • fallback-язык;
  • параметры форматирования дат, чисел и валют;
  • пользовательские настройки региона.

Параметризованные строки

Многие строки требуют подстановок: количества, имен, дат. Обработка таких строк выполняется через шаблонные функции:

notifications: "{count} новых уведомлений"

Компонент передает значения при вызове t():

x.t("notifications", { count: x.count })

Подстановка может сопровождаться форматированием чисел через Intl.NumberFormat, что обеспечивает корректное отображение размера, разделителей и знаков в зависимости от языка и региона.

Форматирование дат и чисел

FAST не реализует форматирование самостоятельно, но тесно работает с Intl.* API браузера. Типичные случаи включают:

  • Intl.DateTimeFormat для дат и времени;
  • Intl.NumberFormat для чисел, валют и процентов;
  • Intl.RelativeTimeFormat для относительных интервалов;
  • Intl.PluralRules для согласования множественного числа.

Сочетание PluralRules с параметризованными строками обеспечивает корректный выбор формы слова:

ru:
  notifications_zero: "Нет уведомлений"
  notifications_one: "{count} уведомление"
  notifications_few: "{count} уведомления"
  notifications_many: "{count} уведомлений"

Правило выбирается на основе результата PluralRules.

Локализация атрибутов и aria-меток

Локализация не ограничивается видимым текстом. В компонентах присутствуют aria-метки, заголовки, атрибуты alt, placeholder, title. Все эти элементы также должны выводиться через словарь.

<input
  placeholder=${x => x.t("searchPlaceholder")}
  aria-label=${x => x.t("searchAriaLabel")}
/>

Соблюдение этого правила повышает доступность и делает компонент пригодным для международных приложений.

Динамическое переключение локали

Чтобы переключение языка происходило без перезагрузки, контейнер локали реализует событие изменения. Компоненты подписываются на это событие автоматически через реактивность FAST. После изменения локали:

  • пересчитываются биндинги;
  • обновляются текстовые узлы;
  • обновляются атрибуты и aria-метки;
  • применяются новые правила форматирования.

Динамическое переключение особенно важно для SPA-интерфейсов.

Lazy-loading словарей

В крупных приложениях словари загружаются по требованию. Такой подход снижает размер начального bundles и ускоряет загрузку. FAST-компоненты совместимы с отложенной загрузкой, если метод получения словаря возвращает Promise. После разрешения Promise инициируется обновление компонента.

async t(key) {
  const dict = await this.getDictionaryForLocale(this.locale);
  return dict[key];
}

Тестирование локализации

Тестирование включает следующие аспекты:

  • корректное отображение строк в разных локалях;
  • соблюдение правил множественного числа;
  • корректность aria-меток и доступности;
  • устойчивость к отсутствующим ключам словаря;
  • корректность переключения локали в рантайме.

Псевдолокализация применяется для выявления срезания текста, переполнений, неверных ширин контейнеров и неподдерживаемых символов.

Обработка отсутствующих ключей

Словари могут быть неполными. Распространенная стратегия — вывод fallback-текста или логирование предупреждений. Нельзя использовать пустые строки или молчаливые пропуски, поскольку они ведут к трудноуловимым дефектам интерфейса.

Вынос культурной логики

Локализация включает не только язык. Сюда относится форматирование дат, валют, единиц измерения, написание имен, порядок обращения, сортировка. Такие аспекты выносятся в отдельные вспомогательные функции или классы, которые зависят от локали. Компонент остается универсальным и не знает о конкретных форматах.

Локализация пользовательских шаблонов

Компоненты с пользовательскими слотами должны учитывать, что вложенный контент может быть локализован пользователем. Важно избегать коллизий: компонент локализует только свои собственные участки, оставляя слоты внешнему коду. Такой подход снижает связывание и повышает гибкость.

Локализация ошибок и валидации

Сообщения об ошибках обычно зависят от данных. Форматирование ошибок строится на параметризации шаблонов и выборе формы слова. Валидационные сообщения помещаются в отдельный раздел словаря или в отдельный словарь валидации, что позволяет менять формулировки без изменения логики.

Взаимодействие с сервером

В многоязычных системах сервер может предоставлять данные уже в нужной локали. Компонент должен уметь сочетать серверные данные и собственные словари. Например, сервер может отдать отформатированные даты или уже локализованные сообщения. В таких случаях компонент избегает повторной локализации.

Архитектурные рекомендации

  • Настраивать локаль в корне приложения.
  • Выносить словари в отдельные файлы.
  • Использовать Intl для форматирования.
  • Предусматривать fallback для пропущенных ключей.
  • Проверять доступность атрибутов.
  • Поддерживать динамическое переключение.
  • Тестировать через псевдолокализацию.

Систематическое соблюдение этих практик обеспечивает универсальность компонентов FAST Element и делает их пригодными для масштабных международных приложений.

Оглавление