# sanity: 配置
URL: https://generaltranslation.com/zh/docs/sanity/guides/configuration.mdx
---
title: 配置
description: 为你的 Sanity 项目配置 gt-sanity 插件
---

## 概述

`gtPlugin` 函数接收一个配置对象，用于自定义翻译行为、区域设置以及文档处理方式。

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

export default defineConfig({
  plugins: [
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'], // 替换为您的目标 locales
      languageField: 'language',
      singletons: ['siteSettings', 'navigation'],
    }),
  ],
});
```

## 基本配置

### 源语言和目标 locales

设置源语言和目标 locales：

```typescript
gtPlugin({
  sourceLocale: 'en', // 内容的源语言
  locales: ['es', 'zh', 'ja'], // 翻译的目标语言
});
```

### 使用 `gt.config.json` 中的 `defaultLocale`

如果你已经有 `gt.config.json` (例如在使用 `gt-next` 或 `gt-react` 时创建的) ，可以直接将其展开到 plugin 配置中。`defaultLocale` 字段也可作为 `sourceLocale` 的别名使用：

```typescript
import gtConfig from './gt.config.json';

gtPlugin({
  ...gtConfig, // { defaultLocale: 'en', locales: ['es', 'zh', 'ja'] }
});
```

如果同时提供了 `sourceLocale` 和 `defaultLocale`，则以 `sourceLocale` 为准。


### 语言字段

指定用于存储文档区域设置的字段。默认为 `'language'`：

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  languageField: 'locale', // 默认情况下，文档使用 'language' 字段。此处改为使用 'locale'。
});
```

## 文档筛选

### 翻译特定文档类型

将翻译范围限制为特定文档类型：

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ type: 'page' }, { type: 'post' }],
});
```


### 翻译特定文档

指定文档 ID：

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [
    { documentId: 'homepage' },
    { documentId: 'about-page' },
  ],
});
```


## 单例文档

单例文档是仅有一个实例、但可包含多个翻译变体的 Sanity 文档。配置这些翻译版本的命名方式：

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  singletons: ['siteSettings', 'navigation', 'footer'], // 单例文档 ID 列表
  singletonMapping: (docId, locale) => `${docId}-${locale}`, // 可选函数，用于自定义已翻译单例文档的 ID
});
```

默认情况下，单例文档的翻译会分配随机生成的 id，除非提供了 `singletonMapping`。

## 忽略字段

指你不希望被翻译或发送到 GT API，但仍需从源文档复制到译文中的字段。忽略字段会在序列化前被移除 (因此这些内容绝不会发送到 API) ，然后在翻译后的文档创建后再从源文档恢复。

对于分类、标签或内部元数据这类字段，请使用 `ignoreFields`。这些字段在源文档和翻译后的文档中应保持相同的值，但不需要翻译：

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  ignoreFields: [
    { fields: [{ property: '$.category' }] },       // 所有语言使用相同的分类
    { fields: [{ property: '$..linkType' }] },       // 内部链接元数据
    { fields: [{ property: '$..frequencies.default' }] },
  ],
});
```

`property` 是一个 [JSONPath](https://goessner.net/articles/JsonPath/) 表达式，用于匹配文档中的一个或多个字段。
`type` 是一个可选参数，用于进一步将要忽略的字段限定为特定类型。


## 去重字段

对于你不想翻译或发送到 GT API、但仍需从源文档复制，并在首次创建翻译后的文档时保持唯一的字段，可以使用去重字段。去重字段会在序列化前被移除，随后从源文档中恢复，并附加目标区域设置。

对于 Sanity slug 或其他类似字符串的标识符，如果它们应基于源值、但又必须在每种语言中保持唯一，请使用 `dedupeFields`：

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

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

## 跳过字段

这类字段完全不应自动复制到翻译后的文档中。与 `ignoreFields` (会在译文中保留源值) 不同，`skipFields` 会将匹配到的字段从翻译后的文档中彻底移除。

对于 SEO canonical URL、仅适用于源文档的元数据，或需要由编辑者按语言手动设置的 slug 等字段，应使用 `skipFields`：

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  skipFields: [
    { fields: [{ property: '$.slug', type: 'slug' }] },  // 编辑者需为每种语言手动设置 slug
    { fields: [{ property: '$.canonicalUrl' }] },         // 仅适用于源文档
    {
      documentId: 'homepage',
      fields: [{ property: '$.debugInfo' }],              // 仅源文档使用的调试数据
    },
  ],
});
```

## 序列化选项

扩展默认的序列化行为：

```typescript
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'),
    },
  },
});
```

详情请参阅[序列化指南](/docs/sanity/guides/serialization)。


## 完整示例

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

export default defineConfig({
  name: 'default',
  title: 'My Project',
  projectId: 'your-project-id',
  dataset: 'production',

  plugins: [
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'fr', 'de', 'ja', 'zh'],
      languageField: 'language',
      singletons: ['siteSettings', 'navigation'],
      translateDocuments: [{ type: 'article' }, { type: 'page' }],
      ignoreFields: [
        {
          fields: [{ property: '$.publishedAt' }],
        },
      ],
      dedupeFields: [
        {
          fields: [{ property: '$.slug', type: 'slug' }],
        },
      ],
      skipFields: [
        {
          fields: [{ property: '$.internalNotes' }],
        },
      ],
    }),
  ],

  schema: {
    types: schemaTypes,
  },
});
```

## 后续操作

* [序列化指南](/docs/sanity/guides/serialization) - 自定义序列化规则
* [API 参考](/docs/sanity/api/plugin-config) - 完整配置选项