# General Translation Integrations: Managing translations
URL: https://generaltranslation.com/en-US/docs/integrations/sanity/guides/managing-translations.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: How to import, patch references, bulk publish, and manage field behavior for Sanity translations.

Manage generated Sanity translations after setup with the plugin's translation tools.

This guide covers the site-wide **Translations** tool, reference patching, bulk publishing, field behavior, and custom serialization.

## Use the Translations tool [#translations-tool]

The plugin registers a site-wide **Translations** tool that lists every translatable document. A locale menu beside **Translate All** chooses which target locales the tool acts on. Every target locale starts selected, and the source locale is not listed. From the tool you can:

- Generate translations for every listed document in the selected locales (**Translate All**).
- Preserve current Sanity translations before later runs (**Save local edits**).
- Send current Sanity translations for the selected locales to General Translation without starting a run (**Save Local Edits**).
- Import ready translations in the selected locales, overwriting existing ones (**Import All**).
- Import only translations in the selected locales that are not yet recorded in the source document's metadata (**Import Missing**).
- Patch references in the selected locales (**Patch References**).
- Publish translated documents in the selected locales whose source document is published (**Publish Translations**).

The menu selection is not saved; reloading the Studio selects every target locale again. The six bulk-action buttons stay disabled until at least one locale is selected. **Translate All**, **Import All**, **Import Missing**, and **Save Local Edits** list the selected locales in their confirmation dialog, while **Patch References** and **Publish Translations** start immediately. While you search the menu, selecting all changes only the matching locales. Clearing a locale does not stop a translation that is already running for it.

The document **Translate** dialog has its own locale checkboxes, which do not change this menu.

Auto-refresh and auto-import are on by default. Auto-patch and auto-publish are off. Changes to these switches and **Save local edits** are remembered in browser storage for the current Sanity project and dataset.

*Note: **Import Missing**, **Patch References**, and **Publish Translations** depend on document-level `translation.metadata`. For field-level localization, use **Import All** or import a locale from its status row, then review and publish the source document through Sanity's normal workflow.*

(See [Keep edits to translations](/docs/integrations/sanity/guides/translating-content#preserve-edits) to choose between the toggle and the on-demand action).

## Import translations [#import]

Generated translations must be imported into Sanity. For document-level localization, the plugin merges translated fields into a locale document, so fields that were not sent for translation are carried over. For field-level localization, it merges translated values into the source document's internationalized arrays.

- For a single document, import from the **Translate** action or the optional **General Translation** tab.
- For many documents, use **Import All** or **Import Missing** on the Translations tool. Both follow the locales selected in the tool's menu.

If a document-level translation was deleted while its `translation.metadata` entry remained, importing that locale creates a replacement translation and updates the metadata reference. Use **Import All** or import the locale directly; **Import Missing** skips locales already recorded in metadata. Import fails for a document when its source no longer exists.

## Patch references [#patch-references]

Translated documents may reference other documents. Reference patching rewrites each reference `_ref` to point to the referenced document's translation for the same locale, when one exists. The plugin resolves these from the `translation.metadata` documents.

Use **Patch References** on the Translations tool to update existing translated documents in the selected locales, or turn on **Auto-patch after import** in the single-document dialog. Auto-patch is off by default.

If a translated document is already published and has no draft, patching creates a draft from the published document and updates that draft. It does not change the published document directly.

## Publish translations [#publish]

Use **Publish Translations** on the **Translations** tool to publish translated documents in the selected locales. The plugin publishes only translation documents whose source document is published. This is useful after importing many translations or patching references.

Imported document-level translations are created as drafts. Turn on **Auto-publish after import** to publish them automatically, or leave the default off to review them before publishing.

## Inspect debug information [#debug-info]

The footer of the **Translations** tool and document dialog shows the installed `gt-sanity` version. Click **Debug info** to inspect and copy the plugin's effective setup for a support request.

The output includes resolved locales, translation mode, document and field rules, current preference values, translation counts, the Sanity project and dataset, and whether the secrets document was found. It never includes the API key, only whether one is configured.

## Manage field behavior [#field-behavior]

Use field matchers when some fields should not be translated normally. Each matcher targets fields with a JSONPath `property` expression and, optionally, a document `_id`.

### Copy fields without translating

Use `ignoreFields` for fields that should be copied from the source document but not sent to the translation API, such as categories, tags, or internal metadata.

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  ignoreFields: [
    { fields: [{ property: '$.category' }] },
    { fields: [{ property: '$..linkType' }] },
  ],
});
```

### Copy fields and make them unique

Use `dedupeFields` for fields that should start from the source value but become unique per locale. This is common for slugs.

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  dedupeFields: [{ fields: [{ property: '$.slug', type: 'slug' }] }],
});
```

For a Sanity slug, `{ _type: 'slug', current: 'about' }` becomes `{ _type: 'slug', current: 'about-es' }` for Spanish. If an editor later changes the translated slug, future imports preserve that edited value.

### Remove fields from translations

Use `skipFields` for fields that should not be copied to translated documents at all, such as source-only metadata or slugs that editors set manually per language.

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  skipFields: [
    { fields: [{ property: '$.slug', type: 'slug' }] },
    { fields: [{ property: '$.canonicalUrl' }] },
  ],
});
```

(See the [field matcher reference](/docs/integrations/sanity/reference/plugin-configuration#field-matchers) for the full type).

## Stop custom types from translating [#stop-types]

By default, the plugin preserves a set of non-translatable schema types. Use `additionalStopTypes` to add your own custom types.

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  additionalStopTypes: ['codeBlock', 'mux.video', 'mux.videoAsset'],
});
```

(See the full [default stop types](/docs/integrations/sanity/reference/plugin-configuration#stop-types)).

## Customize serialization [#serialization]

The plugin converts documents to HTML for translation and back. Most projects do not need to change this. Built-in links and other annotations keep their complete `markDef` automatically. Use custom serializers only when your schema has custom marks or block types that the defaults do not handle.

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

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

`attachGTData(html, data, 'markDef')` embeds the mark's data into the serialized HTML so the plugin can rebuild the mark when it merges the translation back. (See the [serialization reference](/docs/integrations/sanity/reference/plugin-configuration#serialization)).

## Next steps

- /docs/integrations/sanity/guides/translating-content
- /docs/integrations/sanity/guides/querying-translations
- /docs/integrations/sanity/guides/configuring-sanity

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.