Кастомные переводы

Библиотека Axe-core предоставляет мощные возможности для автоматической проверки доступности веб-приложений. Помимо стандартного набора правил, важно учитывать локализацию сообщений об ошибках, предупреждениях и рекомендациях. Кастомные переводы позволяют адаптировать вывод под конкретный язык и терминологию проекта.

Структура кастомных переводов

Axe-core использует объектную структуру для хранения текстов локализации. Каждое правило, нарушение или предупреждение содержит несколько ключевых полей:

  • help: краткое описание правила, отображаемое пользователю.
  • description: развернутое объяснение проблемы и её контекста.
  • tags: список категорий, к которым относится правило (например, wcag2a, wcag2aa).
  • impact: уровень влияния нарушения (minor, moderate, serious, critical).

Пример структуры кастомного перевода на русском:

const customTranslations = {
  "color-contrast": {
    "help": "Проверка контраста цветов",
    "description": "Элемент должен иметь достаточный контраст между текстом и фоном для обеспечения читаемости.",
    "impact": "serious",
    "tags": ["wcag2aa", "contrast"]
  },
  "label": {
    "help": "Наличие метки для элементов формы",
    "description": "Каждое поле формы должно иметь ассоциированную метку, чтобы пользователи с ассистивными технологиями могли понять его назначение.",
    "impact": "critical",
    "tags": ["wcag2a", "forms"]
  }
};

Подключение кастомных переводов

Для применения кастомных переводов используется метод axe.configure(), где через свойство i18n задаются новые локализационные строки:

import axe from 'axe-core';

axe.configure({
  i18n: {
    locale: 'ru',
    messages: customTranslations
  }
});
  • locale — идентификатор языка. Можно использовать любой уникальный код, например 'ru' для русского.
  • messages — объект с переводами для конкретных правил. Если перевод не найден, библиотека использует стандартные английские сообщения.

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

Axe-core позволяет задавать переводы не только статически, но и динамически через функции. Это полезно для случаев, когда описание правила должно зависеть от состояния элемента или страницы:

const dynamicTranslations = {
  "color-contrast": ({ value }) => ({
    help: "Проверка контраста цветов",
    description: `Контраст между цветом текста (${value.textColor}) и фоном (${value.backgroundColor}) слишком низкий.`,
    impact: "serious"
  })
};

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

Многоязычная поддержка

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

const translations = {
  ru: customTranslations,
  en: { /* стандартные или свои переводы */ }
};

function setLocale(locale) {
  axe.configure({ i18n: { locale, messages: translations[locale] } });
}

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

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

  • Для каждой кастомной локализации необходимо обеспечивать полный охват используемых правил. Отсутствующие переводы приводят к fallback на английский язык.
  • Рекомендуется использовать точные термины WCAG и избегать упрощений, чтобы сообщения оставались корректными и понятными специалистам по доступности.
  • Динамические переводы полезны для сложных правил, зависящих от стилей, размеров или контента страницы.
  • Для крупных проектов целесообразно хранить переводы в отдельном модуле и подключать их централизованно, чтобы избежать дублирования и облегчить поддержку.

Ограничения и особенности

  • Axe-core не поддерживает полностью произвольное форматирование сообщений (например, HTML внутри description), поэтому текст должен быть чистым.
  • Некоторые встроенные сообщения используют placeholders (например, {selector}), которые необходимо сохранять в кастомных переводах, иначе часть информации потеряется.
  • Поддержка RTL-языков требует проверки правильности отображения сообщений в интерфейсе, особенно для визуальных отчетов и расширений браузера.

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

Оглавление