# sanity: 序列化
URL: https://generaltranslation.com/zh/docs/sanity/guides/serialization.mdx
---
title: 序列化
description: 自定义 Sanity 文档在翻译时的序列化方式
---

## 概览

该 plugin 会先将 Sanity 文档转换为 HTML 以便翻译，然后再将翻译后的 HTML 反序列化为 Sanity 格式。你可以针对特定字段类型自定义这一流程。

## 序列化的工作原理

1. **序列化**：`gt-sanity` 将文档转换为 HTML
2. **翻译**：HTML 会被发送到 General Translation API 进行翻译。内容会根据目标区域设置重新编排和格式化。
3. **反序列化**：`gt-sanity` 解析翻译后的 HTML，并将其与原始文档合并

## 默认行为

### 会被翻译的类型

序列化器会递归处理以下类型：

* 字符串和文本字段
* Portable Text 块 (段落、标题、列表等) 
* 嵌套对象
* 数组

### 跳过的类型 (排除类型) 

这些类型会被保留，不会被发送进行翻译：

```typescript
const defaultStopTypes = [
  'reference',
  'crossDatasetReference',
  'date',
  'datetime',
  'file',
  'geopoint',
  'image',
  'number',
  'slug',
  'url',
];
```

## 自定义序列化器

在某些情况下，某些字段默认可能无法被正确序列化或反序列化。这时，你可能需要为特定的块类型添加自定义序列化规则。

```typescript title="sanity.config.ts"
import { attachGTData, gtPlugin } from 'gt-sanity';

gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  additionalSerializers: {
    // 用于标记的附加序列化器（自定义注释）
    marks: {
      link: ({ value, children }) =>
        attachGTData(`<a>${children}</a>`, value, 'markDef'),
      inlineMath: ({ value, children }) =>
        attachGTData(`<span>${children}</span>`, value, 'markDef'),
    },
  },
});
```

在上面的示例中，我们使用 `attachGTData` 将额外数据嵌入序列化后的 HTML 中，反序列化器随后会利用这些数据，帮助将翻译后的 HTML 合并回原始文档。


### 序列化函数签名

```typescript
type Serializer = (props: {
  value: any; // Sanity 块/字段的值
  isInline?: boolean; // 是否为内联元素
  children?: string; // 序列化后的子内容
}) => string; // 返回 HTML 字符串
```


## 附加排除类型

防止翻译特定类型：

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  additionalStopTypes: [
    'codeBlock', // 代码片段
    'embedCode', // 第三方嵌入内容
    'mathFormula', // LaTeX/数学公式
    'technicalId', // 内部标识符
  ],
});
```

例如，如果你的 Sanity Studio 使用 Mux input plugin，请同时添加
Mux 视频字段类型和 Mux 资源元数据类型：

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  additionalStopTypes: [
    'mux.video', // Mux 视频字段
    'mux.videoAsset', // Mux 资产元数据
  ],
});
```

Mux plugin 将视频字段存储为 `mux.video`，并且可能会将引用的
资源元数据公开为 `mux.videoAsset`。同时排除这两种类型可防止 GT 发送
视频资源元数据 (例如播放 ID、文件名和处理状态) 
用于翻译。

## 后续步骤

* [设置指南](/docs/sanity/guides/configuration) - plugin 设置选项
* [API 参考](/docs/sanity/api/plugin-config) - 序列化类 API