Многоязычный контент

MDX позволяет сочетать возможности Markdown и JSX, что делает его удобным инструментом для работы с многоязычным контентом в JavaScript-проектах. Организация контента на нескольких языках требует продуманного подхода к структуре файлов, компонентам локализации и динамической подгрузке переводов.

Структура проекта для локализации

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

/content
  /en
    article.mdx
  /ru
    article.mdx
  /fr
    article.mdx

Каждый MDX-файл содержит одинаковую семантику, но переведённый текст. Для удобства управления можно использовать единый компонент-обёртку, который подставляет правильный файл в зависимости от выбранного языка.

Компоненты для локализации

MDX позволяет интегрировать JSX-компоненты напрямую в текст. Для многоязычного контента удобно создавать компонент Trans или Localized, который принимает ключ перевода и динамически возвращает текст на текущем языке.

Пример компонента Trans:

import translations from './translations';

export function Trans({ id, lang }) {
  return translations[lang][id] || id;
}

Файл переводов может выглядеть так:

export default {
  en: {
    greeting: "Hello",
    intro: "Welcome to our documentation"
  },
  ru: {
    greeting: "Привет",
    intro: "Добро пожаловать в нашу документацию"
  }
};

Использование в MDX:

# <Trans id="greeting" lang="ru" />

<Trans id="intro" lang="ru" />

Динамическая загрузка переводов

Для крупных проектов важно загружать переводы по требованию, чтобы уменьшить размер бандла. MDX поддерживает динамический импорт компонентов, что позволяет реализовать подгрузку JSON с переводами только для текущего языка:

import { useEffect, useState } from 'react';

export function Trans({ id, lang }) {
  const [text, setText] = useState(id);

  useEffect(() => {
    import(`./translations/${lang}.json`).then(module => {
      setText(module.default[id] || id);
    });
  }, [id, lang]);

  return <>{text}</>;
}

Комбинирование Markdown и JSX для локализации

MDX позволяет легко вставлять компоненты внутрь текста Markdown:

# Introduction

<Trans id="intro" lang={currentLang} />

## Features

- <Trans id="feature1" lang={currentLang} />
- <Trans id="feature2" lang={currentLang} />

Такой подход обеспечивает гибкость: текст остаётся в формате Markdown, а динамический контент локализуется через JSX-компоненты.

Локализация интерактивных элементов

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

Пример кнопки с локализованным текстом:

export function LocalizedButton({ id, lang, ...props }) {
  return <button {...props}>{translations[lang][id]}</button>;
}

Использование в MDX:

<LocalizedButton id="submit" lang={currentLang} />

Управление многоязычным контентом на уровне роутинга

В проектах на Next.js или Gatsby часто применяется стратегия роутинга с языковыми префиксами:

/en/docs
/ru/docs
/fr/docs

Компоненты MDX подгружаются динамически в зависимости от языка:

import { useRouter } from 'next/router';
import Article from `../content/${router.locale}/article.mdx`;

export default function Page() {
  const router = useRouter();
  return <Article />;
}

Интеграция с системами перевода

Для крупных проектов рекомендуется использовать сторонние системы управления переводами (i18n), такие как i18next или react-intl. MDX позволяет напрямую подключать такие решения:

import { useTranslation } from 'react-i18next';

export function Trans({ id }) {
  const { t } = useTranslation();
  return <>{t(id)}</>;
}

В MDX это выглядит максимально лаконично:

# <Trans id="welcome_message" />