# sanity: シリアライズ
URL: https://generaltranslation.com/ja/docs/sanity/guides/serialization.mdx
---
title: シリアライズ
description: 翻訳向けにSanityドキュメントのシリアライズ方法をカスタマイズします
---

## 概要

このプラグインは、Sanity ドキュメントを翻訳用に HTML に変換し、翻訳後の HTML を再び Sanity 形式にデシリアライズします。この処理は、特定のフィールド型に合わせてカスタマイズできます。

## シリアライズの仕組み

1. **シリアライズ**: `gt-sanity` がドキュメントを HTML に変換します
2. **翻訳**: HTML が翻訳のために General Translation API に送信されます。コンテンツは対象ロケールに合わせて並べ替えられ、再整形されます。
3. **デシリアライズ**: `gt-sanity` が翻訳済みの HTML を解析し、元のドキュメントとマージします

## デフォルトの動作

### 翻訳される型

シリアライザは、以下の型を再帰的に処理します。

* 文字列とテキストフィールド
* Portable Text ブロック (段落、見出し、リストなど) 
* ネストされたオブジェクト
* 配列

### スキップ対象の型 (stop types) 

これらの型はそのまま保持され、翻訳用には送信されません。

```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文字列を返す
```


## 追加のstop types

特定のタイプを翻訳対象から除外します。

```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` として公開することがあります。この2つのタイプを両方とも停止すると、再生 ID、ファイル名、処理ステータスなどの
動画アセットメタデータを GT が翻訳のために送信するのを防げます。

## 次のステップ

* [設定ガイド](/docs/sanity/guides/configuration) - プラグインの設定項目
* [APIリファレンス](/docs/sanity/api/plugin-config) - シリアライズクラスのAPI