Подключение языковых файлов

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

Структура языкового файла

Языковой файл представляет собой обычный JavaScript-объект, экспортируемый из модуля. Основная структура выглядит следующим образом:

export default {
  buttons: {
    next: "Далее",
    back: "Назад",
    cancel: "Закрыть",
    finish: "Завершить"
  },
  labels: {
    step: "Шаг",
    of: "из"
  }
};

Ключевые моменты структуры:

  • buttons — содержит подписи для кнопок навигации. Каждая кнопка должна иметь уникальный идентификатор (next, back, cancel, finish) для корректной работы внутренней логики Shepherd.js.
  • labels — хранит вспомогательные текстовые элементы, например, индикатор текущего шага (step) и общее количество шагов (of).

Дополнительно можно расширять объект любыми необходимыми текстовыми метками для кастомных кнопок или подсказок.

Подключение языкового файла в проект

Импорт языкового файла зависит от того, используется ли модульная сборка или подключение через <script>.

В модульном проекте (ES Modules)

import Shepherd from "shepherd.js";
import ruLocale from "./locales/ru.js";

const tour = new Shepherd.Tour({
  defaultStepOptions: {
    classes: "shepherd-theme-arrows",
    scrollTo: true,
  },
  locale: ruLocale
});

В объекте locale передается импортированный язык. После этого все стандартные кнопки и подсказки тура автоматически используют значения из локали.

Через подключение скрипта на страницу

Если Shepherd.js подключен через CDN:

<script src="https://cdn.jsdelivr.net/npm/shepherd.js@8.3.1/dist/js/shepherd.min.js"></script>
<script src="locales/ru.js"></script>
<script>
  const tour = new Shepherd.Tour({
    defaultStepOptions: {
      classes: 'shepherd-theme-arrows',
      scrollTo: true
    },
    locale: window.ruLocale
  });
</script>

Языковой файл должен экспортировать объект в глобальную переменную, например window.ruLocale, чтобы Shepherd.js мог его использовать.

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

Shepherd.js позволяет менять язык тура на лету, без перезагрузки страницы. Для этого достаточно изменить свойство locale у экземпляра тура:

import enLocale from "./locales/en.js";
import ruLocale from "./locales/ru.js";

tour.locale = ruLocale; // переключение на русский
tour.locale = enLocale; // переключение на английский

После установки новой локали все кнопки и стандартные надписи обновятся автоматически.

Создание собственной локали

При создании собственного языкового файла следует придерживаться следующих правил:

  1. Обязательные ключи: buttons с идентификаторами next, back, cancel, finish и labels с step и of.
  2. Уникальные идентификаторы для кастомных кнопок, если используются дополнительные элементы навигации.
  3. Соблюдение структуры вложенных объектов, чтобы Shepherd.js корректно обрабатывал переводы.

Пример расширенной локали с дополнительной кнопкой:

export default {
  buttons: {
    next: "Далее",
    back: "Назад",
    cancel: "Закрыть",
    finish: "Завершить",
    skip: "Пропустить"
  },
  labels: {
    step: "Шаг",
    of: "из"
  }
};

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

Использование нескольких языков

Для многоязычных приложений целесообразно хранить все языки в отдельной директории:

/locales
 ├─ en.js
 ├─ ru.js
 └─ fr.js

Загрузка локали может выполняться динамически через import() в зависимости от выбранного языка:

async function loadLocale(lang) {
  const localeModule = await import(`./locales/${lang}.js`);
  tour.locale = localeModule.default;
}

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

Особенности использования

  • Локали применяются только к стандартным элементам Shepherd.js. Пользовательские тексты в text шагов нужно перевести вручную.
  • При смене языка на лету кастомные кнопки, созданные с помощью addStep(), сохраняют свои тексты, если их не переопределить через новую локаль.
  • Shepherd.js не накладывает ограничений на количество языков, но рекомендуется использовать единообразную структуру объектов для совместимости с обновлениями библиотеки.

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

Оглавление