# General Translation Integrations: Harvest API
URL: https://generaltranslation.com/en-US/docs/integrations/rrweb/reference/harvest.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Map recorded text nodes to published locale catalogs. 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 catalog. |
| [`stringOverlay`](#string-overlay) | Matches unwrapped source strings by message hash. |
| [`HarvestOptions` and related types](#types) | Describe loaders, overlays, catalogs, 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 catalog 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 catalog by locale. | `(locale: string) => Promise<unknown>` | Yes | — |
| `hashMessage` | Maps bare source strings to hashes already used by the catalog. | `(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 catalog 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 one 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 catalog entries and leaves blank, unchanged, absent, or interpolated rendered strings in the source locale.

## Types [#types]

| Type | Definition |
| --- | --- |
| `HarvestOptions` | Optional catalog 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 catalog 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.