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

Библиотека Axe-core представляет собой инструмент для автоматизированного тестирования доступности веб-контента. Она интегрируется с браузером через JavaScript и позволяет выявлять нарушения стандартов доступности (WCAG) на страницах и компонентах веб-приложений. Архитектура библиотеки построена таким образом, чтобы поддерживать как браузерный, так и серверный рендеринг, включая Node.js-среду.

Установка и подключение

Для подключения Axe-core в проект используется пакет npm:

npm install axe-core --save-dev

В браузере подключение возможно через CDN:

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

После подключения можно инициировать проверку доступности на конкретной странице или элементе:

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

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

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

Формат языковых файлов

Каждый языковой файл представляет собой объект, где ключами являются идентификаторы правил (ruleId), а значениями — объект с текстами сообщений:

{
  "color-contrast": {
    "description": "Элемент должен иметь достаточный контраст текста.",
    "help": "Проверьте контраст текста и фона.",
    "helpUrl": "https://dequeuniversity.com/rules/axe/4.6/color-contrast",
    "failureSummary": "Контраст между текстом и фоном слишком низкий."
  },
  "label": {
    "description": "Каждый интерактивный элемент должен иметь метку.",
    "help": "Добавьте уникальную метку для всех интерактивных элементов.",
    "helpUrl": "https://dequeuniversity.com/rules/axe/4.6/label",
    "failureSummary": "Элемент не имеет описательной метки."
  }
}

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

  • description — краткое объяснение правила, его смысл и цель.
  • help — рекомендации по исправлению конкретного нарушения.
  • helpUrl — ссылка на официальную документацию с подробным разбором.
  • failureSummary — текст, который будет показан пользователю при обнаружении нарушения.

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

Расширение и кастомизация

Axe-core поддерживает возможность расширения стандартного набора языковых файлов. Можно создавать кастомные объекты сообщений, добавляя новые правила или переопределяя существующие:

import axe from 'axe-core';
import customLang from './axe-lang-ru.json';

axe.configure({
  locale: customLang
});

В этом случае все выводимые ошибки и предупреждения будут использовать локализованные строки, определённые в customLang.

Динамическая подгрузка языковых файлов

Для многоязычных приложений часто требуется динамическая подгрузка локализаций. Axe-core позволяет менять текущий язык во время выполнения через метод setLocale:

import axe from 'axe-core';
import langEn from './axe-lang-en.json';
import langRu from './axe-lang-ru.json';

axe.setLocale(langRu); // Смена языка на русский
axe.run(document).then(results => {
  console.log(results.violations);
});

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

Взаимодействие с кастомными компонентами

При разработке пользовательских компонентов (например, на React, Vue или Angular) важно поддерживать корректные языковые сообщения для каждой ошибки. Axe-core предоставляет API для передачи кастомных сообщений при создании правил:

axe.registerRule({
  id: 'custom-button-label',
  description: 'Кнопки должны иметь уникальную метку.',
  impact: 'serious',
  tags: ['custom'],
  test: (node) => !node.hasAttribute('aria-label'),
  options: { message: 'Добавьте aria-label для кнопки' }
});

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

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

  • Для каждого языка лучше создавать отдельный JSON-файл.
  • Использовать одинаковую структуру ключей (description, help, helpUrl, failureSummary) для совместимости.
  • При изменении стандартных сообщений рекомендуется оставлять оригинальные тексты, чтобы не потерять контекст рекомендаций.
  • Для SPA и серверных приложений реализовать динамическую смену языка через axe.setLocale.

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

Оглавление