# General Translation Integrations: 配置 Sanity
URL: https://generaltranslation.com/zh/docs/integrations/sanity/guides/configuring-sanity.mdx
---

title: 配置 Sanity
description: "如何配置 General Translation 的 gt-sanity 插件：本指南涵盖 locales、文档筛选器、字段级本地化、凭据、语言字段和单例文档。"
related:
  links:
    - /docs/integrations/sanity/guides/translating-content
    - /docs/integrations/sanity/guides/managing-translations
    - /docs/integrations/sanity/guides/querying-translations

---

使用 `gtPlugin` 函数配置 General Translation 在 Sanity Studio 中的运行方式。

本指南介绍最常见的选项。完整列表请参阅[插件配置参考](/docs/integrations/sanity/reference/plugin-configuration)。

## 添加 插件 [#add-plugin]

将 `gtPlugin` 添加到你的 Studio 配置中。此步骤在[快速入门](/docs/integrations/sanity/quickstart)中也有介绍。

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

export default defineConfig({
  plugins: [
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'],
      translateDocuments: [{ type: 'article' }, { type: 'page' }],
    }),
  ],
});
```

## 设置 source 和目标区域设置 [#set-locales]

源语言使用 `sourceLocale`，目标语言使用 `locales`。

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
});
```

如果你已经有 `gt.config.json`，可以在插件配置中将其展开。`defaultLocale` 也可以作为 `sourceLocale` 的别名。

```ts title="sanity.config.ts"
import gtConfig from './gt.config.json';

gtPlugin({
  ...gtConfig,
});
```

源区域设置会按以下顺序解析：`sourceLocale`，然后是 `defaultLocale`，最后是库的默认值。如果同时设置了 `sourceLocale` 和 `defaultLocale`，则 `sourceLocale` 优先。

## 添加 language field [#language-field]

翻译内容以独立文档的形式存储。该插件使用 language field 来记录每个文档的区域设置。默认情况下，该字段名为 `language`。

```ts title="schema/article.ts"
import { defineField, defineType } from 'sanity';

export const articleType = defineType({
  name: 'article',
  title: 'Article',
  type: 'document',
  fields: [
    defineField({
      name: 'language',
      type: 'string',
      readOnly: true,
      hidden: true,
    }),
  ],
});
```

如果要使用不同的字段名，请设置 `languageField`，并在你的 schema 中使用相同的名称。

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  languageField: 'locale',
});
```

## 选择要翻译的文档 [#choose-documents]

使用 `translateDocuments` 来筛选可翻译的文档。它支持文档类型过滤器、文档 ID 过滤器，或简写类型字符串。

```ts
// 按文档类型
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ type: 'page' }, { type: 'post' }],
});
```

```ts
// 按指定文档 ID
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ documentId: 'homepage' }, { documentId: 'about-page' }],
});
```

```ts
// 简写类型字符串
gtPlugin({
  sourceLocale: 'en',
  locales: ['es'],
  translateDocuments: ['article', 'page'],
});
```

字符串 entries 会被视为 `{ type: '<string>' }`。`showDocumentInternationalization` 会根据 `type` entries 决定哪些 schema 类型显示语言徽章并应用 templates，因此必须配置文档类型过滤器才能启用这些功能。

## 配置字段级本地化 [#field-level]

默认情况下，`gt-sanity` 按文档级别翻译，为每个区域设置创建一份文档。字段级本地化会将各个区域设置的值都存储在同一份文档中，采用 internationalized array 的形式 (`[{ _key, _type, language, value }]` —— 其结构与 [`sanity-plugin-internationalized-array`](https://github.com/sanity-io/sanity-plugin-internationalized-array) 相同，因此现有数据无需迁移) 。

使用 `internationalizedArray` (或其别名 `fieldLevelLocalization`) 启用 schema 生成，然后将 `translationLevel` 设置为 `'internationalizedArray'`。

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ type: 'post' }],
  internationalizedArray: { enabled: true },
  translationLevel: 'internationalizedArray',
});
```

