diff --git a/docs/src/content/docs/ru/guides/customization.mdx b/docs/src/content/docs/ru/guides/customization.mdx index 33c2cc6577..dea4371eec 100644 --- a/docs/src/content/docs/ru/guides/customization.mdx +++ b/docs/src/content/docs/ru/guides/customization.mdx @@ -195,7 +195,7 @@ defineConfig({ Starlight имеет встроенную поддержку для добавления ссылок на ваши аккаунты в социальных сетях в заголовок сайта через параметр [`social`](/ru/reference/configuration/#social) в интеграции Starlight. -В настоящее время поддерживаются ссылки на Bitbucket, Codeberg, CodePen, Discord, Email, Facebook, GitHub, GitLab, Gitter, Instagram, LinkedIn, Mastodon, Microsoft Teams, RSS-ленту, Stack Overflow, Telegram, Threads, Twitch, Twitter, X и Youtube. +Вы можете найти полный список поддерживаемых иконок для ссылок в [Справочнике по конфигурации](/ru/reference/configuration/#social). Дайте нам знать на GitHub или Discord, если вам нужна поддержка для другого сервиса! ```js diff --git a/docs/src/content/docs/ru/guides/i18n.mdx b/docs/src/content/docs/ru/guides/i18n.mdx new file mode 100644 index 0000000000..3912cb40b7 --- /dev/null +++ b/docs/src/content/docs/ru/guides/i18n.mdx @@ -0,0 +1,233 @@ +--- +title: Интернационализация (i18n) +description: Узнайте, как настроить ваш сайт на Starlight для поддержки нескольких языков. +--- + +import FileTree from '../../../../components/file-tree.astro'; + +Starlight предоставляет встроенную поддержку для многоязычных сайтов, включая маршрутизацию, резервной контен и полную поддержку языков RTL. + +## Настройте i18n + +1. Сообщите Starlight о поддерживаемых вами языках, передав [`locales`](/ru/reference/configuration/#locales) и [`defaultLocale`](/ru/reference/configuration/#defaultlocale) в интеграцию Starlight: + + ```js + // astro.config.mjs + import { defineConfig } from 'astro/config'; + import starlight from '@astrojs/starlight'; + + export default defineConfig({ + integrations: [ + starlight({ + title: 'My Docs', + // Установите английский как язык по умолчанию для этого сайта. + defaultLocale: 'en', + 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', + }, + }, + }), + ], + }); + ``` + + `defaultLocale` будет использоваться для резервного контента и текста UI, поэтому выберите язык, на котором вы скорее всего начнете писать контент или для которого у вас уже есть материалы. + +2. Создайте каталог для каждого языка в `src/content/docs/`. + Например, для показанной выше конфигурации создайте следующие папки: + + + + - src/ + - content/ + - docs/ + - ar/ + - en/ + - zh-cn/ + + + +3. Теперь вы можете добавлять контент в ваши языковые каталоги. Используйте одно и то же имя файла, чтобы связать страницы на разных языках и использовать все функции i18n Starlight, включая резервной контент, уведомления о переводах и многое другое. + + Например, создайте `ar/index.md` и `en/index.md` для отображения главной страницы на арабском и английском языках. + +### Использование корневой локали + +Вы можете использовать "корневую" локаль для отображения языка без префикса i18n в его пути. +Например, если английский является вашей корневой локалью, путь к английской странице будет выглядеть как `/about` вместо `/en/about`. + +Чтобы установить корневую локаль, используйте ключ `root` в вашей конфигурации `locales`. +Если корневая локаль также является локалью по умолчанию для вашего контента, удалите `defaultLocale` или установите его значение как `'root'`. + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: 'Моя документация', + defaultLocale: 'root', // опционально + locales: { + root: { + label: 'English', + lang: 'en', // lang обязателен для корневых локалей. + }, + 'zh-cn': { + label: '简体中文', + lang: 'zh-CN', + }, + }, + }), + ], +}); +``` + +Когда вы используете `root` локаль, сохраняйте страницы для этого языка непосредственно в `src/content/docs/`, +а не в выделенной папке для языка. Например, вот файлы главной страницы для английского и китайского языков, используя приведенную выше конфигурацию: + + + +- src/ + - content/ + - docs/ + - **index.md** + - zh-cn/ + - **index.md** + + + +#### Одноязычные сайты + +По умолчанию, Starlight является одноязычным (английским) сайтом. Чтобы создать сайт на другом языке, укажите его как `root` в вашей конфигурации `locales`: + +```js +// astro.config.mjs +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; + +export default defineConfig({ + integrations: [ + starlight({ + title: 'Моя документация', + locales: { + root: { + label: '简体中文', + lang: 'zh-CN', + }, + }, + }), + ], +}); +``` + +Это позволяет вам переопределить язык по умолчанию для Starlight без включения других функций интернационализации для многоязычных сайтов, таких как выбор языка. + +## Резервный контент + +Starlight предполагает, что вы создадите эквивалентные страницы на всех поддерживаемых языках. +Например, если у вас есть файл `en/about.md`, создайте файл `about.md` для каждого другого языка, который вы поддерживаете. +Это позволяет Starlight предоставлять автоматически резервный контент для страниц, которые еще не были переведены. + +Если перевод для языка еще не доступен, Starlight покажет читателям контент этой страницы на языке по умолчанию (установлен через `defaultLocale`). +Например, если вы еще не создали французскую версию вашей страницы "О нас" и вашим языком по умолчанию является английский, +посетители `/fr/about` увидят английский контент из `/en/about` с уведомлением о том, что эта страница еще не была переведена. +Это помогает вам добавлять контент на вашем языке по умолчанию и постепенно переводить его, когда у ваших переводчиков есть время. + +## Перевод UI Starlight + +Кроме размещения переведенных файлов с контентом, Starlight позволяет вам переводить текст UI (например, заголовок "На этой странице" в оглавлении), +чтобы ваши читатели могли полностью погрузиться в ваш сайт на выбранном языке. + +Переводы строк пользовательского интерфейса на английский, чешский, французский, немецкий, итальянский, японский, +португальский, голландский, датский, испанский, турецкий, арабский, норвежский, фарси, иврит, упрощенный китайский, +корейский, индонезийский, русский, шведский, украинский и вьетнамский языки предоставляются "из коробки", +и мы приветствуем [вклад в добавление языков по умолчанию](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md). + +Вы можете добавить переводы для дополнительных языков, которые вы поддерживаете — или переопределить наши стандартные текст — через коллекцию данных `i18n`. + +1. Сконфигурируйте коллекцию данных `i18n` в `src/content/config.ts`, если она еще не настроена: + + ```js + // 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/` для каждой дополнительной локали, для которой вы хотите добавить текста перевода UI. + Например, так можно добавить файлы перевода для арабского и упрощенного китайского: + + + + - src/ + - content/ + - i18n/ + - ar.json + - zh-CN.json + + + +3. Добавьте переводы для ключей, которые вы хотите перевести, в файлы JSON. Переводите только значения, оставляя ключи на английском языке (например, `"search.label": "Buscar"`). + + Это английские значения по умолчанию для существующих строк, с которыми поставляется Starlight: + + ```json + { + "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": "Next", + "page.nextLink": "Previous", + "404.text": "Page not found. Check the URL or try using the search bar." + } + ``` + + Модальное окно поиска в Starlight работает на библиотеке [Pagefind](https://pagefind.app/). + Вы можете установить переводы для пользовательского интерфейса Pagefind в том же JSON-файле, используя ключи `pagefind`: + + ```json + { + "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]..." + } + ``` diff --git a/docs/src/content/docs/ru/guides/overriding-components.md b/docs/src/content/docs/ru/guides/overriding-components.md new file mode 100644 index 0000000000..964f75e99a --- /dev/null +++ b/docs/src/content/docs/ru/guides/overriding-components.md @@ -0,0 +1,144 @@ +--- +title: Переопределение Компонентов +description: Узнайте, как переопределить встроенные компоненты Starlight, чтобы добавить пользовательские элементы в UI вашего сайта документации. +sidebar: + badge: Новое +--- + +Стандартный UI и параметры конфигурации Starlight разработаны так, +чтобы быть гибкими и работать с различным контентом. +Большая часть стандартного внешнего вида Starlight может быть настроена с использованием [CSS](/ru/guides/css-and-tailwind/) +и [параметров конфигурации](/ru/guides/customization/). + +Когда вам нужно больше, чем то, что возможно из коробки, +Starlight поддерживает создание собственных компонентов для расширения или переопределения (полная замена) его стандартных компонентов. + +## Когда переопределять + +Переопределение стандартных компонентов Starlight может быть полезно, когда: + +- Вы хотите изменить внешний вид UI Starlight так, как это невозможно сделать с использованием [пользовательских CSS](/ru/guides/css-and-tailwind/). +- Вы хотите изменить поведение UI Starlight. +- Вы хотите добавить какой-то дополнительный UI наряду с существующим UI Starlight. + +## Как выполнить переопределение + +1. Выберите компонент Starlight, который вы хотите переопределить. + Вы можете найти полный список компонентов в [Справочнике по переопределениям](/ru/reference/overrides/). + + В этом примере будет переопределен компонент [`SocialIcons`](/ru/reference/overrides/#socialicons) Starlight в навигационной панели страницы. + +2. Создайте компонент Astro для замены компонента Starlight. + В этом примере отображается ссылка для связи. + + ```astro + --- + // src/components/EmailLink.astro + import type { Props } from '@astrojs/starlight/props'; + --- + + Написать нам на E-mail + ``` + +3. Сообщите Starlight использовать ваш компонент, указав его в параметре конфигурации [`components`](/ru/reference/configuration/#components) в `astro.config.mjs`: + + ```js {9-12} + // astro.config.mjs + import { defineConfig } from 'astro/config'; + import starlight from '@astrojs/starlight'; + + export default defineConfig({ + integrations: [ + starlight({ + title: 'Моя документация, с переопределением', + components: { + // Переопределение компонента `SocialIcons`. + SocialIcons: './src/components/EmailLink.astro', + }, + }), + ], + }); + ``` + +## Переиспользование встроенного компонента + +Вы можете работать со стандартными UI компонентами Starlight так же, +как и со своими собственными: импортировать их и использовать в своих компонентах. +Это позволяет вам сохранить весь UI Starlight в рамках вашего дизайна, +добавляя свой UI рядом с ними. + +Пример ниже показывает компонент, который отображает ссылку на электронную почту наряду со стандартным компонентом `SocialIcons`: + +```astro {4,8} +--- +// src/components/EmailLink.astro +import type { Props } from '@astrojs/starlight/props'; +import Default from '@astrojs/starlight/components/SocialIcons.astro'; +--- + +Написать нам на E-mail + +``` + +При использовании встроенного компонента внутри вашего компонента: + +- Передайте в него `Astro.props`. Это гарантирует, что он получит все данные, необходимые для отображения. +- Добавьте [``](https://docs.astro.build/ru/core-concepts/astro-components/#slots) внутрь компонента по умолчанию. Это гарантирует, что если компоненту передаются какие-либо дочерние элементы, Astro знает, где их отображать. + +## Использование данных страницы + +При переопределении компонента Starlight ваша реализация получает стандартный объект `Astro.props`, содержащий все данные для текущей страницы. +Это позволяет вам использовать эти значения для управления тем, как ваш компонент будет отображаться. + +Например, вы можете прочитать метаданные страницы как `Astro.props.entry.data`. +В следующем примере компонент [`PageTitle`](/ru/reference/overrides/#pagetitle) использует этот объект для отображения текущего заголовка страницы: + +```astro {5} "{title}" +--- +// src/components/Title.astro +import type { Props } from '@astrojs/starlight/props'; + +const { title } = Astro.props.entry.data; +--- + +

{title}

+ + +``` + +Узнайте больше обо всех доступных свойствах в [Справочнике по переопределениям](/ru/reference/overrides/#component-props). + +### Переопределение только на определенных страницах + +Переопределение компонентов применяется ко всем страницам. Тем не менее, вы можете осуществлять условный рендеринг, +используя значения из `Astro.props`, чтобы определить, когда показывать ваш UI, +когда показывать UI от Starlight, или даже когда показывать что-то совершенно другое. + +В следующем примере компонент, переопределяющий [`Footer`](/ru/reference/overrides/#footer-1) от Starlight, +отображает "Создано с Starlight 🌟" только на главной странице, а на всех остальных страницах показывает футер по умолчанию: + +```astro +--- +// src/components/ConditionalFooter.astro +import type { Props } from '@astrojs/starlight/props'; +import Default from '@astrojs/starlight/components/Footer.astro'; + +const isHomepage = Astro.props.slug === ''; +--- + +{ + isHomepage ? ( + + ) : ( + + + + ) +} +``` + +Узнайте больше о условной отрисовке в руководстве [Astro’s Template Syntax](https://docs.astro.build/ru/core-concepts/astro-syntax/#dynamic-html). diff --git a/docs/src/content/docs/ru/guides/sidebar.mdx b/docs/src/content/docs/ru/guides/sidebar.mdx new file mode 100644 index 0000000000..76ed585869 --- /dev/null +++ b/docs/src/content/docs/ru/guides/sidebar.mdx @@ -0,0 +1,525 @@ +--- +title: Боковая панель +description: Узнайте, как настроить и настроить ссылки боковой панели навигации вашего сайта Starlight. +--- + +import FileTree from '../../../../components/file-tree.astro'; +import SidebarPreview from '../../../../components/sidebar-preview.astro'; + +Хорошо организованная боковая панель ключевой параметр хорошей документации, поскольку это один из основных способов, +которыми пользователи будут перемещаться по вашему сайту. Starlight предоставляет полный набор опций для настройки макета и содержимого вашей боковой панели. + +## Стандартная боковая панель + +По умолчанию, Starlight автоматически создаст боковую панель на основе файловой системы вашей документации, используя свойство `title` каждого файла как элемент боковой панели. + +Например, учитывая следующую структуру файлов: + + + +- src/ + - content/ + - docs/ + - guides/ + - components.md + - i18n.md + - reference/ + - configuration.md + + + +Следующая боковая панель будет сгенерирована автоматически: + + + +Узнайте больше о автоматически генерируемых боковых панелях в разделе [Автоматически Генерируемые Группы](##автогенерируемые-группы). + +## Добавление ссылок и групп ссылок + +Чтобы настроить свои [ссылки](#ссылки) и [группы ссылок](#группировка) (внутри сворачиваемого заголовка) в боковой панели, +используйте свойство [`starlight.sidebar`](/reference/configuration/#sidebar) в `astro.config.mjs`. + +Сочетая ссылки и группы, вы можете создавать разнообразные макеты боковой панели. + +### Ссылки + +Добавьте ссылку на внутреннюю или внешнюю страницу, используя объект со свойствами `label` и `link`. + +```js +starlight({ + sidebar: [ + // Ссылка на руководство по CSS и стилизации. + { label: 'CSS & стилизация', link: '/ru/guides/css-and-tailwind/' }, + // Внешняя ссылка на веб-сайт Astro. + { label: 'Astro', link: 'https://astro.build/' }, + ], +}); +``` + +Конфигурация выше создает следующую боковую панель: + + + +### Группировка + +Вы можете структурировать вашу боковую панель, группируя связанные ссылки вместе под раскрывающимся заголовком. +Группы могут содержать как ссылки, так и другие подгруппы. + +Добавьте группу, используя объект с свойствами `label` и `items`. +`label` будет использован как заголовок для группы. +Добавляйте ссылки или подгруппы в массив `items`. + +```js +starlight({ + sidebar: [ + // Группа ссылок с названием "Руководства". + { + label: 'Руководства', + items: [ + { label: 'Компоненты', link: '/ru/guides/components/' }, + { label: 'Интернационализация (i18n)', link: '/ru/guides/i18n/' }, + // Вложенная группа ссылок. + { + label: 'Стилизация', + items: [ + { label: 'CSS', link: '/ru/guides/css-and-tailwind/' }, + { label: 'Tailwind', link: '/ru/guides/css-and-tailwind/' }, + { label: 'Shiki', link: '/ru/guides/css-and-tailwind/' }, + ], + }, + ], + }, + ], +}); +``` + +Вышеуказанная конфигурация генерирует следующую боковую панель: + + + +### Автогенерируемые группы + +Starlight может автоматически генерировать группу в вашей боковой панели, основываясь на директориях в вашей документации. +Это полезно, когда вы не хотите вручную вводить каждый элемент боковой панели в группе. +Страницы по умолчанию будут отсортированы по алфавиту по имени файла. + +Добавьте автогенерируемую группу, используя объект с свойствами `label` и `autogenerate`. +Ваша конфигурация `autogenerate` должна указывать `directory`, который будет использоваться для записей боковой панели. +Например, со следующей конфигурацией: + +```js +starlight({ + sidebar: [ + { + label: 'Руководства', + // Автоматически генерировать группу ссылок для директории "руководства". + autogenerate: { directory: 'guides' }, + }, + ], +}); +``` + +И следующей структурой файлов: + + + +- src/ + - content/ + - docs/ + - guides/ + - components.md + - i18n.md + - advanced/ + - project-structure.md + + + +Следующая боковая панель будет сгенерирована: + + + +#### Настройка сгенерированных ссылок через метаданные + +Используйте [поле `sidebar`](/ru/reference/frontmatter/#sidebar) в метаданных страниц для настройки автоматически генерируемых ссылок. + +Параметры в метаданных для боковой панели позволяют [установить метку](/ru/reference/frontmatter/#label) +или добавить [значок](/ru/reference/frontmatter/#badge) к ссылке, [скрыть](/ru/reference/frontmatter/#hidden) +ссылку из боковой панели или определить [вес сортировки](/ru/reference/frontmatter/#order). + +```md +--- +title: Моя страница +sidebar: + # Установить текст для ссылки + label: Текст в боковой панели + # Установить порядок для ссылки (меньшие числа отображаются выше) + order: 2 + # Добавить значок к ссылке + badge: + text: Новое + variant: tip +--- +``` + +Автоматически созданная группа, включающая страницу с вышеуказанными метаданными, сгенерирует следующую боковую панель: + + + +:::note[Заметка] +Конфигурация `sidebar` в метаданных используется только для автоматически генерируемых ссылок и будет проигнорирована для вручную определенных ссылок. +::: + +## Значки + +Ссылки также могут включать свойство `badge` для отображения значка рядом с текстом ссылки. + +```js +starlight({ + sidebar: [ + { + label: 'Руководства', + items: [ + // Ссылка со значком "Новое". + { + label: 'Компоненты', + link: '/ru/guides/components/', + badge: 'Новое', + }, + ], + }, + ], +}); +``` + +Конфигурация выше создаст следующую боковую панель: + + + +### Варианты значков + +Настройте стиль значка, используя объект с свойствами `text` и `variant`. + +`text` представляет содержимое для отображения (например, "Новое"). +Переопределите стиль `default`, который использует акцентный цвет вашего сайта, +установив свойство `variant` в одно из следующих значений: `note`, `tip`, `danger`, `caution` или `success`. + +```js +starlight({ + sidebar: [ + { + label: 'Руководства', + items: [ + // Ссылка с желтым значком "Экспериментально". + { + label: 'Компоненты', + link: '/ru/guides/components/', + badge: { text: 'Экспериментально', variant: 'caution' }, + }, + ], + }, + ], +}); +``` + +Конфигурация выше создаст следующую боковую панель: + + + +## Пользовательские HTML-атрибуты + +Ссылки также могут включать свойство `attrs` для добавления пользовательских HTML-атрибутов к элементу ссылки. + +В следующем примере `attrs` используется для добавления атрибута `target="_blank"`, чтобы ссылка открывалась в новой вкладке, +а также для применения атрибута `style`, чтобы курсивом выделить метку ссылки: + +```js +starlight({ + sidebar: [ + { + label: 'Руководства', + items: [ + // Внешняя ссылка на документацию Astro, открывающаяся в новой вкладке. + { + label: 'Документация Astro', + link: 'https://docs.astro.build/', + attrs: { target: '_blank', style: 'font-style: italic' }, + }, + ], + }, + ], +}); +``` + +Конфигурация выше создаст следующую боковую панель: + + + +## Интернационализация + +Используйте свойство `translations` для ссылок и групп, чтобы перевести текст ссылки или группы на каждый поддерживаемый язык, +указав языковой тег [BCP-47](https://www.w3.org/International/questions/qa-choosing-language-tags), например, +`"en"`, `"ar"` или `"zh-CN"`, в качестве ключа и переведенной метки в качестве значения. +Свойство `label` будет использоваться для языка по умолчанию и для языков без перевода. + +```js +starlight({ + sidebar: [ + { + label: 'Руководства', + translations: { + 'pt-BR': 'Guias', + }, + items: [ + { + label: 'Компоненты', + translations: { + 'pt-BR': 'Componentes', + }, + link: '/guides/components/', + }, + { + label: 'Интернационализация (i18n)', + translations: { + 'pt-BR': 'Internacionalização (i18n)', + }, + link: '/guides/i18n/', + }, + ], + }, + ], +}); +``` + +При просмотре документации на бразильском португальском языке будет сгенерирована следующая боковая панель: + + + +## Сворачиваемые группы + +Группы ссылок могут быть свернуты по умолчанию, если установить свойство `collapsed` в `true`. + +```js +starlight({ + sidebar: [ + { + label: 'Руководства', + // Collapse the group by default. + collapsed: true, + items: [ + { label: 'Components', link: '/guides/components/' }, + { label: 'Internationalization (i18n)', link: '/guides/i18n/' }, + ], + }, + ], +}); +``` + +Конфигурация выше создает следующую боковую панель: + + + +[Автогенерируемые группы](#автогенерируемые-группы) учитывают значение `collapsed` родительской группы: + +```js +starlight({ + sidebar: [ + { + label: 'Руководства', + // Свернуть группу и её автогенерируемые подгруппы по умолчанию. + collapsed: true, + autogenerate: { directory: 'guides' }, + }, + ], +}); +``` + +Конфигурация выше создает следующую боковую панель: + + + +Это поведение может быть переопределено путем установки свойства `autogenerate.collapsed`. + +```js +starlight({ + sidebar: [ + { + label: 'Руководства', + // Не сворачивать группу "Руководства", но свернуть её автоматически сгенерированные подгруппы. + collapsed: false, + autogenerate: { directory: 'guides', collapsed: true }, + }, + ], +}); +``` + +Конфигурация выше создает следующую боковую панель: + +