#Интернационализация

Чтобы в Rspress реализовать документацию на нескольких языках, нужно выполнить следующее:

1. Определите текстовые данные для I18n.
2. Настройте список языков — locales в rspress.config.ts.
3. Настройте язык по умолчанию — lang в rspress.config.ts.
4. Создайте файлы документации для каждого языка.
5. Настройте боковую панель (sidebar) и навигационную панель (navbar).
6. Используйте useI18n в пользовательских компонентах.

#Определение текстовых данных для i18n

Создайте файл i18n.json в текущем рабочем пространстве, рядом с файлом rspress.config.ts:

Определите в этом JSON-файле тексты, необходимые для интернационализации. Определение типа выглядит следующим образом:

export interface I18n {
  // key: идентификатор
  [key: string]: {
    // key: язык
    [key: string]: string;
  };
}

Например:

{
  "gettingStarted": {
    "en": "Getting Started",
    "ru": "Подготовка"
  },
  "features": {
    "en": "Features",
    "ru": "Возможности"
  },
  "guide": {
    "en": "Guide",
    "ru": "Руководство"
  }
}

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

#Настройка locales

В rspress.config.ts параметр locales настраивает информацию на уровне сайта для каждого языка, такую как lang, title и description.

import { defineConfig } from '@rspress/core';

export default defineConfig({
  // locales — массив объектов
  locales: [
    {
      lang: 'en',
      // Метка в панели навигации для переключения языков
      label: 'English',
      title: 'Rspress',
      description: 'Static Site Generator',
    },
    {
      lang: 'ru',
      label: 'Русский',
      title: 'Rspress',
      description: 'Генератор статических сайтов',
    },
  ],
});

Описание других параметров темы, связанных с интернационализацией, см. в разделе тип API.

#Настройка lang — языка по умолчанию

После настройки locales задайте язык сайта по умолчанию с помощью параметра lang:

import { defineConfig } from '@rspress/core';

export default defineConfig({
  lang: 'ru',
});

Это важно, потому что Rspress удаляет языковой префикс из маршрутов языка по умолчанию. Например, маршрут /ru/guide/getting-started преобразуется в /guide/getting-started.

#Создание документации для каждого языка

После выполнения описанной выше настройки создайте следующую структуру в корневой директории документации:

Здесь документация для разных языков находится в директориях en и ru внутри docs, что делает каждую языковую версию легко различимой.

#Настройка файлов _nav.json и _meta.json

Используйте _nav.json и _meta.json для настройки панели навигации и сайдбара. Подробнее см. в разделе Автонавигация.

#Настройка навигации _nav.json

При настройке панели навигации через _nav.json поле text может быть i18n-ключом. Например:

[
  {
    "text": "guide",
    "link": "/guide/start/introduction"
  },
  {
    "text": "api",
    "link": "/api/"
  }
]

Здесь text — это guide. Rspress переводит это значение в Guide или Руководство в зависимости от i18n.json и текущего языка.

#Настройка сайдбара _meta.json

При настройке сайдбара через файл _meta.json поле label может быть i18n-ключом. Например:

[
  {
    "type": "dir",
    "name": "start",
    "label": "gettingStarted"
  }
]

Здесь label — это gettingStarted. Rspress переводит это значение в Подготовка или Getting Started в зависимости от текущего языка.

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

При написании MDX или разработке собственной темы пользовательским компонентам также может требоваться локализованный текст. Используйте useI18n для его получения:

Rspress предоставляет хук useI18n для получения текста на нужном языке. Использование выглядит следующим образом:

import { useI18n } from '@rspress/core/runtime';

const MyComponent = () => {
  const t = useI18n();

  return <div>{t('gettingStarted')}</div>;
};

Для удобной подсказки типов вы можете настроить paths в tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "i18n": ["./i18n.json"]
    }
  }
}

Затем используйте это следующим образом в компоненте:

import { useI18n } from '@rspress/core/runtime';

const MyComponent = () => {
  const t = useI18n<typeof import('i18n')>();

  return <div>{t('gettingStarted')}</div>;
};

Таким образом вы получаете подсказки типов для всех текстовых ключей, определённых в i18n.json.