> For AI agents: the complete documentation index is available at /rspress-russian/llms.txt, the full documentation bundle is available at /rspress-russian/llms-full.txt.

# i18n

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

1. Настройте список языков и язык по умолчанию в `rspress.config.ts`.
2. Создайте файлы документации и навигации для каждого языка.

Если пользовательским компонентам нужен переведённый текст или вы хотите изменить встроенные тексты интерфейса, обратитесь к необязательным разделам ниже.

## Настройка `rspress.config.ts`

Отредактируйте `rspress.config.ts`, чтобы настроить:

- [`locales`](/rspress-russian/api/config/config-basic.md#locales): поддерживаемые языки и информацию уровня сайта для каждого языка, например `title` и `description`.
- [`lang`](/rspress-russian/api/config/config-basic.md#lang): язык сайта по умолчанию. Его значение должно совпадать с одним из значений `lang` в `locales`.

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

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

:::tip

Rspress удаляет языковой префикс из маршрутов языка по умолчанию. При `lang: 'ru'` маршрут `/ru/guide/start/introduction` превращается в `/guide/start/introduction`, а английский маршрут сохраняет префикс: `/en/guide/start/introduction`.

:::

:::warning

`themeConfig.locales` также содержит все поля из `locales`, однако в будущем этот параметр будет удалён. Вместо него используйте `locales`.

:::

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

Создайте директорию для каждого языка в корневом каталоге документации. Имена директорий должны совпадать со значениями `lang` в `locales`:

```tree
├── docs
│   ├── 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
├── package.json
├── rspress.config.ts
└── tsconfig.json
```

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

Внутри каждой языковой директории используйте `_nav.json` и `_meta.json` для настройки панели навигации и сайдбара. Подробнее см. в разделе [Автонавигация](/rspress-russian/guide/basic/auto-nav-sidebar.md).

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

В `_nav.json` каждого языка задайте в поле `"text"` текст на этом языке:


**docs/en/_nav.json**

```json
[
  {
    "text": "Guide",
    "link": "/guide/start/introduction"
  },
  {
    "text": "API",
    "link": "/api/"
  }
]
```


**docs/ru/_nav.json**

```json
[
  {
    "text": "Руководство",
    "link": "/guide/start/introduction"
  },
  {
    "text": "API",
    "link": "/api/"
  }
]
```


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

Аналогично задайте в поле `"label"` текст для каждого языка:


**docs/en/guide/_meta.json**

```json
[
  {
    "type": "dir",
    "name": "start",
    "label": "Getting Started"
  }
]
```


**docs/ru/guide/_meta.json**

```json
[
  {
    "type": "dir",
    "name": "start",
    "label": "Подготовка"
  }
]
```


Для таких языковых файлов навигации отдельные текстовые данные i18n не нужны.

## Определение текстовых данных для i18n (необязательно)

Описанной выше настройки достаточно для многоязычного сайта документации. Если пользовательским компонентам нужен переведённый текст, определите ключ, например `welcomeMessage`, и укажите значение для каждого языка.

Rspress принимает одни и те же текстовые данные двумя способами.

:::tip

Выберите либо `i18n.json`, либо `i18nSource`; оба способа сразу не нужны.

:::


**i18n.json**

Создайте файл `i18n.json` рядом с `rspress.config.ts`. Каждый ключ сопоставляет коды языков с переведённым текстом:
```json title="i18n.json"
{
  "welcomeMessage": {
    "en": "Welcome",
    "ru": "Добро пожаловать"
  }
}
```


**i18nSource**

Либо поместите те же данные в параметр `i18nSource` в `rspress.config.ts`. Файл `i18n.json` в этом случае не нужен:
```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  i18nSource: {
    welcomeMessage: {
      en: 'Welcome',
      ru: 'Добро пожаловать',
    },
  },
});
```


Если настроены оба способа, при совпадении ключа и языка приоритет имеет объектная форма `i18nSource`; остальные переводы сохраняются.

О функциональной форме `i18nSource` см. в [описании API](/rspress-russian/api/config/config-basic.md#i18nsource). Чтобы загрузить JSON-файл из другого расположения, используйте [`i18nSourcePath`](/rspress-russian/api/config/config-basic.md#i18nsourcepath).

## Использование `useI18n` в пользовательских компонентах (необязательно)

В MDX-компонентах или [собственной теме](/rspress-russian/guide/basic/custom-theme.md) используйте `useI18n`, чтобы получить определённые выше переводы. Хук работает одинаково и с `i18n.json`, и с `i18nSource`:

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

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

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

Подробнее об использовании и подсказках типов см. в разделе [`useI18n`](/rspress-russian/ui/hooks/use-i18n.md).

## Изменение текстов i18n

Стандартная тема Rspress включает переводы интерфейса для нескольких языков. Отсутствующие переводы откатываются к английскому.

Описанные выше источники переводов также могут переопределять встроенные тексты: используйте существующий ключ вместо определения нового. Например, добавьте `editLinkText` в выбранный источник, чтобы настроить текст ссылки на редактирование:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  i18nSource: {
    editLinkText: {
      en: 'Edit this page on GitLab',
      ru: 'Изменить эту страницу на GitLab',
    },
  },
});
```

Если вы используете `i18n.json`, добавьте такую же запись в него:

```json title="i18n.json"
{
  "editLinkText": {
    "en": "Edit this page on GitLab",
    "ru": "Изменить эту страницу на GitLab"
  }
}
```

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

Настройка текстов интерфейса необязательна и работает также на одноязычных сайтах. Полный список встроенных текстовых ключей см. в [описании API](/rspress-russian/api/config/config-basic.md#i18nsource).
