﻿---
title: "Справочник настроек: Giscus и общие обсуждения переводов"
description: "Все поля Giscus, типы и стандарты, ограничения общего обсуждения, совместное использование настроек заметками и границы проверок."
url: "https://demo.anglefeint.com/ru/blog/config-comments/"
language: "ru"
author: "Anglefeint"
published: "2026-11-13T00:00:00.000Z"
updated: "2026-11-14T00:00:00.000Z"
---

# Справочник настроек: Giscus и общие обсуждения переводов

Для первой настройки прочитайте [комментарии читателей](https://demo.anglefeint.com/ru/blog/starter-guide-4-giscus-comments/) с подготовкой репозитория и получением параметров. Файл — в [установке](https://demo.anglefeint.com/ru/blog/starter-guide-1-configure-your-site/), остальные модули — в [общем справочнике](https://demo.anglefeint.com/ru/blog/config-reference/).

Общие настройки — theme.comments в src/site.config.ts; стандартно отключены. Ниже стандарты пакета, не подключённый личный репозиторий demo. ID и repo выводятся в страницу и публичны; не помещайте GitHub access token или секреты.

## Различайте два переключателя

| Путь | Тип / стандарт | Состояние, действие и ограничения | Пример |
| --- | --- | --- | --- |
| theme.comments.enabled | boolean / false | Условно: статьи, не кнопки заметок. При недостающих параметрах область может не выводиться; это не проверка удалённого сервиса | theme: { comments: { enabled: true } } |
| theme.fragments.comments.enabled | boolean / false | Условно: список заметок, нужен theme.fragments.enabled true. Независим от статей; отсутствие подключения вызывает ошибку генерации заметок | theme: { fragments: { enabled: true, comments: { enabled: true } } } |

Нет comments: false frontmatter отдельной статьи или заметки. Превью главной не имеет кнопки комментариев. Остальное — в [Fragments](https://demo.anglefeint.com/ru/blog/config-fragments/#comments-enabled).

## Все поля theme.comments

Префикс всех строк — theme.comments., например theme.comments.repo. В частичном вводе поля необязательны и дополняются стандартами темы. Строковые флаги сохраняйте в кавычках, не boolean/число.

Все условны: статьям нужны включение и условия вывода; заметки используют только часть, остальные переопределяют/игнорируют. Общего правила восстановления стандартов пустой строкой нет. Помимо явных mapping-проверок, правильный тип/непустота не доказывают удалённую конфигурацию Giscus.

### Репозиторий и категория

| Поле | Тип | Стандарт | Действие, условия и ограничения | Пример |
| --- | --- | --- | --- | --- |
| `repo` | string | `""` | GitHub owner/repo. Статья требует truthy, заметка дополнительно непустое после trim. Не добавляйте крайние пробелы; удалённые права не проверяются | `"your-account/blog-discussions"` |
| `repoId` | string | `""` | ID из Giscus, не имя repo, номер или access token; общий | `"YOUR_REPOSITORY_ID"` |
| `category` | string | `""` | Настоящая категория Giscus в паре с categoryId, не тег статьи | `"Announcements"` |
| `categoryId` | string | `""` | ID, не имя категории. Статьи требуют truthy, заметки trim-непустоту; подлинность не проверяется | `"YOUR_CATEGORY_ID"` |

### Mapping статей и строгое совпадение

| Поле | Тип | Стандарт | Действие, условия и ограничения | Пример |
| --- | --- | --- | --- | --- |
| `mapping` | ‘pathname’ | ‘url’ | ‘title’ | ‘og:title’ | ‘specific’ | ‘number’ | `"pathname"` | Связь статьи/обсуждения, значения ниже. Общему режиму нужен specific; заметки поле не используют | `"pathname"` |
| `term` | string | `""` | specific необщих статей: непустой после trim, общий фиксированный для сайта. В общем режиме пустой, затем slug статьи; в остальных не передаётся | `"my-fixed-discussion"` |
| `number` | string | `""` | number необщих статей: после trim строка положительного безопасного целого без начальных нулей, плюса или дроби. В общем режиме пустой; в других не передаётся | `"42"` |
| `strict` | ‘0’ | ‘1’ | `"0"` | Строковый, не boolean. Общий режим требует 1, заметки принудительно 1. Не объединяет обсуждения с одинаковым заголовком | `"1"` |

### Вид, язык и загрузка

| Поле | Тип | Стандарт | Действие, условия и ограничения | Пример |
| --- | --- | --- | --- | --- |
| `reactionsEnabled` | ‘0’ | ‘1’ | `"1"` | Реакции основной записи обсуждения, общие; не отключение всех действий | `"1"` |
| `emitMetadata` | ‘0’ | ‘1’ | `"0"` | Метаданные Giscus родительскому окну. Статьи передают настройку без автоматической статистики; заметки принудительно 1 для готовности/смены | `"0"` |
| `inputPosition` | ‘top’ | ‘bottom’ | `"bottom"` | Форма над/под списком, общая; не положение всей области на странице | `"top"` |
| `theme` | string | `"dark"` | Тема iframe Giscus, не Matrix/Cyber/Hacker/AI. Общая, поддержка имён сервисом не проверяется, автоматической смены по сцене нет | `"dark"` |
| `lang` | string | `"en"` | Язык интерфейса статей: непустой передаётся, пустой маппится из страницы. Заметки всегда следуют странице; текст комментариев не переводится | `""` |
| `loading` | ‘lazy’ | ‘eager’ | `"lazy"` | Подсказка iframe статей, не задержка вывода client.js. Заметки eager после кнопки | `"lazy"` |
| `crossorigin` | ‘anonymous’ | ‘use-credentials’ | `"anonymous"` | Атрибут script клиента, общий; не логин repo, token или исправление разрешений | `"anonymous"` |

## theme.comments.shareAcrossLocales: общие обсуждения переводов

*   **Тип / стандарт:** необязательный boolean / false.
*   **Состояние и действие:** условно при комментариях статей; одинаковый полный slug разных языков связывает с одним обсуждением, разные slug независимы.
*   **Ограничения:** mapping ‘specific’, term/number пусты после trim, strict строка ‘1’. Иначе ошибка, одного boolean недостаточно. При отключённых статьях эти ограничения пропускаются, но подключение заметок проверяется отдельно.
*   **Пример:** общий фрагмент ниже. Не переводит, не объединяет старые обсуждения и не меняет связь заметок.

| Файл статьи | Реальный term общего режима |
| --- | --- |
| src/content/blog/zh/my-first-post.md | my-first-post |
| src/content/blog/en/my-first-post.md | my-first-post |
| src/content/blog/zh/guides/setup.md | guides/setup |
| src/content/blog/en/other/setup.md | other/setup |

Полный slug без языка, не заголовок, canonicalTopic или сходство текста. Стандартный маршрут передаёт articleSlug. Собственный BlogPost тоже требует непустой полный slug без крайних пробелов, пустых сегментов и `.` / `..`. Это параметр компонента, не site.config.

Несколько сайтов с одинаковым slug в одном repo/category могут попасть в одно обсуждение: домен не создаёт отдельную базу. С сохранением пути смена заголовка не меняет term; смена slug/repo/category/стратегии может изменить обсуждение.

## Значения mapping

| Значение | Основа Giscus | Ограничение и пример |
| --- | --- | --- |
| pathname | Путь URL | Стандарт; языковые пути обычно различаются, смена пути меняет связь |
| url | Полный URL | Домен/адрес влияют |
| title | title документа | Заголовок статьи/сайта, не только h1 текста |
| og:title | Open Graph title | Существующие метаданные, не заголовок внутри theme.comments |
| specific | Заданный term | Необщий — фиксированный всего сайта, общий — slug каждой статьи |
| number | Существующий номер Discussion | Общий фиксированный номер строкой ‘42’, не issue; не создаётся автоматически |

Поиск/создание выполняет Giscus. При отсутствии обсуждение может создаться первым комментарием/реакцией, не обязательно просмотром. Нужны публичный repo, Discussions и приложение; см. руководство и [Giscus](https://giscus.app/). Локальной базы нет.

При strict ‘1’ Giscus использует хэш заголовка в тексте обсуждения, не локальное сравнение темы. Старым обсуждениям может понадобиться маркер: [строгое совпадение](https://github.com/giscus/giscus/blob/main/ADVANCED-USAGE.md#data-strict). Общий режим/смена mapping не мигрируют, не объединяют и не удаляют старое. Комментарии могут остаться в GitHub вне новой связи; сначала определите соответствие старого обсуждения новому term.

Необщий specific с одним term направляет все статьи к одному обсуждению; number тоже фиксирован для сайта. Это не автоматический ID каждой статьи. Нерелевантные term/number не отправляются, но оба всё равно проходят trim: не заменяйте строки null/числом.

## Примеры для объединения

Добавьте в существующий defineThemeConfig({…}) src/site.config.ts, сохранив import/export и личные настройки без второго theme. Четыре значения подключения получите своим Giscus: заполнители показывают структуру, не пригодны для онлайн-проверки.

### Отдельные обсуждения статей по пути

```ts
theme: {
  comments: {
    enabled: true,
    repo: 'your-account/blog-discussions',
    repoId: 'YOUR_REPOSITORY_ID',
    category: 'Announcements',
    categoryId: 'YOUR_CATEGORY_ID',
    shareAcrossLocales: false,
    mapping: 'pathname',
    lang: '',
  },
},
```

### Общее обсуждение переводов статьи

Сохраните подключение и объедините mapping:

```ts
theme: {
  comments: {
    enabled: true,
    shareAcrossLocales: true,
    mapping: 'specific',
    term: '',
    number: '',
    strict: '1',
    lang: '',
  },
},
```

Реальный lang по умолчанию ‘en’, не следование странице. Пустая строка выше явно включает языковой mapping: zh→zh-CN, zh-hant→zh-TW, pt-br→pt, остальные напрямую. Поддержку определяет Giscus. Меняется интерфейс, не идентичность и не опубликованный текст. theme.comments глобален, не копируйте его в i18n.locales.

Строка theme напрямую передаётся Giscus, например ‘dark’/‘light’. Доступные темы и URL custom CSS определяет сервис, внешняя AI-панель не меняется. См. [темы Giscus](https://github.com/giscus/giscus/blob/main/ADVANCED-USAGE.md#data-theme); пакет не проверяет содержимое/доступность CSS.

## Какие общие поля используют заметки?

| Общее поле | Поведение заметок |
| --- | --- |
| repo / repoId / category / categoryId | Общие, непустые после trim; передаются исходные, не добавляйте крайние пробелы; удалённые права не проверяются |
| theme / reactionsEnabled / inputPosition / crossorigin | Общие исходные значения |
| enabled | Игнорирует статьи, использует theme.fragments.comments.enabled |
| shareAcrossLocales | Не используется, одинаковый стабильный ID уже общий |
| mapping / term / number | specific, term `fragment/<ID>`, number не отправляется |
| strict / emitMetadata | Фиксированные ‘1’ / ‘1’ |
| lang | Игнорируется, mapping языка страницы заметок |
| loading | eager, но клиент после первого щелчка |

Пример только заметок без статей:

```ts
theme: {
  comments: {
    enabled: false,
    repo: 'your-account/blog-discussions',
    repoId: 'YOUR_REPOSITORY_ID',
    category: 'Announcements',
    categoryId: 'YOUR_CATEGORY_ID',
  },
  fragments: { enabled: true, comments: { enabled: true } },
},
```

Одинаковые ID языков делят `fragment/<ID>`, это другая система, чем slug статей. Не меняйте ID ради сортировки/пагинации. Первое открытие загружает окно, закрытие сохраняет iframe, смена посылает конфигурацию Giscus. Примерно через 15 секунд без действительного результата ошибка/повтор. Публичных timeout/preload нет. Если статьи тоже включены, их mapping проверяется даже при настройке только заметок.

## Тексты самой страницы

Необязательные string в `i18n.locales.<locale>.messages`, стандарт — встроенный язык/откат. Примеры внутри соответствующего объекта. Меняют внешние labels, не кнопки iframe. Ниже настоящие стандарты упрощённого китайского/английского.

| Относительное поле | Стандарт упрощённого китайского / английского | Состояние, действие и ограничения | Пример |
| --- | --- | --- | --- |
| `blog.comments` | 评论 / Comments | Условно: доступное имя области статьи, не дополнительный видимый заголовок | `"Обсуждение статьи"` |
| `fragments.comments` | 评论 / Comments | Условно: кнопка и заголовок окна заметок | `"Обсудить"` |
| `fragments.close` | 关闭 / Close | Условно: закрытие окна, также доступное имя окна главной | `"Закрыть окно"` |
| `fragments.loading` | 正在加载评论… / Loading comments… | Условно: загрузка заметок | `"Загрузка обсуждения…"` |
| `fragments.error` | 评论未能加载，请检查网络或评论配置后重试。 / Unable to load comments. Check your network or comment settings, then retry. | Условно: ошибка заметок | `"Обсуждение временно недоступно."` |
| `fragments.retry` | 重试 / Retry | Условно: повтор после ошибки | `"Перезагрузить"` |

Остальные тексты — [статьи](https://demo.anglefeint.com/ru/blog/config-article/#article-messages) и [Fragments](https://demo.anglefeint.com/ru/blog/config-fragments/#fragment-messages). Они не задают язык iframe, который следует правилам lang выше.

## Границы загрузки и проверок

Статья выводит асинхронный client.js. loading ‘lazy’ передаётся iframe, не означает ожидание прокрутки для script. Заметки сначала выводят шаблон и вставляют клиент после кнопки; eager относится к iframe после щелчка. [Giscus](https://giscus.app/) различает эти уровни.

Локальный код проверяет mapping статей и обязательные поля заметок, не GitHub-вход, права приложения, публичность, категории, сеть или сервис. Пустое подключение статьи может не рендериться; строка из пробелов может пройти её условие вывода, но неверна. Заметки проверяют непустоту строже, не подлинность ID.

Все theme.comments потребляются, но не все для заметок: переопределения выше. Нет публичных индивидуальных переключателей, self-host адреса, сортировки, admin token или локальной базы. Клиент фиксирован [https://giscus.app/client.js](https://giscus.app/client.js). Настройки repo Giscus не новые поля site.config.

После изменения пересоберите и разместите. Успех сборки не подтверждает настоящий сервис. Миграция/права выполняются на GitHub/Giscus, не автоматически при сохранении site.config. [Назад к общему справочнику](https://demo.anglefeint.com/ru/blog/config-reference/).
