# General Translation Integrations: Configuring recordings
URL: https://generaltranslation.com/en-US/docs/integrations/rrweb/guides/configuring-recordings.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: How to configure gt-rrweb capture, localized overlays, controls, automation, and bundle handling.

Configure how product walkthroughs are captured, localized from your published catalogs, and stored.

This guide assumes you installed the recorder and enabled translation hashes in the [Quickstart](/docs/integrations/rrweb/quickstart).

## Mount the recorder [#mount]

Mount [`GTRecorder`](/docs/integrations/rrweb/reference/recorder#gt-recorder) once inside your translation provider. Controls elsewhere in the app use [`useRecorder()`](/docs/integrations/rrweb/reference/recorder#use-recorder) to start and stop the same module-level session.

```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) => {
        // Save or upload the completed bundle.
        console.log(bundle);
      }}
    />
  );
}
```

Set `enabled={false}` when the recorder should not configure capture or render its recording overlay.

## Set the capture region and frame [#capture-region]

The recorder captures the whole document. `contentSelector` identifies the product region framed during playback and defaults to `main, [data-gt-content]`.

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

Choose a frame based on where you will embed the walkthrough:

- `frame="none"` leaves the document layout unchanged and replays the full recorded viewport.
- `frame="16:9"` uses the built-in presentation frame.
- `frame={{ aspect: 4 / 3 }}` uses a custom width-to-height ratio.

Use a finite positive custom ratio. Zero, negative values, and `NaN` behave like `none`.

<Callout type="warn">
  **Framed capture:** The selected element must use `position: fixed` before
  recording. Framing static-positioned content can move it outside the
  viewport. Use `frame="none"` when the application cannot apply that layout.
</Callout>

## Configure localized replay [#localized-replay]

`gt-rrweb` does not generate translations during capture. [Publish your translations](/docs/cli/guides/generating-translations) first, then configure the recorder to build locale overlays from those catalogs.

### Load published catalogs

Pass a loader through the `harvest` prop. It receives a locale and returns that locale's published catalog.

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

The loader can read local files, fetch a content delivery network (CDN), or use the same source as your application. Set `sourceLocale` to the locale visible during capture. If you omit it, harvesting reads the cookie named by `localeCookieName`, when configured, and then falls back to the first locale passed to `start()`. The resolved source locale must equal `locales[0]`; that first entry is also embedded as the recording's source locale for replay.

### Choose locales

Pass the recorded locale first, followed by every target locale whose catalog should be loaded:

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

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

Harvesting runs only when `locales` contains at least two entries. A source-only list still produces a valid recording without localized overlays.

### Match translated content

Enable [`_tagIds`](/docs/react/reference/config#tag-ids) so content rendered by [`<T>`](/docs/react/reference/components/t) carries the hash used to match each catalog entry. Variables and value-rendering components keep the value captured during the source recording.

Bare strings rendered by `gt()` or [`useGT()`](/docs/react/reference/hooks/use-gt) require a compatible `hashMessage` function from the same hashing pipeline as the catalog. This is an advanced integration point; `gt-rrweb` does not export that hasher, so ordinary setup should rely on [`<T>`](/docs/react/reference/components/t) hashes.

Content remains in the source locale when a translation is missing, a plural or branch has no single rendered form, translated text has a different node structure, or an interpolated bare string does not match its source template hash. A catalog-loader failure is isolated to that locale, so completed overlays for other locales remain available. A broader harvesting failure is non-fatal and leaves the bundle source-only.

## Customize the recording controls [#controls]

The built-in overlay appears during capture and includes the control that stops the session. Use `labels` to replace its recording and stop text.

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

Runtime wording is visual only. Your application can also render its own controls with [`useRecorder()`](/docs/integrations/rrweb/reference/recorder#use-recorder).

## Expose controls to automation [#automation]

Set `expose` when an end-to-end test or browser automation script needs to drive capture. The recorder adds a `window[name]` handle with `start` and `stop`.

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

```js title="record.spec.js"
await page.evaluate(() => window.gtRecorder.start({ locales: ['en', 'es'] }));
// Drive the product flow.
const bundle = await page.evaluate(() => window.gtRecorder.stop());
```

`expose` defaults to `false`. Leave it disabled when browser automation does not need direct access.

## Handle completed bundles [#bundles]

Pass `onComplete` to save or upload each successful recording. The callback runs after locale overlays are harvested and receives the same [`RecorderBundle`](/docs/integrations/rrweb/reference/recorder#recorder-bundle) returned by `stop()`.

The package does not upload or persist recordings. Store the JSON-serializable bundle with your application assets or in storage you control.

<Callout type="warn">
  Review every bundle before publishing it. Form input values are masked, but the event stream still contains visible page text and application state from the session.
</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.