i18n
Чтобы интернационализировать сайт документации на Rspress, выполните следующие шаги:
- Настройте список языков и язык по умолчанию в
rspress.config.ts. - Создайте файлы документации и навигации для каждого языка.
Если пользовательским компонентам нужен переведённый текст или вы хотите изменить встроенные тексты интерфейса, обратитесь к необязательным разделам ниже.
Настройка rspress.config.ts
Отредактируйте rspress.config.ts, чтобы настроить:
locales: поддерживаемые языки и информацию уровня сайта для каждого языка, напримерtitleиdescription.lang: язык сайта по умолчанию. Его значение должно совпадать с одним из значенийlangвlocales.
Rspress удаляет языковой префикс из маршрутов языка по умолчанию. При lang: 'ru' маршрут /ru/guide/start/introduction превращается в /guide/start/introduction, а английский маршрут сохраняет префикс: /en/guide/start/introduction.
themeConfig.locales также содержит все поля из locales, однако в будущем этот параметр будет удалён. Вместо него используйте locales.
Создание документации для каждого языка
Создайте директорию для каждого языка в корневом каталоге документации. Имена директорий должны совпадать со значениями lang в locales:
Здесь документация для разных языков находится в директориях en и ru внутри docs, что делает каждую языковую версию легко различимой.
Внутри каждой языковой директории используйте _nav.json и _meta.json для настройки панели навигации и сайдбара. Подробнее см. в разделе Автонавигация.
Настройка навигации _nav.json
В _nav.json каждого языка задайте в поле "text" текст на этом языке:
Настройка сайдбара _meta.json
Аналогично задайте в поле "label" текст для каждого языка:
Для таких языковых файлов навигации отдельные текстовые данные i18n не нужны.
Определение текстовых данных для i18n (необязательно)
Описанной выше настройки достаточно для многоязычного сайта документации. Если пользовательским компонентам нужен переведённый текст, определите ключ, например welcomeMessage, и укажите значение для каждого языка.
Rspress принимает одни и те же текстовые данные двумя способами.
Выберите либо i18n.json, либо i18nSource; оба способа сразу не нужны.
Создайте файл i18n.json рядом с rspress.config.ts. Каждый ключ сопоставляет коды языков с переведённым текстом:
Если настроены оба способа, при совпадении ключа и языка приоритет имеет объектная форма i18nSource; остальные переводы сохраняются.
О функциональной форме i18nSource см. в описании API. Чтобы загрузить JSON-файл из другого расположения, используйте i18nSourcePath.
Использование useI18n в пользовательских компонентах (необязательно)
В MDX-компонентах или собственной теме используйте useI18n, чтобы получить определённые выше переводы. Хук работает одинаково и с i18n.json, и с i18nSource:
Подробнее об использовании и подсказках типов см. в разделе useI18n.
Изменение текстов i18n
Стандартная тема Rspress включает переводы интерфейса для нескольких языков. Отсутствующие переводы откатываются к английскому.
Описанные выше источники переводов также могут переопределять встроенные тексты: используйте существующий ключ вместо определения нового. Например, добавьте editLinkText в выбранный источник, чтобы настроить текст ссылки на редактирование:
Если вы используете i18n.json, добавьте такую же запись в него:
Чтобы добавить ещё один язык, укажите его код и переведённый текст в каждом текстовом ключе в i18nSource или i18n.json, используя те же коды языков, что и в конфигурации сайта. Встроенные тексты, которые вы не перевели, продолжат использовать английский вариант по умолчанию.
Настройка текстов интерфейса необязательна и работает также на одноязычных сайтах. Полный список встроенных текстовых ключей см. в описании API.

