# General Translation Integrations: Harvest API
URL: https://generaltranslation.com/en-GB/docs/integrations/rrweb/reference/harvest.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Map recorded text nodes to published locale catalogues. API reference for gt-rrweb harvesting.

Import harvest values from `gt-rrweb/harvest`. Most applications configure harvesting through [`GTRecorder`](/docs/integrations/rrweb/reference/recorder#gt-recorder); the direct API supports custom recording pipelines.

## Overview [#overview]

| API                                          | Description                                                                         |
| -------------------------------------------- | ----------------------------------------------------------------------------------- |
| [`harvestLocales`](#harvest-locales)         | Builds overlays for requested target locales, excluding the selected source locale. |
| [`harvestHash`](#harvest-hash)               | Builds overlays with an explicit source locale and loader.                          |
| [`flattenEntry`](#flatten-entry)             | Flattens translated GTJSON into rendered leaves.                                    |
| [`collectRecordedText`](#recorded-text)      | Collects recorded text nodes by rrweb node id.                                      |
| [`recordingHasHashes`](#recording-hashes)    | Checks whether the stream contains translation hashes.                              |
| [`collectHashNodes`](#hash-nodes)            | Collects hashed translation nodes and descendant text.                              |
| [`overlayFromDict`](#overlay-dict)           | Aligns hashed nodes with one translation catalogue.                                 |
| [`stringOverlay`](#string-overlay)           | Matches unwrapped source strings by message hash.                                   |
| [`HarvestOptions` and related types](#types) | Describe loaders, overlays, catalogues, and GTJSON values.                          |

## `harvestLocales` [#harvest-locales]

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

`locales[0]` is the fallback source locale. The function skips the selected source locale and loads each remaining target catalogue through `options.loadTranslations`; without a loader it returns an empty overlay. When harvesting a recorder bundle, the explicit or cookie-derived source must equal `locales[0]` because the recorder embeds that first entry as the replay source.

| Option             | Description                                                       | Type                                       | Optional | Default                                     |
| ------------------ | ----------------------------------------------------------------- | ------------------------------------------ | -------- | ------------------------------------------- |
| `loadTranslations` | Loads a published hash-to-content catalogue by locale.            | `(locale: string) => Promise<unknown>`     | Yes      | —                                           |
| `hashMessage`      | Maps bare source strings to hashes already used by the catalogue. | `(message: string) => string \| undefined` | Yes      | —                                           |
| `sourceLocale`     | Identifies the locale visible in the recording.                   | `string`                                   | Yes      | Configured locale cookie, then `locales[0]` |
| `localeCookieName` | Names the cookie used to detect the source locale.                | `string`                                   | Yes      | —                                           |

[`<T>`](/docs/react/reference/components/t) entries are aligned by the `data-_gt-hash` attribute emitted when [`_tagIds`](/docs/react/reference/config#tag-ids) is enabled. Untranslated entries, branch or plural entries without a single form, and structures whose leaf counts differ are left in the source locale.

The cookie fallback applies only when `localeCookieName` is set. The package does not assume a framework-specific cookie name. When both `sourceLocale` and `localeCookieName` are omitted, it uses `locales[0]`.

`hashMessage` is an advanced integration point for a caller that already has a compatible public message hasher. `gt-rrweb` does not export that hasher, so ordinary recorder setup should rely on [`<T>`](/docs/react/reference/components/t) hashes.

## `harvestHash` [#harvest-hash]

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

`harvestHash` is the lower-level hash strategy used by `harvestLocales`. It requires an explicit source locale and catalogue loader.

## `flattenEntry` [#flatten-entry]

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

`flattenEntry(entry)` returns translated text and variable leaves in document order. Variables and childless value-rendering components become placeholders that keep the recorded value; plural and branch entries return `null` because they do not identify a single rendered form.

## `collectRecordedText` [#recorded-text]

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

`collectRecordedText(events)` returns the latest non-whitespace text for each rrweb node ID from full snapshots and mutations. Whitespace-only text is skipped, and a later non-whitespace mutation replaces the earlier text for the same ID.

## `recordingHasHashes` [#recording-hashes]

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

`recordingHasHashes(events)` returns whether the recording includes GT message hashes.

## `collectHashNodes` [#hash-nodes]

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

`collectHashNodes(events)` returns each outermost recorded translation hash with its descendant text node IDs and source text in document order. A hash nested inside another hashed node is not returned separately.

## `overlayFromDict` [#overlay-dict]

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

`overlayFromDict(hashNodes, dict)` aligns each hash node with one `TranslationDict`. It skips absent translations, plurals and branches, and structural mismatches instead of assigning text to the wrong node.

## `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)` handles bare text not already covered by a hashed [`<T>`](/docs/react/reference/components/t) node. It applies only string-valued catalogue entries and leaves blank, unchanged, absent, or interpolated rendered strings in the source locale.

## Types [#types]

| Type                 | Definition                                                                                              |
| -------------------- | ------------------------------------------------------------------------------------------------------- |
| `HarvestOptions`     | Optional catalogue loader, message hasher, source locale, and cookie name accepted by `harvestLocales`. |
| `LocaleTextOverlay`  | `Record<string, Record<number, string>>`                                                                |
| `TranslationsLoader` | `(locale: string) => Promise<unknown>`                                                                  |
| `TranslationDict`    | `Record<string, GtJsxChildren \| null>`                                                                 |
| `GtJsxChildren`      | A GTJSON child or array of children.                                                                    |
| `GtJsxChild`         | `string \| GtElement \| GtVariable`                                                                     |
| `GtLeaf`             | `{ text: string } \| { variable: true }`                                                                |

The GTJSON helper types describe the compact catalogue representation consumed by the overlay functions. They are useful when implementing custom harvest tooling; ordinary recorder setup does not need them.

## Sitemap

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