# General Translation Integrations: 配置录制
URL: https://generaltranslation.com/zh/docs/integrations/rrweb/guides/configuring-recordings.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 如何配置 gt-rrweb 的捕获、本地化叠加层、控件、自动化 以及 bundle 处理。

配置产品导览的捕获方式、如何基于已发布的翻译目录进行本地化，以及如何存储。

本指南假定你已按照 [Quickstart](/docs/integrations/rrweb/quickstart) 安装了录制器并启用了翻译哈希值。

## 挂载录制器 [#mount]

在翻译 provider 内挂载一次 [`GTRecorder`](/docs/integrations/rrweb/reference/recorder#gt-recorder)。应用中其他位置的控件可通过 [`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) => {
        // 保存或上传已完成的 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：

* `frame="none"` 保持文档布局不变，并回放完整的录制视口。
* `frame="16:9"` 使用内置的演示 frame。
* `frame={{ aspect: 4 / 3 }}` 使用自定义宽高比。

请使用有限的正数自定义比例。零、负值和 `NaN` 的行为与 `none` 相同。

<Callout type="warn">
  **带 frame 的捕获：** 所选 element 必须在录制前使用 `position: fixed`。
  对 static 定位的内容进行框定可能会将其移出视口。
  当应用无法采用该布局时，请使用 `frame="none"`。
</Callout>

## 配置本地化回放 [#localized-replay]

`gt-rrweb` 不会在捕获期间生成翻译。请先[发布翻译](/docs/cli/guides/generating-translations)，然后配置录制器，基于这些翻译目录构建区域设置叠加层。

### 加载已发布的翻译目录

通过 `harvest` prop 传入一个加载器。它接收一个区域设置，并返回该区域设置已发布的翻译目录。

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

加载器可以读取本地文件、从内容分发网络 (CDN) 拉取，也可以使用与应用相同的数据源。请将 `sourceLocale` 设置为捕获期间显示的区域设置。若省略该项，采集时会读取由 `localeCookieName` 指定的 cookie (如已配置) ，再回退到传入 `start()` 的第一个区域设置。解析出的源区域设置必须与 `locales[0]` 相同；该首个条目同时会作为录制的源区域设置嵌入，供回放使用。

### 选择区域设置

先传入录制时的区域设置，再依次传入需要加载翻译目录的每个目标区域设置：

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

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

只有当 `locales` 至少包含两个条目时，才会执行采集。仅含源语言的列表仍会生成有效的录制，只是没有本地化叠加层。

### 匹配翻译后的内容

启用 [`_tagIds`](/docs/react/reference/config#tag-ids)，让 [`<T>`](/docs/react/reference/components/t) 渲染的内容携带用于匹配各个目录条目的 hash。变量以及渲染值的组件会保留源录制过程中捕获的值。

由 `gt()` 或 [`useGT()`](/docs/react/reference/hooks/use-gt) 渲染的纯字符串需要一个兼容的 `hashMessage` 函数，且该函数须来自与翻译目录相同的哈希流水线。这属于高级集成点；`gt-rrweb` 并不导出该哈希函数，因此常规 setup 应依赖 [`<T>`](/docs/react/reference/components/t) 的 hash。

出现以下情况时,内容将保留源区域设置:缺少翻译、Plural 或 branch 没有唯一的渲染形式、译文的节点结构不一致,或插值后的裸 string 与其 source template hash 不匹配。翻译目录加载器失败仅影响该区域设置,其他区域设置已完成的叠加层仍然可用。更大范围的采集失败不属于致命错误,只会导致 bundle 中仅包含 source 内容。

## 自定义录制控件 [#controls]

内置叠加层会在捕获期间显示，其中包含用于停止会话的控件。可使用 `labels` 替换其中的录制和停止文本。

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

Runtime 措辞仅影响视觉呈现。你的应用也可以通过 [`useRecorder()`](/docs/integrations/rrweb/reference/recorder#use-recorder) 渲染自己的控件。

## 向自动化工具暴露控制接口 [#automation]

当端到端测试或浏览器自动化脚本需要驱动捕获时，请设置 `expose`。录制器会添加一个 `window[name]` 句柄，其中包含 `start` 和 `stop` 方法。

```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`。如果浏览器自动化不需要直接访问，请保持禁用。

## 处理已完成的 bundle [#bundles]

传入 `onComplete`，用于保存或上传每一次成功的录制。该 callback 会在区域设置叠加层采集完成后执行，并接收与 `stop()` 返回值相同的 [`RecorderBundle`](/docs/integrations/rrweb/reference/recorder#recorder-bundle)。

该 package 不会上传或持久化录制内容。请将可 JSON 序列化的 bundle 与应用资源一起存储，或存放到你自己掌控的存储中。

<Callout type="warn">
  发布前请审校每一个 bundle。表单 input 的值会被遮蔽，但事件流中仍包含会话期间可见的页面文本和应用状态。
</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.