Работа с RTL-языками

Intro.js — библиотека для создания интерактивных пошаговых руководств по интерфейсу веб-приложений. Одной из ключевых задач при международной локализации является корректная работа с RTL-языками (Right-to-Left), такими как арабский, иврит и персидский. Intro.js предоставляет встроенные механизмы для адаптации интерфейса и подсказок под направление текста справа налево.

Активация RTL-режима

Для включения RTL-режима необходимо установить свойство rtl в объекте конфигурации при инициализации интро:

introJs().setOptions({
    steps: [
        {
            element: '#step1',
            intro: 'Это первый шаг',
        },
        {
            element: '#step2',
            intro: 'Это второй шаг',
        }
    ],
    rtl: true
}).start();

Особенности:

  • Установка rtl: true изменяет направление текста в подсказках и кнопках навигации.
  • Все стрелки, индикаторы и маркеры шага автоматически перестраиваются с учетом правостороннего отображения.

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

Если приложение поддерживает несколько языков, переключение между LTR и RTL может происходить динамически:

function initializeIntro(language) {
    const isRTL = ['ar', 'he', 'fa'].includes(language);
    
    introJs().setOptions({
        steps: [
            { element: '#step1', intro: 'Пример шага' },
            { element: '#step2', intro: 'Еще один шаг' }
        ],
        rtl: isRTL
    }).start();
}

initializeIntro('ar'); // Инициализация для арабского языка

Важно: При динамическом переключении необходимо пересоздавать экземпляр Intro.js, так как изменение свойства rtl на уже запущенной сессии не применится корректно.

CSS-адаптация для RTL

Intro.js использует стандартные CSS-классы для позиционирования элементов и стрелок. Для полной поддержки RTL необходимо убедиться, что:

  1. Родительский контейнер использует свойство direction: rtl; при необходимости.
  2. Переопределение классов .introjs-tooltip, .introjs-arrow и .introjs-helperLayer корректно учитывает направления.

Пример минимальной CSS-правки:

/* Переворот стрелки для RTL */
.introjs-tooltip.rtl .introjs-arrow {
    left: auto;
    right: -10px;
    transform: rotate(180deg);
}

/* Выравнивание текста */
.introjs-tooltip.rtl .introjs-tooltiptext {
    text-align: right;
}

Совет: В последних версиях Intro.js RTL-поддержка встроена, но кастомные стили интерфейса всё равно могут требовать ручной адаптации.

Управление навигационными кнопками

Intro.js автоматически переставляет кнопки “Next”, “Prev” и “Done” при включенном rtl. Однако при необходимости кастомизации можно использовать классы .introjs-button и .introjs-prevbutton:

.introjs-tooltip.rtl .introjs-prevbutton {
    float: right;
}

.introjs-tooltip.rtl .introjs-nextbutton {
    float: left;
}

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

Поддержка многоязычных подсказок

В приложениях с переключением языков важно создавать текст подсказок на соответствующем языке. Intro.js поддерживает динамическое обновление текста через setOptions:

const steps = [
    { element: '#step1', intro: translations[language].step1 },
    { element: '#step2', intro: translations[language].step2 }
];

introJs().setOptions({ steps, rtl: isRTL }).start();

Особенности:

  • Тексты могут содержать как LTR, так и RTL символы, библиотека корректно отображает направление текста внутри подсказок.
  • Для сложных смешанных интерфейсов рекомендуется проверять корректность позиционирования стрелок и кнопок вручную.

Особенности адаптации для RTL

  1. Позиционирование стрелок — стрелки автоматически отображаются справа для RTL, но при использовании кастомных подсказок могут потребоваться CSS-правки.
  2. Анимации появления — Intro.js использует простые fade/slide анимации, которые при RTL корректно инвертируются.
  3. Поддержка вложенных элементов — если шаг привязан к элементу с собственным direction, подсказка наследует этот стиль, что может приводить к неконсистентному отображению текста.

Практические рекомендации

  • Всегда проверять, что html или основной контейнер документа содержит корректное dir="rtl" при работе с RTL-языками.
  • Для многоязычных интерфейсов лучше создавать отдельные конфигурации шагов и задавать rtl в зависимости от текущего языка.
  • При сложных кастомизациях стрелок, кнопок или фона использовать отдельные CSS-классы с суффиксом .rtl для сохранения чистоты кода.
  • Тестировать интерфейс на реальных RTL-языках, так как визуальные различия могут быть значительными, особенно в мобильных версиях.

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

Intro.js корректно работает с большинством популярных фреймворков, включая React, Vue и Angular, при условии, что RTL-настройка передается через setOptions и CSS наследуется правильно.

// Пример в React
import introJs from 'intro.js';
import 'intro.js/introjs.css';

useEffect(() => {
    const intro = introJs();
    intro.setOptions({
        steps: [
            { element: '#step1', intro: 'Первый шаг' },
            { element: '#step2', intro: 'Второй шаг' }
        ],
        rtl: isRTL
    });
    intro.start();
}, [isRTL]);

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

Оглавление