# General Translation Integrations: ハーベスト API
URL: https://generaltranslation.com/ja/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)      | 選択されたソースロケールを除く、要求されたターゲットロケールの overlay を構築します。 |
| [`harvestHash`](#harvest-hash)            | ソースロケールと ローダー を明示的に指定して overlay を構築します。       |
| [`flattenEntry`](#flatten-entry)          | 翻訳済み GTJSON を、レンダリングされた リーフ にフラット化します。          |
| [`collectRecordedText`](#recorded-text)   | 記録されたテキストノードを rrweb のノード id ごとに収集します。           |
| [`recordingHasHashes`](#recording-hashes) | ストリームに translation ハッシュ が含まれているかを確認します。         |
| [`collectHashNodes`](#hash-nodes)         | ハッシュ化された翻訳ノードとその配下のテキストを収集します。                  |
| [`overlayFromDict`](#overlay-dict)        | ハッシュ化されたノードを 1 つの translation カタログ と対応付けます。  |
| [`stringOverlay`](#string-overlay)        | wrap されていない source string をメッセージハッシュで照合します。     |
| [`HarvestOptions` と関連する型](#types)         | ローダー、overlay、カタログ、GTJSON 値について説明します。       |

## `harvestLocales` [#harvest-locales]

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

`locales[0]` はフォールバック用のソースロケールです。この関数は選択されたソースロケールをスキップし、残りの各ターゲットのカタログを `options.loadTranslations` を通じて読み込みます。ローダー が指定されていない場合は空の overlay を返します。レコーダー の bundle を ハーベスト する場合、レコーダー は最初のエントリを Replay の source として埋め込むため、明示的に指定された、または cookie から導出された source は `locales[0]` と一致している必要があります。

| Option             | 説明                                             | Type                                       | 任意 | Default                          |
| ------------------ | ---------------------------------------------- | ------------------------------------------ | -- | -------------------------------- |
| `loadTranslations` | 公開済みのハッシュとコンテンツの対応カタログをロケール単位で読み込みます。          | `(locale: string) => Promise<unknown>`     | はい | —                                |
| `hashMessage`      | 素の source strings を、カタログですでに使われているハッシュに対応付けます。 | `(message: string) => string \| undefined` | はい | —                                |
| `sourceLocale`     | 記録内に表示されているロケールを指定します。                         | `string`                                   | はい | 設定されたロケール cookie、次に `locales[0]` |
| `localeCookieName` | ソースロケールの検出に使う cookie の名前を指定します。                | `string`                                   | はい | —                                |

[`<T>`](/docs/react/reference/components/t) のエントリは、[`_tagIds`](/docs/react/reference/config#tag-ids) が有効なときに出力される `data-_gt-hash` 属性によって対応付けられます。未翻訳のエントリ、単一の 形式 を持たない branch または Plural のエントリ、および リーフ の数が一致しない構造は、ソースロケールのまま残ります。

cookie によるフォールバックは、`localeCookieName` が設定されている場合にのみ適用されます。この package は framework-specific な cookie 名を前提としません。`sourceLocale` と `localeCookieName` の両方が省略された場合は `locales[0]` を使用します。

`hashMessage` は、互換性のある公開メッセージハッシャーをすでに持っている呼び出し元向けの高度な インテグレーション ポイントです。`gt-rrweb` はそのハッシャーをエクスポートしないため、通常の レコーダー の setup では [`<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)` は、翻訳済みテキストと変数のリーフをドキュメント順で返します。変数、および子を持たない値表示用コンポーネントは、記録された値を保持するプレースホルダーになります。plural および branch のエントリは、レンダリングされる形式を一意に特定できないため `null` を返します。

## `collectRecordedText` [#recorded-text]

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

`collectRecordedText(events)` は、フルスナップショットとミューテーションから、各 rrweb ノード ID の最新の非空白テキストを返します。空白のみのテキストはスキップされ、後続の非空白ミューテーションが同じ 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)` は、記録された最も外側の translation ハッシュ それぞれを、その配下のテキストノード ID および source text とともに、ドキュメント順で返します。別のハッシュ化されたノードの内側にネストされたハッシュは、個別には返されません。

## `overlayFromDict` [#overlay-dict]

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

`overlayFromDict(hashNodes, dict)` は、各 ハッシュ ノードを 1 つの `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                 | Definition                                                         |
| -------------------- | ------------------------------------------------------------------ |
| `HarvestOptions`     | `harvestLocales` が受け取る、任意のカタログ ローダー、メッセージハッシャー、ソースロケール、cookie 名。 |
| `LocaleTextOverlay`  | `Record<string, Record<number, string>>`                           |
| `TranslationsLoader` | `(locale: string) => Promise<unknown>`                             |
| `TranslationDict`    | `Record<string, GtJsxChildren \| null>`                            |
| `GtJsxChildren`      | GTJSON の child、または children の配列。                                   |
| `GtJsxChild`         | `string \| GtElement \| GtVariable`                                |
| `GtLeaf`             | `{ text: string } \| { variable: true }`                           |

GTJSON のヘルパー型は、overlay 関数が受け取るコンパクトなカタログ表現を表します。独自のハーベストツールを実装する場合に役立ちますが、通常のレコーダーのセットアップでは使用する必要はありません。

## Sitemap

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