Структура файлов для i18n

Организация переводов

Для реализации интернационализации (i18n) в проектах на основе MDX необходимо правильно структурировать файлы с переводами. Основной принцип — разделение контента по языкам и компонентам, чтобы обеспечить лёгкую поддержку и масштабируемость.

Обычно структура проекта включает следующие уровни:

/locales
  /en
    common.json
    home.json
    about.json
  /ru
    common.json
    home.json
    about.json
  • locales — корневая директория для всех переводов.
  • Языковые папки (en, ru) — содержат файлы перевода для каждого языка.
  • Файлы перевода (common.json, home.json) — разделяют контент по страницам или логическим блокам. common.json обычно содержит общие фразы интерфейса: кнопки, заголовки, подсказки.

Каждый JSON-файл должен содержать ключи и значения для локализации:

{
  "title": "Главная страница",
  "welcomeMessage": "Добро пожаловать на наш сайт"
}

Интеграция MDX с i18n

MDX позволяет использовать JSX внутри Markdown, что делает возможным динамическое получение текста из файлов переводов. Для этого обычно применяют библиотеку react-i18next.

Пример подключения:

import { useTranslation } from 'react-i18next';
import { MDXProvider } from '@mdx-js/react';

function Page() {
  const { t } = useTranslation('home'); // namespace home.json
  return (
    
      
{t('title')}

      
{t('welcomeMessage')}

    
  );
}

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

  • Используется namespace, соответствующий имени JSON-файла.
  • Функция t динамически подставляет текст на выбранном языке.
  • Внутри MDX-файлов можно использовать React-компоненты, которые уже получают переводы через useTranslation.

Структура MDX-файлов с i18n

MDX-файлы можно организовать параллельно с JSON-файлами:

/content
  /en
    home.mdx
    about.mdx
  /ru
    home.mdx
    about.mdx

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

import { useTranslation } from 'react-i18next';

export const Frontmatter = {
  title: 'home'
};

export default function HomeContent() {
  const { t } = useTranslation('home');
  return (
    <>
      
{t('title')}

      
{t('welcomeMessage')}

    
  );
}

Такой подход позволяет:

  • Отделить контент от структуры приложения.
  • Использовать одинаковую MDX-разметку для разных языков с подстановкой перевода через t.
  • Легко добавлять новые языки, создавая новые папки в locales и content.

Рекомендации по масштабированию

  1. Единая система ключей: Использовать одинаковые ключи в разных языках, чтобы избежать дублирования и путаницы.
  2. Namespace по компонентам: Делить переводы по страницам или компонентам для упрощения поиска и поддержки.
  3. Динамическая загрузка: При большом количестве языков стоит применять lazy-loading JSON-файлов, чтобы не загружать все переводы сразу.
  4. Проверка корректности: Использовать скрипты для проверки отсутствующих ключей в разных языках, чтобы интерфейс не ломался при переключении языка.

Преимущества такой структуры

  • Ясное разделение контента и логики.
  • Лёгкость расширения проекта на новые языки.
  • Возможность повторного использования MDX-компонентов с разными переводами.
  • Совместимость с современными библиотеками i18n в React.

Поддержка вложенных ключей

Для сложного контента допустимо использовать вложенные объекты в JSON:

{
  "header": {
    "title": "Главная",
    "subtitle": "Лучший контент"
  },
  "footer": {
    "contact": "Связаться с нами"
  }
}

В MDX доступ к таким ключам осуществляется через точечную нотацию:

{t('header.subtitle')}

Это упрощает структуру и позволяет группировать фразы по смысловым блокам.

Использование переменных и интерполяции

react-i18next поддерживает вставку динамических значений:

{
  "welcomeUser": "Добро пожаловать, {{name}}!"
}
{t('welcomeUser', { name: 'Алексей' })}

Такой подход особенно полезен для персонализированного контента в MDX.

Оглавление