# General Translation Integrations: 記録の設定
URL: https://generaltranslation.com/ja/docs/integrations/rrweb/guides/configuring-recordings.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: gt-rrweb のキャプチャ、ローカライズされたオーバーレイ、コントロール、自動化、バンドルの取り扱いを設定する方法。

プロダクトウォークスルーのキャプチャ方法、公開済みカタログからのローカライズ、保存方法を設定します。

このガイドは、[Quickstart](/docs/integrations/rrweb/quickstart) でレコーダーをインストールし、translation hash を有効化済みであることを前提としています。

## レコーダーをマウントする [#mount]

[`GTRecorder`](/docs/integrations/rrweb/reference/recorder#gt-recorder) は、翻訳 provider の内側に一度だけマウントします。アプリ内の他の場所にあるコントロールからは、[`useRecorder()`](/docs/integrations/rrweb/reference/recorder#use-recorder) を使って同じモジュールレベルのセッションを開始・停止できます。

```tsx title="src/RecordingTools.tsx"
'use client';

import { GTRecorder } from 'gt-rrweb';
import loadTranslations from './loadTranslations';

export default function RecordingTools() {
  return (
    <GTRecorder
      harvest={{
        loadTranslations,
        sourceLocale: 'en',
      }}
      onComplete={(bundle) => {
        // 完成したバンドルを保存またはアップロードします。
        console.log(bundle);
      }}
    />
  );
}
```

レコーダーによるキャプチャの設定や記録オーバーレイの描画を行わせたくない場合は、`enabled={false}` を設定してください。

## キャプチャリージョンとフレームを設定する [#capture-region]

レコーダーはドキュメント全体をキャプチャします。`contentSelector` は再生時にフレーム表示される製品リージョンを指定するもので、デフォルトは `main, [data-gt-content]` です。

```tsx title="src/RecordingTools.tsx"
<GTRecorder contentSelector="main" frame="16:9" />
```

ウォークスルーを埋め込む場所に応じてフレームを選択してください。

* `frame="none"` はドキュメントのレイアウトを変更せず、記録したビューポート全体を再生します。
* `frame="16:9"` は組み込みのプレゼンテーション用フレームを使用します。
* `frame={{ aspect: 4 / 3 }}` はカスタムの幅と高さの比率を使用します。

カスタム比率には有限の正の値を使用してください。0、負の値、`NaN` は `none` と同じ動作になります。

<Callout type="warn">
  **フレーム付きキャプチャ:** 選択した要素は、記録前に `position: fixed` を使用している必要があります。
  static 配置のコンテンツをフレーム表示すると、ビューポートの外に移動してしまう可能性があります。
  アプリケーションでそのレイアウトを適用できない場合は `frame="none"` を使用してください。
</Callout>

## ローカライズされたリプレイを設定する [#localized-replay]

`gt-rrweb` はキャプチャ中に翻訳を生成しません。まず[翻訳を公開](/docs/cli/guides/generating-translations)してから、それらのカタログをもとにロケールオーバーレイを構築するようレコーダーを設定してください。

### 公開済みカタログの読み込み

`harvest` prop に loader を渡します。loader はロケールを受け取り、そのロケールの公開済みカタログを返します。

```tsx title="src/RecordingTools.tsx"
<GTRecorder
  harvest={{
    loadTranslations,
    sourceLocale: 'en',
  }}
/>
```

loader はローカルファイルの読み取り、コンテンツデリバリーネットワーク (CDN) からの取得、またはアプリケーションと同じソースの利用が可能です。`sourceLocale` には、キャプチャ中に表示されていたロケールを設定してください。省略した場合、ハーベストでは `localeCookieName` で指定された cookie が (設定されていれば) 読み取られ、その後 `start()` に渡された最初のロケールにフォールバックします。解決されたソースロケールは `locales[0]` と一致している必要があります。この最初のエントリは、リプレイ用に記録のソースロケールとしても埋め込まれます。

### ロケールの選択

まず記録されたロケールを渡し、続いてカタログを読み込む対象ロケールをすべて渡します。

```tsx title="src/RecordButton.tsx"
const { start } = useRecorder();

await start({
  locales: ['en', 'es', 'fr', 'ja'],
});
```

ハーベストは、`locales` に 2 つ以上のエントリが含まれている場合にのみ実行されます。ソース言語のみのリストでも、ローカライズされたオーバーレイは付かないものの、有効な記録は生成されます。

### 翻訳済みコンテンツをマッチさせる

[`_tagIds`](/docs/react/reference/config#tag-ids) を有効にすると、[`<T>`](/docs/react/reference/components/t) でレンダリングされたコンテンツに、各カタログエントリとのマッチングに使われる hash が付与されます。変数や値をレンダリングするコンポーネントは、ソースの記録時にキャプチャした値をそのまま保持します。

`gt()` や [`useGT()`](/docs/react/reference/hooks/use-gt) でレンダリングされる素の文字列には、カタログ と同じハッシュ化 pipeline に由来する互換性のある `hashMessage` 関数が必要です。これは高度なインテグレーションポイントであり、`gt-rrweb` はそのハッシュ関数をエクスポートしていないため、通常の setup では [`<T>`](/docs/react/reference/components/t) の hash に依存してください。

翻訳が存在しない場合、plural や branch に単一の描画形式が存在しない場合、翻訳テキストのノード構造が異なる場合、または補間された素の文字列が source template の hash と一致しない場合、コンテンツはソースロケールのまま残ります。カタログ loader の失敗はそのロケール内に限定されるため、他のロケールで完了済みのオーバーレイは引き続き利用できます。より広範なハーベストの失敗も致命的ではなく、バンドル はソースのみの状態となります。

## 記録コントロールをカスタマイズする [#controls]

組み込みの オーバーレイ はキャプチャ中に表示され、セッションを停止するコントロールが含まれます。`labels` を使うと、記録中および停止のテキストを差し替えられます。

```tsx title="src/RecordingTools.tsx"
<GTRecorder
  labels={{
    rec: 'Capturing walkthrough',
    stop: 'Finish recording',
  }}
/>
```

Runtime の文言は見た目のみに影響します。アプリケーション側で [`useRecorder()`](/docs/integrations/rrweb/reference/recorder#use-recorder) を使って独自のコントロールを render することもできます。

## 自動化に制御を公開する [#automation]

エンドツーエンドテストやブラウザ自動化スクリプトからキャプチャを制御する必要がある場合は、`expose` を設定します。レコーダーは、`start` と `stop` を備えた `window[name]` ハンドルを追加します。

```tsx title="src/RecordingTools.tsx"
<GTRecorder expose="gtRecorder" />
```

```js title="record.spec.js"
await page.evaluate(() => window.gtRecorder.start({ locales: ['en', 'es'] }));
// プロダクトのフローを操作する。
const bundle = await page.evaluate(() => window.gtRecorder.stop());
```

`expose` のデフォルト値は `false` です。ブラウザ自動化から直接アクセスする必要がない場合は、無効のままにしておいてください。

## 完了したバンドルを処理する [#bundles]

成功した各記録を保存またはアップロードするには、`onComplete` を渡します。このコールバックはロケールのオーバーレイがハーベストされた後に実行され、`stop()` が返すものと同じ [`RecorderBundle`](/docs/integrations/rrweb/reference/recorder#recorder-bundle) を受け取ります。

このパッケージは記録のアップロードや永続化を行いません。JSON にシリアライズ可能なバンドルは、アプリケーションのアセットとともに保存するか、自身で管理するストレージに保存してください。

<Callout type="warn">
  公開する前に、すべてのバンドルをレビューしてください。フォームの入力値はマスクされますが、イベントストリームにはセッション中に表示されたページのテキストやアプリケーションの状態が依然として含まれています。
</Callout>

## Next steps

- /docs/integrations/rrweb/guides/recording-walkthroughs
- /docs/integrations/rrweb/guides/replaying-recordings

## Sitemap

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