Перейти к содержимому
Starlight

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

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

Настройка i18n

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

    astro.config.mjs
    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/ru/`
            ru: {
              label: 'Русский',
              lang: 'ru',
            },
          },
        }),
      ],
    });

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

  2. Создайте каталог для каждого языка в src/content/docs/. Например, для показанной выше конфигурации создайте следующие папки:

    • Директорияsrc/
      • Директорияcontent/
        • Директорияdocs/
          • Директорияen/
            • …
          • Директорияru/
            • …
          • Директорияzh-cn/
            • …

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

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

Для более продвинутых сценариев использования i18n Starlight также поддерживает настройку интернационализации с помощью опции i18n Astro.

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

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

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

astro.config.mjs
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:

astro.config.mjs
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 использует одно и то же название сайта для всех языков. Если вам нужно настроить заголовок для каждой локали, вы можете передать объект title в опциях Starlight:

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


export default defineConfig({
  integrations: [
    starlight({
     title: 'Моя документация',
     title: {
       ru: "Моя документация",
       'zh-CN': '我的文档',
     },
      defaultLocale: 'ru',
      locales: {
        ru: { label: 'Русский' },
        'zh-cn': { label: '简体中文', lang: 'zh-CN' },
      },
    }),
  ],
});

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

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

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

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

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

    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() }),
    };

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

    • Директорияsrc/
      • Директорияcontent/
        • Директорияi18n/
          • ar.json
          • ru.json

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

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

    {
      "skipLink.label": "Skip to content",
      "search.label": "Search",
      "search.ctrlKey": "Ctrl",
      "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",
      "page.draft": "This content is a draft and will not be included in production builds.",
      "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",
      "builtWithStarlight.label": "Built with Starlight"
    }

    Блоки кода 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:

src/content/config.ts
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.

Использование переводов пользовательского интерфейса

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

В компонентах Astro этот API доступен как часть глобального объекта Astro в виде Astro.locals.t:

example.astro
<p dir={Astro.locals.t.dir()}>
  {Astro.locals.t('404.text')}
</p>

Вы также можете использовать API в эндпойнтах, где объект locals доступен как часть контекста эндпойнта:

src/pages/404.ts
export const GET = (context) => {
  return new Response(context.locals.t('404.text'));
};

Рендеринг строки пользовательского интерфейса

Отрисовка строк пользовательского интерфейса с помощью функции locals.t(). Это экземпляр функции i18next t(), которая принимает в качестве первого аргумента строку-ключ UI и возвращает соответствующий перевод для текущего языка.

Например, задан файл пользовательского перевода со следующим содержанием:

src/content/i18n/ru.json
{
  "link.astro": "Документация Astro",
  "link.astro.custom": "Документация Astro о {{feature}}"
}

Первую строку пользовательского интерфейса можно отобразить, передав 'link.astro' в функцию t():

src/components/Example.astro
<a href="https://docs.astro.build/">
  {Astro.locals.t('link.astro')}
</a>
<!-- Отрисовывает: <a href="...">Документация Astro</a> -->

Вторая строка пользовательского интерфейса использует синтаксис интерполяции i18next для размещения {{feature}}. Значение для feature должно быть задано в объекте options, передаваемом в качестве второго аргумента в t():

src/components/Example.astro
<a href="https://docs.astro.build/ru/guides/astro-db/">
  {Astro.locals.t('link.astro.custom', { feature: 'Astro DB' })}
</a>
<!-- Отрисовывает: <a href="...">Документация Astro о Astro DB</a> -->

Подробнее о том, как использовать функцию t() для интерполяции, форматирования и т. д., см. в документации i18next.

Расширенные API

t.all()

Функция locals.t.all() возвращает объект, содержащий все строки пользовательского интерфейса, доступные для текущей локали.

src/components/Example.astro
---
const allStrings = Astro.locals.t.all();
//    ^
//    {
//      "skipLink.label": "Перейти к содержанию",
//      "search.label": "Поиск",
//      …
//    }
---

t.exists()

Чтобы проверить, существует ли ключ перевода для локали, используйте функцию locals.t.exists() с ключом перевода в качестве первого аргумента. Передайте необязательный второй аргумент, если вам нужно переопределить текущую локаль.

src/components/Example.astro
---
const keyExistsInCurrentLocale = Astro.locals.t.exists('a.key');
//    ^ true
const keyExistsInFrench = Astro.locals.t.exists('another.key', { lng: 'fr' });
//    ^ false
---

Дополнительную информацию см. в статье exists() в документации i18next.

t.dir()

Функция locals.t.dir() возвращает направление текста текущей или определённой локали.

src/components/Example.astro
---
const currentDirection = Astro.locals.t.dir();
//    ^
//    'ltr'
const arabicDirection = Astro.locals.t.dir('ar');
//    ^
//    'rtl'
---

Дополнительную информацию см. в статье dir() в документации i18next.

Доступ к текущей локали

Вы можете использовать Astro.currentLocale для получения текущей локали в компонентах .astro.

Следующий пример считывает текущую локаль и использует её с помощью хелпера getRelativeLocaleUrl() для генерации ссылки на страницу «О сайте» на текущем языке:

src/components/AboutLink.astro
---
import { getRelativeLocaleUrl } from 'astro:i18n';
---


<a href={getRelativeLocaleUrl(Astro.currentLocale ?? 'en', 'about')}>О сайте</a>