# sanity: 插件配置
URL: https://generaltranslation.com/zh/docs/sanity/api/plugin-config.mdx
---
title: 插件配置
description: gtPlugin 配置选项的 API 参考
---

## 概述

`gtPlugin` 函数用于为你的 Sanity Studio 配置 General Translation。

```typescript
import { gtPlugin } from 'gt-sanity'

gtPlugin(config: GTPluginConfig)
```


## GTPluginConfig

<TypeTable
  type={{
sourceLocale: {
type: 'string',
description: '源语言代码（例如 `"en"`）。如果未提供，则回退到 defaultLocale。',
optional: true,
},
defaultLocale: {
type: 'string',
description: 'sourceLocale 的别名。支持此字段，这样你就可以直接展开 gt.config.json。如果两者都设置了，则 sourceLocale 优先。',
optional: true,
},
locales: { type: 'string[]', description: '目标区域设置代码数组' },
apiKey: {
type: 'string',
description: 'GT API 密钥（如果使用 secrets 文档，则为可选）',
optional: true,
},
projectId: {
type: 'string',
description: 'GT 项目 ID（如果使用 secrets 文档，则为可选）',
optional: true,
},
languageField: {
type: 'string',
description: '存储区域设置的文档字段。默认值：`"language"`',
optional: true,
},
singletons: {
type: 'string[]',
description: '视为单例的文档 ID',
optional: true,
},
singletonMapping: {
type: '(docId: string, locale: string) => string',
description:
'用于生成翻译后单例 ID 的函数。默认值：`${docId}-${locale}`',
optional: true,
},
ignoreFields: {
type: 'IgnoreFields[]',
description: '要排除在翻译之外的字段。匹配的字段会在序列化前剥离，并在翻译完成后从源文档恢复。',
optional: true,
},
dedupeFields: {
type: 'DedupeFields[]',
description: '要排除在翻译之外的字段；创建翻译后的文档时，会基于源文档中的值进行初始化，并附加目标区域设置。',
optional: true,
},
skipFields: {
type: 'SkipFields[]',
description: '要从翻译后的文档中完全移除的字段。与 ignoreFields 不同，这些字段完全不会出现在翻译后的文档中。',
optional: true,
},
translateDocuments: {
type: "TranslateDocumentFilter[] | string[]",
description: '用于筛选可翻译文档。接受筛选对象数组，或文档类型字符串的简写数组。',
optional: true,
},
secretsNamespace: {
type: 'string',
description:
'凭据文档的命名空间。默认值：`"generaltranslation"`',
optional: true,
},
additionalStopTypes: {
type: 'string[]',
description: '序列化期间要跳过的附加类型',
optional: true,
},
additionalSerializers: {
type: 'Record<string, Serializer>',
description: '块类型的自定义 HTML 序列化器',
optional: true,
},
additionalDeserializers: {
type: 'Record<string, Deserializer>',
description: '自定义 HTML 反序列化器',
optional: true,
},
additionalBlockDeserializers: {
type: 'BlockDeserializer[]',
description: '自定义块级反序列化器',
optional: true,
},
customMapping: {
type: "Record<string, string | Partial<LocaleProperties>>",
description: '针对非标准区域设置代码的自定义区域设置映射',
optional: true,
},
showDocumentInternationalization: {
type: 'boolean',
description: '为 true 时（默认值），会自动添加 @sanity/document-internationalization 插件，并启用语言徽章、翻译菜单和按语言划分的模板。需要 translateDocuments。',
optional: true,
},
}}
/>

## IgnoreFields

不会被翻译或发送到 API，而是从源文档复制到译文中的字段。可用于分类、标签或内部元数据等需要在所有语言中保持相同值的字段。

```typescript
type IgnoreFields = {
  documentId?: string;
  fields?: Array<{
    property: string;
    type?: string;
  }>;
};
```


