Настройка языка интерфейса

Интерфейсные строки в Tom Select централизованы и формируются через объект локализации i18n. Он отвечает за все текстовые элементы, которые пользователь видит в выпадающем списке: состояния загрузки, пустые результаты, подсказки создания новых значений, множественные формы и служебные сообщения.

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

Структура объекта i18n

Базовая настройка языка выполняется через ключ i18n, содержащий набор строковых значений:

  • no_results — текст при отсутствии совпадений
  • loading — сообщение во время асинхронной загрузки данных
  • create — шаблон создания нового элемента
  • max_options — сообщение о достижении лимита выбора
  • optgroup_header — заголовки групп
  • remove_item — текст удаления выбранного элемента
  • deselect_option — подсказка снятия выбора

Пример конфигурации:

new TomSelect("#select", {
  i18n: {
    no_results: "Ничего не найдено",
    loading: "Загрузка...",
    create: "Добавить «%s»",
    max_options: "Достигнут лимит выбора",
    remove_item: "Удалить",
    optgroup_header: "Группа",
    deselect_option: "Снять выбор"
  }
});

Каждая строка может содержать плейсхолдеры, которые подставляются динамически в процессе работы компонента.

Подстановка динамических значений

Некоторые строки поддерживают интерполяцию значений. Наиболее распространённый формат — %s, который заменяется контекстным значением.

Пример шаблонов

  • create: "Добавить «%s»"
  • no_results: "Нет совпадений по «%s»"

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

Локализация сообщений создания элементов

Функция создания новых опций активируется при включённой настройке create. Текст формируется динамически:

create: "Создать элемент «%s»"

Поведение зависит от параметра create:

  • true — создание включено
  • функция — кастомная логика создания
  • false — создание отключено

Локализация применяется только к визуальному представлению, не влияя на механизм добавления.

Настройка сообщений загрузки данных

При использовании удалённых источников данных через load или fetch интерфейс отображает состояние загрузки.

loading: "Загрузка данных..."

Это сообщение отображается во время ожидания ответа сервера. Оно используется как fallback-индикатор, если кастомный renderer не переопределяет поведение.

Сообщения при отсутствии результатов

Одним из ключевых элементов интерфейса является состояние пустого результата поиска.

no_results: "Совпадений не найдено"

Сообщение отображается при:

  • отсутствии совпадений в локальном массиве
  • отсутствии совпадений в удалённом источнике
  • фильтрации через кастомный score или filter

Дополнительно можно использовать динамический шаблон:

no_results: "По запросу «%s» ничего не найдено"

Локализация ограничений выбора

При включении maxItems или maxOptions пользователь может достичь лимита выбора. В этом случае используется строка:

max_options: "Нельзя выбрать больше элементов"

Это сообщение не содержит плейсхолдеров и используется как статический индикатор ограничения.

Локализация удаления и управления выбранными значениями

Для элементов, уже добавленных в список, применяются отдельные строки управления:

remove_item: "Удалить элемент"
deselect_option: "Убрать выбор"

Разделение логики важно:

  • remove_item относится к уже выбранным элементам
  • deselect_option относится к выпадающему списку

Обе строки используются в разных частях UI, несмотря на схожий смысл.

Глобальная настройка локализации

Tom Select поддерживает глобальное переопределение через TomSelect.defaults.

TomSelect.defaults.i18n = {
  no_results: "Нет данных",
  loading: "Идет загрузка...",
  create: "Добавить «%s»",
  max_options: "Лимит достигнут",
  remove_item: "Удалить",
  deselect_option: "Снять"
};

Особенности глобальной настройки:

  • применяется ко всем новым экземплярам
  • не влияет на уже созданные инстансы
  • может быть переопределена локально

Приоритет локализации

Система разрешения строк работает по иерархии:

  1. Параметры экземпляра (new TomSelect)
  2. Глобальные настройки (TomSelect.defaults)
  3. Встроенные значения по умолчанию

Локальные настройки всегда имеют наивысший приоритет, что позволяет задавать язык точечно для конкретных компонентов.

Динамическое изменение языка

Tom Select не предоставляет полноценного встроенного менеджера языков, но поддерживает обновление i18n в рантайме через метод setValue конфигурации или пересоздание экземпляра.

Подходы к обновлению:

Обновление через повторную инициализацию

const select = new TomSelect("#select", {
  i18n: russianLocale
});

select.destroy();

new TomSelect("#select", {
  i18n: englishLocale
});

Частичное обновление через setOptions

select.setValue({});
select.settings.i18n = englishLocale;
select.refreshOptions(false);

Поведение зависит от версии библиотеки и способа интеграции.

Локализация и кастомные рендеры

При использовании render.option, render.item, render.no_results текстовые значения из i18n часто используются как fallback.

render: {
  no_results: function(data, escape) {
    return `<div class="no-results">
      ${this.settings.i18n.no_results}
    </div>`;
  }
}

Кастомный рендер может полностью игнорировать i18n, если необходимо реализовать полностью независимую систему локализации.

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

Tom Select допускает одновременное использование нескольких языков за счёт создания отдельных конфигураций:

const ruConfig = {
  i18n: { no_results: "Нет результатов" }
};

const enConfig = {
  i18n: { no_results: "No results found" }
};

Каждый экземпляр компонента может использовать свой набор строк без конфликта между инстансами.

Расширение набора переводимых строк

При необходимости можно расширять i18n произвольными ключами. Хотя библиотека не использует их напрямую, это полезно при интеграции с кастомными рендерами:

i18n: {
  no_results: "Нет результатов",
  custom_hint: "Используйте ввод для поиска"
}

Доступ к таким значениям осуществляется через this.settings.i18n.custom_hint.

Особенности работы с Unicode и многоязычностью

Tom Select не накладывает ограничений на кодировку строк. Поддерживаются:

  • кириллица
  • латиница
  • иероглифические системы письма
  • смешанные строки

Основное ограничение связано не с библиотекой, а с корректной обработкой HTML-escaping в кастомных рендерах, где рекомендуется использовать функцию escape для предотвращения XSS при динамических подстановках.

Поведение при отсутствии i18n

Если объект i18n не задан, используются встроенные строки по умолчанию. Они зависят от версии библиотеки и, как правило, представлены на английском языке.

Отсутствие ключей в объекте не приводит к ошибкам — система автоматически подставляет fallback-значения на уровне внутреннего конфигурационного слоя.

Оглавление