Мультиязычность

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

Настройка Markdown-it для мультиязычного контента

Основная идея — использовать экземпляры Markdown-it, каждый из которых настраивается под конкретный язык. Для этого важно учитывать:

  • Локализацию текста и разметки Markdown сам по себе не хранит информацию о языке, поэтому важно поддерживать соответствие между языковой версией текста и экземпляром Markdown-it. Обычно создают объект, где ключ — это код языка, а значение — экземпляр Markdown-it с соответствующими плагинами или настройками.
const MarkdownIt = require('markdown-it');

const mdInstances = {
  en: new MarkdownIt({ html: true }),
  ru: new MarkdownIt({ html: true }),
  fr: new MarkdownIt({ html: true })
};
  • Выбор языка на лету При рендеринге контента выбирается экземпляр Markdown-it, соответствующий текущей локали.
function renderMarkdown(content, lang) {
  const md = mdInstances[lang] || mdInstances['en'];
  return md.render(content);
}

Работа с плагинами и расширениями

Markdown-it поддерживает подключение плагинов, которые расширяют функциональность стандартного синтаксиса Markdown. Для мультиязычности особенно полезны следующие подходы:

  • Плагины для кастомных синтаксисов Иногда требуется поддержка специальных элементов, например, кнопок с текстом на разных языках. Плагин может добавлять новые токены и рендереры, учитывающие локаль.
function multilingualPlugin(md) {
  md.inline.ruler.before('text', 'i18n', (state, silent) => {
    const match = state.src.slice(state.pos).match(/\[\[([a-z]{2}):([^\]]+)\]\]/);
    if (!match) return false;
    if (!silent) {
      const token = state.push('i18n_text', '', 0);
      token.meta = { lang: match[1], text: match[2] };
    }
    state.pos += match[0].length;
    return true;
  });

  md.renderer.rules.i18n_text = (tokens, idx, options, env, self) => {
    const token = tokens[idx];
    return token.meta.lang === env.lang ? token.meta.text : '';
  };
}

const md = new MarkdownIt();
md.use(multilingualPlugin);
console.log(md.render('[[en:Hello]][[ru:Привет]]', { lang: 'ru' }));
  • Поддержка локализованных ссылок и изображений Плагин или кастомный рендерер может автоматически подставлять URL в зависимости от языка.

Интернационализация заголовков, списков и таблиц

Для полноценной мультиязычной документации важно учитывать структуру документа. Markdown-it позволяет работать с токенами, что дает возможность:

  • Анализировать и изменять заголовки перед рендерингом.
  • Автоматически формировать оглавление с локализованными названиями.
  • Применять стили или CSS-классы, зависящие от языка.

Пример обработки заголовков:

const md = new MarkdownIt();

md.core.ruler.push('localize_headers', state => {
  state.tokens.forEach(token => {
    if (token.type === 'heading_open') {
      const nextToken = state.tokens[state.tokens.indexOf(token) + 1];
      if (nextToken.type === 'inline') {
        nextToken.content = localize(nextToken.content, state.env.lang);
      }
    }
  });
});

function localize(text, lang) {
  const translations = {
    'Introduction': { ru: 'Введение', fr: 'Introduction' }
  };
  return translations[text]?.[lang] || text;
}

Использование Markdown-it с фронтенд-фреймворками

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

  • Обновления контента без перезагрузки страницы Markdown рендерится на лету через JavaScript в зависимости от выбранного языка.
const content = {
  en: '# Welcome',
  ru: '# Добро пожаловать'
};

const lang = 'ru';
document.getElementById('markdown').innerHTML = mdInstances[lang].render(content[lang]);
  • Синхронизации с системами локализации Можно интегрировать Markdown-it с i18n-библиотеками, такими как i18next, чтобы автоматически подставлять переводы.

Рекомендации по поддержке нескольких языков

  1. Создавать отдельные экземпляры Markdown-it для каждого языка с индивидуальными плагинами.
  2. Использовать токены и кастомные рендереры для управления локализованным контентом.
  3. Хранить текст в структурированном виде, чтобы было удобно динамически переключать язык.
  4. Интегрировать Markdown-it с i18n-системами для сложных приложений.
  5. Контролировать вывод HTML и избегать дублирования кода при работе с разными локалями.

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

Оглавление