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

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

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

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

Создайте новый файл i18n.json в текущем рабочем пространстве, структура директорий выглядит следующим образом:

.
├── docs
├── i18n.json
├── package.json
├── tsconfig.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.

#Создание документов на разных языках

После выполненных выше настроек можно приступать к созданию документов на разных языках. Это очень просто — достаточно создать следующую структуру в корневой папке документации:

├── doc
│   ├── en
│   │   ├── _nav.json
│   │   ├── api
│   │   │   └── index.mdx
│   │   ├── guide
│   │   │   ├── _meta.json
│   │   │   └── start
│   │   │       ├── introduction.mdx
│   │   │       └── quick-start.mdx
│   │   └── index.md
│   └── ru
│       ├── _nav.json
│       ├── api
│       │   └── index.mdx
│       ├── guide
│       │   ├── _meta.json
│       │   └── start
│       │       ├── introduction.mdx
│       │       └── quick-start.mdx
│       └── index.md
├── i18n.json
├── package.json
├── rspress.config.ts
└── tsconfig.json

Как видно, файлы мы размещаем в папках en и ru внутри директории docs — так удобно различать версии на разных языках.

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

С помощью файла _meta.json можно задать содержимое панели навигации и сайдбара. Подробности — в разделе Автоматическое формирование навигации.

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

В конфигурации _nav.json для панели навигации можно указывать text в качестве ключа i18n, например:

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

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

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

В конфигурации _meta.json для сайдбара можно указывать label в качестве ключа i18n, например:

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

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

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

При разработке MDX или собственной темы часто приходится писать пользовательские компоненты, которым тоже нужны переведённые тексты. Как их получить?

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.