Локализация компонентов

MDX сочетает в себе возможности Markdown и JSX, что делает его мощным инструментом для создания документации и интерактивных компонентов в экосистеме React. Локализация компонентов в MDX требует понимания как работы React-компонентов, так и интеграции с библиотеками интернационализации, такими как react-intl, i18next, next-i18next или formatjs.

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

Первым шагом является выбор и настройка библиотеки интернационализации. Наиболее популярный подход — использование react-intl:

import { IntlProvider, FormattedMessage } from 'react-intl';
import messagesEn from './locales/en.json';
import messagesRu from './locales/ru.json';

const messages = {
  en: messagesEn,
  ru: messagesRu
};

function App({ locale }) {
  return (
    <IntlProvider locale={locale} messages={messages[locale]}>
      <YourMDXContent />
    </IntlProvider>
  );
}

Ключевые моменты:

IntlProvider обеспечивает контекст локализации для всех вложенных компонентов.
messages хранит словари с переводами, обычно в формате JSON.
Выбор языка осуществляется через проп locale.

Использование локализованных компонентов в MDX

MDX позволяет вставлять React-компоненты прямо в Markdown-разметку. Для локализованных компонентов это выглядит так:

import { FormattedMessage } from 'react-intl';

# Пример локализованного заголовка

<FormattedMessage id="app.title" defaultMessage="Привет, мир!" />

Особенности:

id должен быть уникальным ключом для каждой строки.
defaultMessage используется как резервная строка, если перевод для текущей локали отсутствует.

Динамическая локализация через пропсы

В MDX можно передавать параметры в локализованные компоненты для динамической подстановки значений:

import { FormattedMessage } from 'react-intl';

<FormattedMessage
  id="app.greeting"
  defaultMessage="Привет, {name}!"
  values={{ name: 'Алексей' }}
/>

Пояснения:

values — объект с переменными, которые будут подставлены в строку.
Поддерживаются числа, даты и другие объекты, если используется форматирование через react-intl.

Создание собственных локализованных компонентов

Для повторного использования лучше обернуть FormattedMessage в компонент:

import { FormattedMessage } from 'react-intl';

export function Greeting({ name }) {
  return <FormattedMessage id="app.greeting" defaultMessage="Привет, {name}!" values={{ name }} />;
}

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

import { Greeting } from './components/Greeting';

<Greeting name="Екатерина" />

Преимущества:

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

Локализация Markdown-текста

MDX позволяет использовать как JSX, так и Markdown. Для локализации обычного текста Markdown применяют вспомогательные функции:

import { useIntl } from 'react-intl';

export function LocalizedParagraph({ id, defaultMessage }) {
  const intl = useIntl();
  return <p>{intl.formatMessage({ id, defaultMessage })}</p>;
}

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

import { LocalizedParagraph } from './components/LocalizedParagraph';

<LocalizedParagraph id="app.description" defaultMessage="Это пример локализованного параграфа." />

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

Позволяет локализовать блоки Markdown без конвертации их в JSX вручную.
Поддерживает форматирование сообщений через ICU-синтаксис (plural, select, date).

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

MDX часто используется для документации с интерактивными примерами. Локализация компонентов с событиями и состоянием выглядит так:

import { useState } from 'react';
import { FormattedMessage } from 'react-intl';

export function Counter() {
  const [count, setCount] = useState(0);
  return (
    <div>
      <button onCl ick={() => setCount(count + 1)}>
        <FormattedMessage id="counter.button" defaultMessage="Нажми меня" />
      </button>
      <p>
        <FormattedMessage id="counter.value" defaultMessage="Счетчик: {count}" values={{ count }} />
      </p>
    </div>
  );
}