# General Translation Integrations: 采集 API
URL: https://generaltranslation.com/zh/docs/integrations/rrweb/reference/harvest.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 将录制的文本节点映射到已发布的区域设置翻译目录。gt-rrweb 采集的 API 参考。

从 `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)   | 按 rrweb 节点 id 收集录制的文本节点。    |
| [`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` 加载其余每个目标翻译目录；若未提供加载器，则返回空的叠加层。在采集 录制器 bundle 时，显式指定或由 cookie 推导出的 source 必须等于 `locales[0]`，因为 录制器 会将第一个条目嵌入为 replay source。

| Option             | Description                | Type                                       | Optional | Default                             |
| ------------------ | -------------------------- | ------------------------------------------ | -------- | ----------------------------------- |
| `loadTranslations` | 按区域设置加载已发布的 hash 到内容的翻译目录。 | `(locale: string) => Promise<unknown>`     | 是        | —                                   |
| `hashMessage`      | 将纯源字符串映射到翻译目录中已使用的 hash。   | `(message: string) => string \| undefined` | 是        | —                                   |
| `sourceLocale`     | 标识 recording 中显示的 区域设置。    | `string`                                   | 是        | 已配置的 locale cookie，其次为 `locales[0]` |
| `localeCookieName` | 指定用于检测源区域设置的 cookie 名称。    | `string`                                   | 是        | —                                   |

[`<T>`](/docs/react/reference/components/t) 条目 通过启用 [`_tagIds`](/docs/react/reference/config#tag-ids) 时生成的 `data-_gt-hash` attribute 进行对齐。未翻译的 条目、没有唯一形式的 branch 或 plural 条目，以及 leaf 数量不一致的结构，都会保留源区域设置。

仅在设置了 `localeCookieName` 时才会应用 cookie 后备内容。该 package 不会假定任何特定于框架的 cookie 名称。当同时省略 `sourceLocale` 和 `localeCookieName` 时，将使用 `locales[0]`。

`hashMessage` 是一个高级集成点，适用于已经拥有兼容的公共消息 hash 计算器的调用方。`gt-rrweb` 不会导出该 hash 计算器，因此常规的 录制器 设置应依赖 [`<T>`](/docs/react/reference/components/t) hash。

## `harvestHash` [#harvest-hash]

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

`harvestHash` 是 `harvestLocales` 底层使用的 hash 策略，需要显式指定源区域设置和翻译目录加载器。

## `flattenEntry` [#flatten-entry]

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

`flattenEntry(entry)` 按文档顺序返回已翻译的文本和变量叶节点。变量以及不含子节点、仅渲染值的组件会变成占位符，并保留所录制的值；plural 和 branch 条目则返回 `null`，因为它们无法确定唯一的渲染形式。

## `collectRecordedText` [#recorded-text]

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

`collectRecordedText(events)` 会从完整快照和变更 (mutation) 中提取每个 rrweb 节点 ID 对应的最新非空白文本并返回。仅包含空白字符的文本会被跳过；若后续出现非空白变更，则会覆盖同一 ID 此前的文本。

## `recordingHasHashes` [#recording-hashes]

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

`recordingHasHashes(events)` 返回该 recording 是否包含 GT 消息 hash。

## `collectHashNodes` [#hash-nodes]

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

`collectHashNodes(events)` 会按文档顺序返回每个最外层的已录制翻译哈希值，以及其后代文本节点 ID 和源文本。嵌套在另一个带哈希节点内的哈希值不会单独返回。

## `overlayFromDict` [#overlay-dict]

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

`overlayFromDict(hashNodes, dict)` 会将每个 hash 节点与一个 `TranslationDict` 对齐。若遇到缺失的翻译、plurals 与 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`     | `harvestLocales` 接受的可选目录加载器、消息哈希函数、源区域设置和 cookie 名称。 |
| `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.