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

Starlight обеспечивает встроенную поддержку многоязычных сайтов, включая маршрутизацию, резервный контент и полную поддержку языков с письмом справа налево (RTL).

Настройка i18n

Сообщите Starlight о поддерживаемых вами языках, передав свойства locales и defaultLocale в интеграцию Starlight:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Моя документация',
      // Устанавливаем «Русский» как язык по умолчанию для этого сайта
      defaultLocale: 'ru',
      locales: {
        // Документация на английском в `src/content/docs/en/`
        en: {
          label: 'English',
        },
        // Документация на китайском в `src/content/docs/zh-cn/`
        'zh-cn': {
          label: '简体中文',
          lang: 'zh-CN',
        },
        // Документация на арабском в `src/content/docs/ar/`
        ar: {
          label: 'العربية',
          dir: 'rtl',
        },
        // Документация на русском в `src/content/docs/ru/`
        ru: {
          label: 'Русский',
          lang: 'ru',
        },
      },
    }),
  ],
});

defaultLocale будет использоваться для резервного контента и текста UI, поэтому выберите язык, на котором вы скорее всего начнете писать контент или для которого у вас уже есть материалы.

Создайте каталог для каждого языка в src/content/docs/. Например, для показанной выше конфигурации создайте следующие папки:
- Директорияsrc/
  - Директорияcontent/
    Директорияdocs/
    Директорияar/
    …
    Директорияen/
    …
    Директорияru/
    …
Теперь вы можете добавлять контент в свои языковые каталоги. Используйте одно и то же имя файла для связывания страниц на разных языках и воспользуйтесь полным набором функций i18n Starlight, включая резервный контент, уведомления о переводе и многое другое.

Например, создайте ar/index.md и en/index.md для отображения главной страницы на арабском и английском языках.

Использование корневой локали

Вы можете использовать «корневую» локаль для отображения языка без префикса i18n в его пути. Например, если русский является вашей корневой локалью, путь к странице на русском языке будет выглядеть как /about вместо /ru/about.

Чтобы установить корневую локаль, используйте ключ root в вашей конфигурации locales. Если корневая локаль также является локалью по умолчанию для вашего контента, удалите defaultLocale или установите его значение как 'root'.

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Моя документация',
      defaultLocale: 'root', // опционально
      locales: {
        root: {
          label: 'Русский',
          lang: 'ru', // lang обязателен для корневых локалей.
        },
        en: {
          label: 'English',
          lang: 'en',
        },
      },
    }),
  ],
});

При использовании локали root храните страницы для этого языка непосредственно в src/content/docs/, а не в отдельной языковой папке. Например, вот файлы домашней страницы для английского и русского языков при использовании приведённой выше конфигурации:

Директорияsrc/
- Директорияcontent/
  - Директорияdocs/
    index.md
    Директорияen/
    index.md

Одноязычные сайты

По умолчанию, Starlight является одноязычным сайтом, с английским языком. Чтобы создать сайт на другом языке, укажите его как root в вашей конфигурации locales:

import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
  integrations: [
    starlight({
      title: 'Моя документация',
      locales: {
        root: {
          label: 'Русский',
          lang: 'ru',
        },
      },
    }),
  ],
});

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

Резервный контент

Starlight предполагает, что вы создадите эквивалентные страницы на всех поддерживаемых языках. Например, если у вас есть файл en/about.md, создайте файл about.md для каждого другого языка, который вы поддерживаете. Это позволяет Starlight предоставлять автоматически резервный контент для страниц, которые ещё не были переведены.

Если перевод для языка ещё не доступен, Starlight покажет читателям контент этой страницы на языке по умолчанию (установленном через defaultLocale). Например, если вы ещё не создали французскую версию вашей страницы «О нас» и вашим языком по умолчанию является английский, посетители /fr/about увидят английский контент из /en/about с уведомлением о том, что эта страница ещё не была переведена. Это помогает вам добавлять контент на вашем языке по умолчанию и постепенно переводить его, когда у ваших переводчиков есть время.

Перевод интерфейса Starlight

Кроме размещения переведённых файлов с контентом, Starlight позволяет вам переводить текст UI (например, заголовок «На этой странице» в оглавлении), чтобы ваши читатели могли полностью погрузиться в ваш сайт на выбранном языке.

