# General Translation Integrations: API сбора
URL: https://generaltranslation.com/ru/docs/integrations/rrweb/reference/harvest.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Сопоставление записанных текстовых узлов с опубликованными каталогами локалей. Справочник по API сбора gt-rrweb.

Импортируйте значения сбора из `gt-rrweb/harvest`. В большинстве приложений сбор настраивается через [`GTRecorder`](/docs/integrations/rrweb/reference/recorder#gt-recorder); прямой API нужен для собственных конвейеров записи.

## Обзор [#overview]

| API                                         | Описание                                                                             |
| ------------------------------------------- | ------------------------------------------------------------------------------------ |
| [`harvestLocales`](#harvest-locales)        | Создаёт оверлеи для запрошенных целевых локалей, исключая выбранную исходную локаль. |
| [`harvestHash`](#harvest-hash)              | Создаёт оверлеи с явно заданными исходной локалью и загрузчиком.                     |
| [`flattenEntry`](#flatten-entry)            | Разворачивает переведённый GTJSON в отрендеренные конечные узлы.                      |
| [`collectRecordedText`](#recorded-text)     | Собирает записанные текстовые узлы по id узла rrweb.                                 |
| [`recordingHasHashes`](#recording-hashes)   | Проверяет, содержит ли поток хеши переводов.                                         |
| [`collectHashNodes`](#hash-nodes)           | Собирает узлы переводов с хешами и вложенный в них текст.                            |
| [`overlayFromDict`](#overlay-dict)          | Сопоставляет узлы с хешами с одним каталогом переводов.                              |
| [`stringOverlay`](#string-overlay)          | Находит необёрнутые исходные строки по хешу сообщения.                               |
| [`HarvestOptions` и связанные типы](#types) | Описывают загрузчики, оверлеи, каталоги и значения GTJSON.                           |

## `harvestLocales` [#harvest-locales]

```ts
function harvestLocales(
  events: eventWithTime[],
  locales: string[],
  options?: HarvestOptions
): Promise<LocaleTextOverlay>;
```

`locales[0]` — резервная исходная локаль. Функция пропускает выбранную исходную локаль и загружает каждый оставшийся целевой каталог через `options.loadTranslations`; без загрузчика она возвращает пустой оверлей. При сборе из бандла рекордера явно заданная или полученная из cookie-файла исходная локаль должна совпадать с `locales[0]`, поскольку рекордер встраивает эту первую запись как источник для воспроизведения.

| Option             | Описание                                                                            | Type                                       | Необязательный | По умолчанию                                       |
| ------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------ | -------------- | -------------------------------------------------- |
| `loadTranslations` | Загружает опубликованный каталог соответствий «хеш — контент» для указанной локали. | `(locale: string) => Promise<unknown>`     | Да             | —                                                  |
| `hashMessage`      | Сопоставляет «голые» исходные строки с хешами, уже используемыми в каталоге.        | `(message: string) => string \| undefined` | Да             | —                                                  |
| `sourceLocale`     | Указывает локаль, отображаемую в записи.                                            | `string`                                   | Да             | Настроенный cookie-файл локали, затем `locales[0]` |
| `localeCookieName` | Задаёт имя cookie-файла для определения исходной локали.                            | `string`                                   | Да             | —                                                  |

Записи [`<T>`](/docs/react/reference/components/t) сопоставляются по атрибуту `data-_gt-hash`, который добавляется при включённом [`_tagIds`](/docs/react/reference/config#tag-ids). Непереведённые записи, записи branch или Plural без единственной формы, а также структуры с разным количеством конечных узлов остаются в исходной локали.

Резервный вариант с cookie-файлом применяется только при заданном `localeCookieName`. Пакет не предполагает какого-либо имени cookie-файла, специфичного для конкретного фреймворка. Если не указаны ни `sourceLocale`, ни `localeCookieName`, используется `locales[0]`.

`hashMessage` — точка расширенной интеграции для вызывающей стороны, у которой уже есть совместимый публичный хешер сообщений. `gt-rrweb` не экспортирует такой хешер, поэтому при обычной настройке рекордера следует полагаться на хеши [`<T>`](/docs/react/reference/components/t).

## `harvestHash` [#harvest-hash]

```ts
function harvestHash(
  events: eventWithTime[],
  locales: string[],
  options: {
    source: string;
    loadTranslations: TranslationsLoader;
    hashMessage?: (message: string) => string | undefined;
  }
): Promise<LocaleTextOverlay>;
```

`harvestHash` — это низкоуровневая стратегия хеширования, которую использует `harvestLocales`. Она требует явно указать исходную локаль и загрузчик каталога.

## `flattenEntry` [#flatten-entry]

```ts
function flattenEntry(
  entry: GtJsxChildren | null | undefined
): GtLeaf[] | null;
```

`flattenEntry(entry)` возвращает переведённый текст и конечные узлы с переменными в порядке их следования в документе. Переменные и компоненты без дочерних элементов, отображающие значение, превращаются в placeholder&#39;ы, сохраняющие записанное значение; записи типов Plural и branch возвращают `null`, так как они не задают единственную отрендеренную форму.

## `collectRecordedText` [#recorded-text]

```ts
function collectRecordedText(events: eventWithTime[]): Map<number, string>;
```

`collectRecordedText(events)` возвращает последний непробельный текст для каждого ID узла rrweb из полных снимков и мутаций. Текст, состоящий только из пробельных символов, пропускается, а более поздняя мутация с непробельным текстом заменяет предыдущий текст для того же ID.

## `recordingHasHashes` [#recording-hashes]

```ts
function recordingHasHashes(events: eventWithTime[]): boolean;
```

`recordingHasHashes(events)` возвращает, содержит ли запись хеши сообщений GT.

## `collectHashNodes` [#hash-nodes]

```ts
function collectHashNodes(events: eventWithTime[]): Array<{
  hash: string;
  textNodes: Array<{ id: number; text: string }>;
}>;
```

`collectHashNodes(events)` возвращает каждый внешний записанный хеш перевода вместе с идентификаторами вложенных текстовых узлов и исходным текстом в порядке следования в документе. Хеш, вложенный в другой хешированный узел, отдельно не возвращается.

## `overlayFromDict` [#overlay-dict]

```ts
function overlayFromDict(
  hashNodes: ReturnType<typeof collectHashNodes>,
  dict: TranslationDict
): Record<number, string>;
```

`overlayFromDict(hashNodes, dict)` сопоставляет каждый хеш-узел с одним `TranslationDict`. Функция пропускает отсутствующие переводы, Plural и branches, а также структурные несоответствия, вместо того чтобы присваивать текст не тому узлу.

## `stringOverlay` [#string-overlay]

```ts
function stringOverlay(
  recorded: Map<number, string>,
  covered: Set<number>,
  dict: TranslationDict,
  hashMessage: (message: string) => string | undefined
): Record<number, string>;
```

`stringOverlay(recorded, covered, dict, hashMessage)` обрабатывает голый текст, ещё не охваченный хешированным узлом [`<T>`](/docs/react/reference/components/t). Функция применяет только строковые записи каталога и оставляет пустые, неизменённые, отсутствующие или интерполированные отрендеренные строки в исходной локали.

## Типы [#types]

| Type                 | Определение                                                                                                           |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `HarvestOptions`     | Необязательный загрузчик каталога, хешер сообщений, исходная локаль и имя cookie-файла, принимаемые `harvestLocales`. |
| `LocaleTextOverlay`  | `Record<string, Record<number, string>>`                                                                              |
| `TranslationsLoader` | `(locale: string) => Promise<unknown>`                                                                                |
| `TranslationDict`    | `Record<string, GtJsxChildren \| null>`                                                                               |
| `GtJsxChildren`      | Дочерний элемент GTJSON или массив дочерних элементов.                                                                |
| `GtJsxChild`         | `string \| GtElement \| GtVariable`                                                                                   |
| `GtLeaf`             | `{ text: string } \| { variable: true }`                                                                              |

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

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.