# sanity: Serialisation
URL: https://generaltranslation.com/en-GB/docs/sanity/guides/serialization.mdx
---
title: Serialisation
description: Customise how Sanity documents are serialised for translation
---

## Overview

The plugin converts Sanity documents to HTML for translation, then deserialises the translated HTML back into Sanity format. You can customise this process for specific field types.

## How serialisation works

1. **Serialise**: `gt-sanity` converts the document to HTML
2. **Translate**: HTML is sent to the General Translation API for translation. The content is rearranged and reformatted for the target locale.
3. **Deserialise**: `gt-sanity` parses the translated HTML and merges it with the original document

## Default behaviour

### Translated types

The serialiser recursively processes these types:

* Strings and text fields
* Portable Text blocks (paragraphs, headings, lists, etc.)
* Nested objects
* Arrays

### Skipped types (stop types)

These types are preserved and not sent for translation:

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


## Custom serialisers

In some cases, some fields may not be serialised or deserialised correctly by default. In these cases, you may need to add custom serialisation rules for certain block types.

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

gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  additionalSerializers: {
    // Additional serializers for marks (custom annotations)
    marks: {
      link: ({ value, children }) =>
        attachGTData(`<a>${children}</a>`, value, 'markDef'),
      inlineMath: ({ value, children }) =>
        attachGTData(`<span>${children}</span>`, value, 'markDef'),
    },
  },
});
```

In the above example, we use `attachGTData` to embed additional data in the serialised HTML, which is then used by the deserialiser to help merge the translated HTML back into the original document.


### Serialiser function signature

```typescript
type Serializer = (props: {
  value: any; // The Sanity block/field value
  isInline?: boolean; // Whether this is an inline element
  children?: string; // Serialised child content
}) => string; // Returns HTML string
```


## Additional stop types

Prevent specific types from being translated:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  additionalStopTypes: [
    'codeBlock', // Code snippets
    'embedCode', // Third-party embeds
    'mathFormula', // LaTeX/maths content
    'technicalId', // Internal identifiers
  ],
});
```

For example, if your Sanity Studio uses the Mux input plugin, add both the
Mux video field type and the Mux asset metadata type:

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  additionalStopTypes: [
    'mux.video', // Mux video field
    'mux.videoAsset', // Mux asset metadata
  ],
});
```

The Mux plugin stores video fields as `mux.video` and may expose the referenced
asset metadata as `mux.videoAsset`. Blocking both types prevents GT from sending
video asset metadata, such as playback IDs, filenames, and processing status,
for translation.

## Next steps

* [Configuration Guide](/docs/sanity/guides/configuration) - Plugin configuration options
* [API Reference](/docs/sanity/api/plugin-config) - Serialisation class APIs