Английский, арабский, вьетнамский, галисийский, датский, иврит, индонезийский, испанский, итальянский, китайский, китайский (Тайвань), корейский, немецкий, нидерландский, норвежский букмол, персидский, польский, португальский, румынский, русский, турецкий, украинский, французский, хинди, чешский, шведский и японский — все переведённые строки пользовательского интерфейса на указанных языках предоставляются «из коробки», и мы приветствуем вклад в добавление дополнительных языков по умолчанию.

Вы можете добавить переводы для дополнительных языков, которые вы поддерживаете — или переопределить наши стандартные тексты — через коллекцию данных i18n.

Сконфигурируйте коллекцию данных i18n в src/content/config.ts, если она ещё не настроена:

import { defineCollection } from 'astro:content';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ schema: docsSchema() }),
  i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
};

Создайте файл JSON в src/content/i18n/ для каждой дополнительной локали, для которой вы хотите добавить строки перевода UI. Например, так можно добавить файлы перевода для арабского и русского:
- Директорияsrc/
  - Директорияcontent/
    Директорияi18n/
    ar.json
    ru.json

Добавьте переводы для ключей, которые вы хотите перевести, в файлы JSON. Переводите только значения, оставляя ключи на английском языке (например, "search.label": "Поиск").

Это английские значения по умолчанию для существующих строк, с которыми поставляется Starlight:

{
  "skipLink.label": "Skip to content",
  "search.label": "Search",
  "search.shortcutLabel": "(Press / to Search)",
  "search.cancelLabel": "Cancel",
  "search.devWarning": "Search is only available in production builds. \nTry building and previewing the site to test it out locally.",
  "themeSelect.accessibleLabel": "Select theme",
  "themeSelect.dark": "Dark",
  "themeSelect.light": "Light",
  "themeSelect.auto": "Auto",
  "languageSelect.accessibleLabel": "Select language",
  "menuButton.accessibleLabel": "Menu",
  "sidebarNav.accessibleLabel": "Main",
  "tableOfContents.onThisPage": "On this page",
  "tableOfContents.overview": "Overview",
  "i18n.untranslatedContent": "This content is not available in your language yet.",
  "page.editLink": "Edit page",
  "page.lastUpdated": "Last updated:",
  "page.previousLink": "Previous",
  "page.nextLink": "Next",
  "404.text": "Page not found. Check the URL or try using the search bar.",
  "aside.note": "Note",
  "aside.tip": "Tip",
  "aside.caution": "Caution",
  "aside.danger": "Danger",
  "fileTree.directory": "Directory"
}

Блоки кода Starlight основаны на библиотеке Expressive Code. Вы можете установить переводы для строк пользовательского интерфейса в том же файле JSON, используя ключи expressiveCode:

{
  "expressiveCode.copyButtonCopied": "Copied!",
  "expressiveCode.copyButtonTooltip": "Copy to clipboard",
  "expressiveCode.terminalWindowFallbackTitle": "Terminal window"
}

Модальное окно поиска в Starlight работает с помощью библиотеки Pagefind. Вы можете установить переводы для пользовательского интерфейса Pagefind в том же JSON-файле, используя ключи pagefind:

{
  "pagefind.clear_search": "Clear",
  "pagefind.load_more": "Load more results",
  "pagefind.search_label": "Search this site",
  "pagefind.filters_label": "Filters",
  "pagefind.zero_results": "No results for [SEARCH_TERM]",
  "pagefind.many_results": "[COUNT] results for [SEARCH_TERM]",
  "pagefind.one_result": "[COUNT] result for [SEARCH_TERM]",
  "pagefind.alt_search": "No results for [SEARCH_TERM]. Showing results for [DIFFERENT_TERM] instead",
  "pagefind.search_suggestion": "No results for [SEARCH_TERM]. Try one of the following searches:",
  "pagefind.searching": "Searching for [SEARCH_TERM]..."
}

Расширение схемы перевода

Добавьте пользовательские ключи в словари переводов вашего сайта, установив extend в опциях i18nSchema(). В следующем примере к ключам по умолчанию добавляется новый необязательный ключ custom.label:

import { defineCollection, z } from 'astro:content';
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';

export const collections = {
  docs: defineCollection({ schema: docsSchema() }),
  i18n: defineCollection({
    type: 'data',
    schema: i18nSchema({
      extend: z.object({
        'custom.label': z.string().optional(),
      }),
    }),
  }),
};

Дополнительную информацию о схемах коллекции контента см. в разделе Определение схемы коллекции в документации Astro.