### 示例

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  ignoreFields: [
    // 将 category 原样复制到所有翻译后的文档中
    {
      fields: [{ property: '$.category' }],
    },
    // 仅对文章原样复制这些字段
    {
      documentId: 'article',
      fields: [{ property: '$.tags' }, { property: '$.author' }],
    },
  ],
});
```

## DedupeFields

不会被翻译或发送到 API，而是在首次创建翻译后的文档时，从源文档复制并追加目标区域设置后缀的字段。对于应从源文档派生开始、但在每个翻译后的文档中都必须唯一的字段 (例如 Sanity slug) ，请使用此选项。

```typescript
type DedupeFields = {
  documentId?: string;
  fields?: Array<{
    property: string;
    type?: string;
  }>;
};
```

### 示例

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'fr'],
  dedupeFields: [
    // "about" 变为 "about-es" 和 "about-fr"
    {
      fields: [{ property: '$.slug', type: 'slug' }],
    },
  ],
});
```

对于 Sanity 的 slug 字段，plugin 会更新 slug 对象的 `current` 值。例如，当创建西班牙语文档时，`{ _type: 'slug', current: 'about' }` 会变为 `{ _type: 'slug', current: 'about-es' }`。如果编辑者之后更改了已翻译的 slug，后续的翻译导入会保留该编辑后的值。

## SkipFields

会从翻译后的文档中彻底移除的字段。与 `ignoreFields` 不同，这些字段完全不会出现在译文中。对于 SEO canonical URL、仅源文档使用的元数据，或编辑者应按语言手动设置的 slug 等字段，请使用此选项。

```typescript
type SkipFields = {
  documentId?: string;
  fields?: Array<{
    property: string;
    type?: string;
  }>;
};
```

### 示例

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  skipFields: [
    // 编辑者将为每种语言手动设置 slug
    {
      fields: [{ property: '$.slug', type: 'slug' }],
    },
    // Remove source-only debug data from homepage translations
    {
      documentId: 'homepage',
      fields: [{ property: '$.debugInfo' }],
    },
  ],
});
```

## TranslateDocumentFilter

用于筛选可供翻译的文档：

```typescript
type TranslateDocumentFilter = {
  documentId?: string; // 特定文档 ID
  type?: string; // 文档类型
};
```


### 示例

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  translateDocuments: [
    { type: 'article' },
    { type: 'page' },
    { documentId: 'homepage' },
  ],
});
```


## 序列化器

用于将 Sanity 块 转为 HTML 的自定义函数：

```typescript
type Serializer = (props: {
  value: any;
  isInline?: boolean;
  children?: string;
}) => string;
```

### 示例

```typescript
import { attachGTData, gtPlugin } from 'gt-sanity';
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  additionalSerializers: {
    link: ({ value, children }) =>
      attachGTData(`<a>${children}</a>`, value, 'markDef'),
  },
});
```


## 默认排除类型

这些类型会被保留，但不会被发送去翻译：

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

通过 `additionalStopTypes` 添加更多类型：

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  additionalStopTypes: ['codeBlock', 'mathFormula'],
});
```


## 完整示例

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

export default defineConfig({
  plugins: [
    gtPlugin({
      // Required
      sourceLocale: 'en',
      locales: ['es', 'fr', 'de', 'ja'],

      // Document handling
      languageField: 'language',
      singletons: ['siteSettings', 'navigation'],
      singletonMapping: (id, locale) => `${id}_${locale}`,

      // Filtering
      translateDocuments: [{ type: 'article' }, { type: 'page' }],
      ignoreFields: [{ fields: [{ property: '$.publishedAt' }] }],
      dedupeFields: [{ fields: [{ property: '$.slug', type: 'slug' }] }],
      skipFields: [{ fields: [{ property: '$.internalNotes' }] }],

      // 序列化 - 除非您清楚自己在做什么，否则请勿使用此选项！
      additionalSerializers: {
        // 用于标记（自定义注释）的额外序列化器
        marks: {
          link: ({ value, children }) =>
            attachGTData(`<a>${children}</a>`, value, 'markDef'),
          inlineMath: ({ value, children }) =>
            attachGTData(`<span>${children}</span>`, value, 'markDef'),
        },
      },
    }),
  ],
});
```

## 后续步骤

* [配置指南](/docs/sanity/guides/configuration) - 配置方案
* [序列化指南](/docs/sanity/guides/serialization) - 自定义序列化