Перевод сообщений

Axe-core — это JavaScript-библиотека для автоматизированного тестирования доступности веб-приложений. Она позволяет проверять HTML-код, стили и интерактивные элементы на соответствие стандартам доступности, таким как WCAG 2.1 и ARIA. Библиотека используется как в браузере, так и в Node.js, а также интегрируется с различными фреймворками и инструментами тестирования.

Основная архитектура Axe-core строится вокруг правил (rules), которые описывают конкретные проверки элементов DOM. Каждое правило имеет уникальный идентификатор, категорию и подробное объяснение, почему нарушение доступности считается проблемой. Библиотека поддерживает настройку правил: можно отключать проверку определённых правил, добавлять свои или изменять существующие.

Подключение и инициализация

Для работы в браузере Axe-core можно подключить через CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.6.3/axe.min.js"></script>

Для Node.js используется установка через npm:

npm install axe-core

После подключения инициализация тестирования выполняется вызовом метода axe.run на корневом элементе DOM:

axe.run(document, {}, (err, results) => {
  if (err) throw err;
  console.log(results.violations);
});

Ключевые параметры метода axe.run:

  • context — объект или селектор DOM, на котором выполняется проверка.
  • options — настройки, включающие активные правила, их уровень серьёзности и исключения.
  • callback — функция обратного вызова с результатами анализа.

Структура результатов

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

  • violations — массив обнаруженных нарушений доступности. Каждый элемент включает:

    • id — уникальный идентификатор правила;
    • impact — уровень серьёзности (critical, serious, moderate, minor);
    • description — объяснение проблемы;
    • help и helpUrl — рекомендации по исправлению и ссылка на документацию;
    • nodes — элементы DOM, на которых обнаружено нарушение.

  • passes — элементы, прошедшие проверку.

  • incomplete — проверки, которые не были завершены.

  • inapplicable — правила, неприменимые к текущему контексту.

Пример работы с результатами:

axe.run(document).then(results => {
  results.violations.forEach(v => {
    console.log(`${v.id}: ${v.impact}`);
    v.nodes.forEach(node => console.log(node.html));
  });
});

Настройка правил

Axe-core предоставляет гибкую систему настройки:

  • Включение/отключение правил:
axe.run(document, {
  rules: {
    'color-contrast': { enabled: false },
    'image-alt': { enabled: true }
  }
});
  • Игнорирование элементов: через параметр exclude можно исключить определённые селекторы из проверки:
axe.run(document, {
  exclude: [['.ad-banner', '#cookie-consent']]
});
  • Пользовательские правила: возможно добавление новых правил с помощью метода axe.registerRule:
axe.registerRule({
  id: 'custom-heading',
  selector: 'h1',
  evaluate: node => node.textContent.length > 10,
  message: 'Заголовок должен содержать не менее 10 символов'
});

Интеграция с фреймворками и тестами

Для автоматизации в React, Angular или Vue можно использовать Axe-core совместно с Jest или Cypress.

Пример с Jest и Testing Library:

import { render } from '@testing-library/react';
import axe from 'axe-core';
import MyComponent from './MyComponent';

test('доступность компонента', async () => {
  const { container } = render(<MyComponent />);
  const results = await axe.run(container);
  expect(results.violations).toHaveLength(0);
});

Пример с Cypress:

cy.visit('/my-page');
cy.injectAxe();
cy.checkA11y();

Axe-core автоматически собирает все элементы страницы и проверяет их на соответствие стандартам доступности, выводя подробные отчёты.

Перевод сообщений

Результаты проверки Axe-core содержат текстовые сообщения на английском языке (help, description, impact). Для русскоязычных приложений важно локализовать эти сообщения.

  • Создание словаря переводов:
const translations = {
  'color-contrast': 'Контраст текста недостаточен',
  'image-alt': 'Отсутствует альтернативный текст для изображения',
  'critical': 'Критическая ошибка',
  'serious': 'Серьёзная ошибка'
};
  • Функция замены сообщений:
function translateResults(results, dict) {
  return results.violations.map(v => ({
    ...v,
    description: dict[v.id] || v.description,
    impact: dict[v.impact] || v.impact
  }));
}
  • Применение перевода:
axe.run(document).then(results => {
  const translated = translateResults(results, translations);
  translated.forEach(v => console.log(`${v.impact}: ${v.description}`));
});

Особенности перевода:

  1. Перевод impact помогает быстрее оценивать серьёзность проблемы.
  2. Перевод description и help делает отчёты понятными для команды разработчиков.
  3. Для многоязычных проектов можно хранить отдельные словари для каждого языка и автоматически подставлять нужный вариант.

Использование локализованных отчётов в интерфейсе

Результаты можно выводить в виде таблицы или визуальных карточек:

function renderViolations(violations) {
  violations.forEach(v => {
    const container = document.createElement('div');
    container.innerHTML = `<strong>${v.impact}</strong>: ${v.description}`;
    document.body.appendChild(container);
  });
}

Это позволяет интегрировать Axe-core в административные панели, CI/CD отчёты и инструменты контроля качества доступности.

Практические советы

  • Проверки лучше запускать на полностью загруженной странице, чтобы все динамические элементы были в DOM.
  • Использовать exclude для рекламы и виджетов, которые не влияют на доступность основной функциональности.
  • Автоматизировать тесты в CI/CD, чтобы нарушения доступности обнаруживались на ранней стадии разработки.
  • Регулярно обновлять библиотеку, так как правила доступности и рекомендации WCAG могут изменяться.

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

Оглавление