该插件会根据 `sourceLocale` 和 `locales` 生成 `internationalizedArray*` schema 类型，并提供按各区域设置分别编辑的内联 UI。请在你的 schema 中使用这些生成的类型。

```ts
defineField({
  name: 'title',
  type: 'internationalizedArrayString',
});
```

默认情况下，该插件会生成 `string` 和 `text` 类型。使用 `fieldTypes` 可添加 `block` (Portable Text) 类型或自定义对象定义。

```ts
internationalizedArray: {
  enabled: true,
  fieldTypes: ['string', 'text', 'block', { name: 'seo', type: 'seoFields' }],
},
```

如果要混合使用这两种策略，请将 `translationLevel` 设为 `'mixed'`，并在 `fieldLevelDocuments` 中列出按字段级别翻译的文档类型。

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  translateDocuments: [{ type: 'post' }, { type: 'siteSettings' }],
  internationalizedArray: { enabled: true },
  translationLevel: 'mixed',
  fieldLevelDocuments: [{ type: 'siteSettings' }],
});
```

以原地方式本地化的文档类型会自动从 `@sanity/document-internationalization` 中排除，因此不会显示语言徽章，也不会为每个区域设置生成单独的文档模板。导入时，插件只会更新源文档中的目标区域设置，并保留其他所有语言。

请参阅 [插件配置参考](/docs/integrations/sanity/reference/plugin-configuration#field-level) 了解所有字段级选项。

## 配置单例文档 [#singletons]

对于每个站点只存在一份的文档 (例如站点设置或导航) ，请使用 `singletons`。`singletonMapping` 用于控制如何根据源 ID 和区域设置生成已翻译单例文档的文档 ID。

```ts
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  singletons: ['siteSettings', 'navigation', 'footer'],
  singletonMapping: (sourceDocumentId, locale) => `${sourceDocumentId}-${locale}`,
});
```

如果省略 `singletonMapping`，默认会把 `sourceDocumentId` 和 `locale` 映射到 `` `${sourceDocumentId}-${locale}` `` (例如 `siteSettings-es`) 。

## 存储凭据 [#store-credentials]

该 插件 会从一个私有 Sanity 文档中读取你的 API 密钥和项目 ID；该文档的 `_id` 必须与 `secretsNamespace` 一致 (默认值为 `generaltranslation.secrets`) 。请使用一次性脚本创建该文档。

```js title="populateSecrets.js"
import { getCliClient } from 'sanity/cli';

const client = getCliClient({ apiVersion: '2026-04-06' });

client.createOrReplace({
  _id: 'generaltranslation.secrets',
  _type: 'generaltranslation.secrets',
  secret: process.env.GT_API_KEY,
  project: process.env.GT_PROJECT_ID,
});
```

```bash
GT_API_KEY=your-api-key GT_PROJECT_ID=your-project-id npx sanity exec populateSecrets.js --with-user-token
```

`secret` 字段用作 API Key，`project` 字段用作项目 ID。要从其他文档读取凭据，请将 `secretsNamespace` 设置为该文档的 `_id`。

你也可以将 `apiKey` 和 `projectId` 直接传给 `gtPlugin`，但更推荐使用 secrets 文档，这样凭据就不会被纳入源代码版本控制。当两者同时存在时，运行时会优先使用 secrets 文档。

## 添加可选的 Translations 选项卡 [#translations-tab]

系统会自动添加 **Translate** 文档操作。若还想在文档编辑器中显示 Translations 选项卡，请将 `TranslationsTab` 与 `structureTool` 一起添加。

```ts title="sanity.config.ts"
import { defineConfig } from 'sanity';
import { structureTool } from 'sanity/structure';
import { gtPlugin, TranslationsTab } from 'gt-sanity';

export default defineConfig({
  plugins: [
    structureTool({
      defaultDocumentNode: (S) =>
        S.document().views([
          S.view.form(),
          S.view.component(TranslationsTab).title('General Translation'),
        ]),
    }),
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'zh', 'ja'],
    }),
  ],
});
```
## Next steps

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