From 4fe9baa960fe11dae4d02edf4715ad9754010340 Mon Sep 17 00:00:00 2001 From: Bugo Date: Sat, 2 Aug 2025 13:00:53 +0500 Subject: i18n(ru): update translations (#3356) Co-authored-by: HiDeoo <494699+HiDeoo@users.noreply.github.com>--- docs/src/content/docs/ru/components/asides.mdx | 42 ++++++- .../content/docs/ru/guides/authoring-content.mdx | 17 ++- docs/src/content/docs/ru/guides/i18n.mdx | 15 ++- docs/src/content/docs/ru/guides/sidebar.mdx | 70 +++++++++++- docs/src/content/docs/ru/manual-setup.mdx | 2 +- .../content/docs/ru/reference/configuration.mdx | 121 ++++++++++++++++++++- docs/src/content/docs/ru/reference/frontmatter.md | 1 + .../docs/ru/resources/community-content.mdx | 5 + docs/src/content/docs/ru/resources/plugins.mdx | 15 +++ docs/src/content/docs/ru/resources/themes.mdx | 6 +- 10 files changed, 275 insertions(+), 19 deletions(-) diff --git a/docs/src/content/docs/ru/components/asides.mdx b/docs/src/content/docs/ru/components/asides.mdx index 227a9ce1..92179ba8 100644 --- a/docs/src/content/docs/ru/components/asides.mdx +++ b/docs/src/content/docs/ru/components/asides.mdx @@ -112,7 +112,7 @@ Starlight также предоставляет собственный синт import { Aside } from '@astrojs/starlight/components'; ``` @@ -120,14 +120,44 @@ import { Aside } from '@astrojs/starlight/components'; ```markdoc 'title="Осторожно!"' {% aside type="caution" title="Осторожно!" %} -Вставка предупреждения *с* пользовательским заголовком. +Предупреждение *с* пользовательским заголовком. {% /aside %} ``` + + + +### Использование пользовательских иконок + +Переопределяйте стандартные иконки боковой панели, используя атрибут [`icon`](#icon) с именем одной из [встроенных иконок Starlight](/ru/reference/icons/#все-иконки). + + + +```mdx 'icon="starlight"' +import { Aside } from '@astrojs/starlight/components'; + + +``` + + + +```markdoc 'icon="starlight"' +{% aside type="tip" icon="starlight" %} +Подсказка *с* пользовательской иконкой. +{% /aside %} +``` + + + + @@ -156,3 +186,9 @@ import { Aside } from '@astrojs/starlight/components'; Заголовок вставки для отображения. Если `title` не установлен, будет использоваться заголовок по умолчанию для текущего `type` вставки. + +### `icon` + +**тип:** [`StarlightIcon`](/ru/reference/icons/#тип-starlighticon) + +Вставка может включать атрибут `icon`, содержащий имя одной из [встроенных иконок Starlight](/ru/reference/icons/#все-иконки). \ No newline at end of file diff --git a/docs/src/content/docs/ru/guides/authoring-content.mdx b/docs/src/content/docs/ru/guides/authoring-content.mdx index d1ff16bc..e557da5f 100644 --- a/docs/src/content/docs/ru/guides/authoring-content.mdx +++ b/docs/src/content/docs/ru/guides/authoring-content.mdx @@ -151,9 +151,24 @@ Astro позволяет создавать быстрые сайты с пом ::: ``` +### Пользовательские иконки вставок + +Вы можете указать пользовательскую иконку для вставки в фигурных скобках после типа панели или [пользовательского заголовка](#настраиваемые-заголовки-вставок), например, `:::tip{icon="heart"}` или `:::tip[Знаете ли вы?]{icon="heart"}` соответственно. +В качестве имени должна использоваться одна из [встроенных иконок Starlight](/ru/reference/icons/#все-иконки). + +:::tip{icon="heart"} +Astro помогает создавать более быстрые веб-сайты с помощью [архитектуры островков](https://docs.astro.build/ru/concepts/islands/). +::: + +```md +:::tip{icon="heart"} +Astro помогает создавать более быстрые веб-сайты с помощью [архитектуры островков](https://docs.astro.build/ru/concepts/islands/). +::: +``` + ### Другие типы вставок -Вставки «Caution» и «danger» полезны для привлечения внимания пользователя к деталям, которые могут сбивать с толку. +Вставки с типами «caution» и «danger» полезны для привлечения внимания пользователя к деталям, которые могут сбивать с толку. Если вы часто используете их, это может быть признаком того, что может быть нужно пересмотреть то, что вы документируете. :::caution diff --git a/docs/src/content/docs/ru/guides/i18n.mdx b/docs/src/content/docs/ru/guides/i18n.mdx index ad330484..94027c20 100644 --- a/docs/src/content/docs/ru/guides/i18n.mdx +++ b/docs/src/content/docs/ru/guides/i18n.mdx @@ -182,8 +182,7 @@ import UIStringsList from '~/components/ui-strings-list.astro'; — все переведённые строки пользовательского интерфейса на указанных языках предоставляются «из коробки», и мы приветствуем -[вклад в добавление дополнительных языков по -умолчанию](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md). +[вклад в добавление новых языков](https://github.com/withastro/starlight/blob/main/CONTRIBUTING.md). Вы можете добавить переводы для дополнительных языков, которые вы поддерживаете — или переопределить наши стандартные тексты — через коллекцию данных `i18n`. @@ -253,7 +252,7 @@ import UIStringsList from '~/components/ui-strings-list.astro'; -### Расширение схемы перевода +### Расширение схемы переводов Добавьте пользовательские ключи в словари переводов вашего сайта, установив `extend` в опциях `i18nSchema()`. В следующем примере к ключам по умолчанию добавляется новый необязательный ключ `custom.label`: @@ -281,7 +280,7 @@ export const collections = { ## Использование UI-переводов -Вы можете получить доступ к [встроенным строкам пользовательского интерфейса](/ru/guides/i18n/#перевод-интерфейса-starlight) Starlight, а также к [пользовательским](/ru/guides/i18n/#расширение-схемы-перевода) и [предоставляемым плагинами](/ru/reference/plugins/#injecttranslations) строкам пользовательского интерфейса через единый API на базе [i18next](https://www.i18next.com/). +Вы можете получить доступ к [встроенным строкам пользовательского интерфейса](/ru/guides/i18n/#перевод-интерфейса-starlight) Starlight, а также к [пользовательским](/ru/guides/i18n/#расширение-схемы-переводов) и [предоставляемым плагинами](/ru/reference/plugins/#injecttranslations) строкам пользовательского интерфейса через единый API на базе [i18next](https://www.i18next.com/). Это включает поддержку таких функций, как [интерполяция](https://www.i18next.com/translation-function/interpolation) и [плюрализация](https://www.i18next.com/translation-function/plurals). В компонентах Astro этот API доступен как часть [глобального объекта `Astro`](https://docs.astro.build/en/reference/api-reference/#locals) в виде `Astro.locals.t`: @@ -361,15 +360,15 @@ const allStrings = Astro.locals.t.all(); #### `t.exists()` -Чтобы проверить, существует ли ключ перевода для локали, используйте функцию `locals.t.exists()` с ключом перевода в качестве первого аргумента. -Передайте необязательный второй аргумент, если вам нужно переопределить текущую локаль. +Чтобы проверить, существует ли ключ перевода, используйте функцию `locals.t.exists()` с ключом перевода в качестве первого аргумента. +Передайте необязательный второй аргумент, если нужно проверить наличие перевода для определённой локали. ```astro --- // src/components/Example.astro -const keyExistsInCurrentLocale = Astro.locals.t.exists('a.key'); +const keyExists = Astro.locals.t.exists('a.key'); // ^ true -const keyExistsInFrench = Astro.locals.t.exists('another.key', { lng: 'fr' }); +const keyExistsInFrench = Astro.locals.t.exists('other.key', { lngs: ['fr'] }); // ^ false --- ``` diff --git a/docs/src/content/docs/ru/guides/sidebar.mdx b/docs/src/content/docs/ru/guides/sidebar.mdx index 495dd67e..57365d8b 100644 --- a/docs/src/content/docs/ru/guides/sidebar.mdx +++ b/docs/src/content/docs/ru/guides/sidebar.mdx @@ -244,7 +244,7 @@ starlight({ Используйте [поле `sidebar`](/ru/reference/frontmatter/#sidebar) в метаданных страниц для настройки автоматически генерируемых ссылок. -Параметры в метаданных для боковой панели позволяют [установить метку](/ru/reference/frontmatter/#label) или добавить [значок](/ru/reference/frontmatter/#badge) к ссылке, [скрыть](/ru/reference/frontmatter/#hidden) ссылку из боковой панели или определить её [порядок](/ru/reference/frontmatter/#order) в общем списке. +Параметры в метаданных для боковой панели позволяют установить [пользовательскую метку](/ru/reference/frontmatter/#label), использовать [пользовательские атрибуты](/ru/reference/frontmatter/#attrs), добавить [значок](/ru/reference/frontmatter/#badge) к ссылке, [скрыть](/ru/reference/frontmatter/#hidden) ссылку из боковой панели или определить [порядок её сортировки](/ru/reference/frontmatter/#order). ```md "sidebar:" --- @@ -253,7 +253,7 @@ title: Моя страница sidebar: # Установить текст для ссылки label: Текст в боковой панели - # Установить порядок для ссылки (меньшие числа отображаются выше) + # Установить порядок для ссылки (чем ниже число, тем выше будет отображаться ссылка) order: 2 # Добавить значок к ссылке badge: @@ -436,6 +436,72 @@ starlight({ ]} /> +### Пользовательские HTML-атрибуты для автоматически сгенерированных ссылок + +Настройте HTML-атрибуты всех ссылок в [автоматически сгенерированных группах](#автогенерируемые-группы), указав свойство `attrs` в конфигурации `autogenerate`. +Отдельные страницы могут задавать пользовательские атрибуты с помощью поля [`sidebar.attrs`](/ru/reference/frontmatter/#attrs) в метаданных, которое будет объединено с конфигурацией `autogenerate.attrs`. + +Например, со следующей конфигурацией: + +```js {9} +starlight({ + sidebar: [ + { + label: 'Созвездия', + autogenerate: { + // Автоматически генерируем группу ссылок для директории 'constellations' + directory: 'constellations', + // Выделяем курсивом все ярлыки ссылок в этой группе + attrs: { style: 'font-style: italic' }, + }, + }, + ], +}); +``` + +и следующей файловой структурой: + + + +- src/ + - content/ + - docs/ + - constellations/ + - carina.md + - centaurus.md + - seasonal/ + - andromeda.md + + + +Будет сгенерирована боковая панель с выделением всех автоматически созданных ссылок курсивом: + + + ## Интернационализация Используйте свойство `translations` для записей ссылок и групп, чтобы перевести метку ссылки или группы для каждого поддерживаемого языка, указав тег языка [BCP-47](https://www.w3.org/International/questions/qa-choosing-language-tags), например, `"en"`, `"ru"` или `"zh-CN"` в качестве ключа, и перевод метки — в качестве значения. diff --git a/docs/src/content/docs/ru/manual-setup.mdx b/docs/src/content/docs/ru/manual-setup.mdx index 882eaa8a..3372da9a 100644 --- a/docs/src/content/docs/ru/manual-setup.mdx +++ b/docs/src/content/docs/ru/manual-setup.mdx @@ -64,7 +64,7 @@ export default defineConfig({ Starlight создан на основе [коллекций контента](https://docs.astro.build/ru/guides/content-collections/) Astro, которые настраиваются в файле `src/content.config.ts`. -Создайте или обновите файл конфигурации контента, добавив коллекцию `docs`, которая использует схемы `docsLoader` и `docsSchema` от Starlight: +Создайте или обновите файл конфигурации контента, добавив коллекцию `docs`, которая использует схемы [`docsLoader`](/ru/reference/configuration/#docsloader) и [`docsSchema`](/ru/reference/configuration/#docsschema): от Starlight: ```js ins={3-4,7} // src/content.config.ts diff --git a/docs/src/content/docs/ru/reference/configuration.mdx b/docs/src/content/docs/ru/reference/configuration.mdx index 08521e21..bcc7999e 100644 --- a/docs/src/content/docs/ru/reference/configuration.mdx +++ b/docs/src/content/docs/ru/reference/configuration.mdx @@ -224,7 +224,11 @@ type SidebarItem = | { // Автоматически созданная группа ссылок label: string; - autogenerate: { directory: string; collapsed?: boolean }; + autogenerate: { + directory: string; + collapsed?: boolean; + attrs?: Record; + }; collapsed?: boolean; } )); @@ -677,3 +681,118 @@ starlight({ credits: true, }); ``` + +## Настройка коллекций контента + +Starlight использует [коллекции контента](https://docs.astro.build/ru/guides/content-collections/) Astro для загрузки вашего контента. +Загрузчики контента и схемы Starlight помогают настроить коллекции в соответствии с вашими потребностями. + +```js +// src/content.config.ts +import { defineCollection } from 'astro:content'; +import { docsLoader, i18nLoader } from '@astrojs/starlight/loaders'; +import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'; + +export const collections = { + docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }), + // Необязательно: коллекция i18n используется для перевода + // пользовательского интерфейса на многоязычных сайтах + i18n: defineCollection({ loader: i18nLoader(), schema: i18nSchema() }), +}; +``` + +### Загрузчики + +Starlight экспортирует следующие [загрузчики Astro](https://docs.astro.build/ru/reference/content-loader-reference/) из модуля `@astrojs/starlight/loaders`, чтобы упростить настройку коллекций контента. + +#### `docsLoader()` + +Загрузчик `docsLoader()` загружает локальные файлы Markdown, MDX и Markdoc из директории `src/content/docs/`. Файлы, названия которых начинаются с подчёркивания (`_`), игнорируются. + +##### Импорт + +```js +import { docsLoader } from '@astrojs/starlight/loaders'; +``` + +##### Параметры + +###### `generateId()` + +**тип:** `({ entry: string; base: URL; data: Record }) => string` + +По умолчанию страницы, созданные с помощью `docsLoader()`, обрабатывают имена файлов с помощью «слагификатора» (sluggifier), который удаляет специальные символы и приводит имя к нижнему регистру. +Если вы хотите переопределить это поведение, можно предоставить собственную функцию `generateId()`. + +Например, это может быть полезно для сохранения специальных символов, которые в противном случае были бы удалены. +По умолчанию файл `Example.File.md` будет доступен по пути `/examplefile`. +Если нужно, чтобы он был доступен по пути `/Example.File`, можно определить кастомную функцию `generateId()`: + +```js +docsLoader({ + // Удаляет расширение `.md` или `.mdx`, но в остальном не изменяет названия файлов. + generateId: ({ entry }) => entry.split('.').slice(0, -1).join('.'), +}), +``` + +Подробнее см. [`generateId()` в документации Astro](https://docs.astro.build/ru/reference/content-loader-reference/#generateid). + +#### `i18nLoader()` + +Загрузчик `i18nLoader()` загружает локальные файлы JSON и YAML из директории `src/content/i18n/`. +Файлы, названия которых начинаются с подчёркивания (`_`), игнорируются. + +##### Импорт + +```js +import { i18nLoader } from '@astrojs/starlight/loaders'; +``` + +##### Параметры + +На данный момент у `i18nLoader()` нет доступных параметров. + +### Схемы + +Starlight предоставляет следующие [схемы для коллекций контента](https://docs.astro.build/ru/guides/content-collections/#%D0%BE%D0%BF%D1%80%D0%B5%D0%B4%D0%B5%D0%BB%D0%B5%D0%BD%D0%B8%D0%B5-%D1%81%D1%85%D0%B5%D0%BC%D1%8B-%D0%BA%D0%BE%D0%BB%D0%BB%D0%B5%D0%BA%D1%86%D0%B8%D0%B8) из модуля `@astrojs/starlight/schema`. +Эти схемы обязательны для использования в коллекциях `docs` и `i18n`, от которых зависит Starlight. + +#### `docsSchema()` + +`schema()` обрабатывает метаданные для всего контента в коллекции `docs`. + +##### Импорт + +```js +import { docsSchema } from '@astrojs/starlight/schema'; +``` + +##### Параметры + +###### `extend` + +**тип:** схема Zod или функция, возвращающая схему Zod +**по умолчанию:** `z.object({})` + +Расширяет схему метаданных Starlight дополнительными полями. +Подробнее об использовании опции `extend` см. в разделе [Настройка схемы метаданных](/ru/reference/frontmatter/#настройка-схемы-метаданных). + +#### `i18nSchema()` + +Схема `i18nSchema()` обрабатывает все файлы данных в коллекции `i18n`. + +##### Импорт + +```js +import { i18nSchema } from '@astrojs/starlight/schema'; +``` + +##### Параметры + +###### `extend` + +**тип:** объект Zod +**по умолчанию:** `z.object({})` + +Расширяет схему интернационализации (i18n) Starlight дополнительными полями. +Подробнее об использовании опции `extend` см. в разделе [Расширение схемы переводов](/ru/guides/i18n/#расширение-схемы-переводов). diff --git a/docs/src/content/docs/ru/reference/frontmatter.md b/docs/src/content/docs/ru/reference/frontmatter.md index 5ff1ef3f..289af10f 100644 --- a/docs/src/content/docs/ru/reference/frontmatter.md +++ b/docs/src/content/docs/ru/reference/frontmatter.md @@ -386,6 +386,7 @@ sidebar: **тип:** `Record` Атрибуты HTML для добавления к ссылке на страницу в боковой панели при отображении в автогенерируемой группе ссылок. +Если поле [`autogenerate.attrs`](/ru/guides/sidebar/#пользовательские-html-атрибуты-для-автоматически-сгенерированных-ссылок) установлено для автоматически сгенерированной группы, к которой относится эта страница, атрибуты в метаданных будут объединены с атрибутами группы. ```md --- diff --git a/docs/src/content/docs/ru/resources/community-content.mdx b/docs/src/content/docs/ru/resources/community-content.mdx index c93537e1..a53e953a 100644 --- a/docs/src/content/docs/ru/resources/community-content.mdx +++ b/docs/src/content/docs/ru/resources/community-content.mdx @@ -109,6 +109,11 @@ import { CardGrid, LinkCard } from '@astrojs/starlight/components'; title="Примеры Starlight" description="Коллекция вставок StackBlitz, демонстрирующих практические способы работы с сайтами документации Starlight" /> + ## Видеоконтент diff --git a/docs/src/content/docs/ru/resources/plugins.mdx b/docs/src/content/docs/ru/resources/plugins.mdx index 7a4ac987..fbca3f97 100644 --- a/docs/src/content/docs/ru/resources/plugins.mdx +++ b/docs/src/content/docs/ru/resources/plugins.mdx @@ -158,6 +158,16 @@ sidebar: title="starlight-scroll-to-top" description="Добавьте кнопку прокрутки страницы вверх к вашему сайту документации." /> + + ## Инструменты и интеграции от сообщества @@ -217,4 +227,9 @@ import { CardGrid, LinkCard } from '@astrojs/starlight/components'; title="astro-mermaid" description="Рендеринг Mermaid-контента на стороне клиента в блоках кода Markdown." /> + diff --git a/docs/src/content/docs/ru/resources/themes.mdx b/docs/src/content/docs/ru/resources/themes.mdx index c451e2e7..11f7cd65 100644 --- a/docs/src/content/docs/ru/resources/themes.mdx +++ b/docs/src/content/docs/ru/resources/themes.mdx @@ -74,9 +74,9 @@ import ThemeGrid from '~/components/theme-grid.astro'; previews: { light: 'nova-light.png', dark: 'nova-dark.png' }, }, { - title: 'Starlight NextJS Theme', - description: 'Тема Starlight, вдохновлённая документацией NextJS.', - href: 'https://starlight-nextjs-theme.trueberryless.org/', + title: 'Starlight Next.js', + description: 'Тема Starlight, вдохновлённая документацией Next.js.', + href: 'https://starlight-theme-next.trueberryless.org/', previews: { light: 'nextjs-light.png', dark: 'nextjs-dark.png' }, }, ]} -- cgit