Интернационализация (i18n)

Docusite поддерживает многоязычную документацию через VitePress locales. Каждая локаль может иметь свою навигацию и сайдбар.

Настройка

import { defineConfig } from 'docusite'

export default defineConfig({
  locales: {
    root: {
      label: 'Русский',
      lang: 'ru',
    },
    en: {
      label: 'English',
      lang: 'en',
      link: '/en/',
      nav: [
        { text: 'Guide', link: '/en/guide/getting-started' },
      ],
      sidebar: {
        '/en/': [
          {
            text: 'Guide',
            items: [
              { text: 'Getting Started', link: '/en/guide/getting-started' },
            ],
          },
        ],
      },
    },
  },
})

Поля локали

Поле	Тип	Описание
label	string	Отображаемое название языка (например, 'English')
lang	string	HTML-атрибут lang (например, 'en')
link	string?	Префикс пути (обязателен для не-root локалей, например '/ru/')
nav	NavItem[]?	Навигация для данной локали
sidebar	Sidebar?	Сайдбар для данной локали

Корневая локаль

Локаль с ключом root — это локаль по умолчанию. Для неё:

• Поле link не указывается (контент доступен по корневому пути /)
• Если не указать nav и sidebar, используются глобальные настройки

Некорневые локали

Для некорневых локалей (например, en):

• Поле link обязательно — определяет префикс URL (например, /en/)
• Рекомендуется указать nav и sidebar для каждого языка

Структура директорий

docs/
  index.md                     ← корневая локаль (русский)
  introduction/
    getting-started.md
  en/
    index.md                   ← английская локаль
    introduction/
      getting-started.md

Переключатель языков

Docusite подключает переключатель языков, который учитывает версионирование: при переходе с /v1/... на другой язык сохраняется префикс версии (/ru/v1/...).

Вместе с версионированием

Язык — внешний префикс, версия — внутренний:

docs/
  introduction/...           ← EN latest
  v1/introduction/...        ← EN v1
  ru/
    introduction/...         ← RU latest
    v1/introduction/...      ← RU v1

Path-keyed nav / sidebar задаются для каждого префикса (/, /v1/, /ru/, /ru/v1/). Ссылки в versions.older указываются для root-локали (/v1/...) — для остальных языков Docusite подставляет текущий locale-префикс сам.

Подробнее: Версионирование.