# General Translation Changelog: gt-sanity 3.0.0: 原生 Sanity 本地化插件
URL: https://generaltranslation.com/zh/blog/gt-sanity_v3_0_0.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 
Authors: Brian Lou
Published: 2026-07-22

## 概览

`gt-sanity` v3 进一步回归 Sanity 的原生行为。字段级本地化现已改由 [`sanity-plugin-internationalized-array`](https://github.com/sanity-io/sanity-plugin-internationalized-array) 提供支持——也就是 Sanity 的参考插件——而不再使用 GT 自建的 Studio UI；现在你还可以在自己的 schema 中，采用与标准 Sanity 本地化插件相同的基于 `options` 的模式，直接将字段排除在翻译之外。

目标是：`gt-sanity` 负责协调 Sanity 生态中已在维护的插件 (文档级使用 `@sanity/document-internationalization`，字段级使用 `sanity-plugin-internationalized-array`) ，并在此基础上叠加翻译工作流。你的 Studio 不会因为安装了 GT 而改变行为。

***

## 最新动态

### 字段级本地化现已运行在 参考插件之上

启用 `fieldLevelLocalization` (或其别名 `internationalizedArray`) 后，现在会根据你的 `sourceLocale` 和 `locales` 自动配置 `sanity-plugin-internationalized-array`。该原生插件负责 `internationalizedArray*` `schema` 类型以及 Studio 的编辑 UI——包括按语言添加按钮、语言标签和字段操作——因此 Studio 的行为始终与 Sanity 用户已有的使用习惯保持一致，同时也能在上游发布后第一时间获得插件更新。

```ts title="sanity.config.ts"
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'fr', 'ja'],
  translateDocuments: [{ type: 'post' }],
  fieldLevelLocalization: { enabled: true },
  translationLevel: 'internationalizedArray',
});
```

存储的数据本身没有任何变化：各项内容仍然是 `{ _key, _type, language, value }`，因此现有内容无需迁移。config 还新增了原生透传选项：`defaultLanguages`、`buttonLocations`、`buttonAddAll`、`languageDisplay` 和 `apiVersion`。

### 使用你自己的 plugin 实例

如果你已经自行注册了 `sanity-plugin-internationalized-array`，请保持当前 setup。翻译检测基于数据结构——它会读取并写入已存储的数据，无论这些 schema 类型是由谁注册的。请保持 `fieldLevelLocalization` 为禁用状态，以确保这些类型只会注册一次，并使用 `translationLevel` 为文档启用字段级翻译：

```ts title="sanity.config.ts"
plugins: [
  internationalizedArray({
    languages: [
      { id: 'en', title: 'English' },
      { id: 'es', title: 'Spanish' },
    ],
    fieldTypes: ['string'],
  }),
  gtPlugin({
    sourceLocale: 'en',
    locales: ['es'],
    translateDocuments: [{ type: 'post' }],
    translationLevel: 'internationalizedArray',
  }),
],
```

`gt-sanity` 重新导出 `internationalizedArray`、`internationalizedArrayLanguageFilter` 和 `isInternationalizedArrayItemType`，可供直接使用。

### 在 schema 中排除无需翻译的字段

通过直接标记某个字段——或整个类型——即可，无需再在插件配置中维护一份单独的列表：

```ts
defineField({
  name: 'internalNotes',
  type: 'string',
  options: { gt: { exclude: true } },
});
```

该 serializer 也兼容标准 Sanity 本地化插件的排除选项，因此一个模式就能覆盖所有情况：

* `options.gt.exclude` — GT 自身的命名空间
* `options.documentInternationalization.exclude` — `@sanity/document-internationalization`
* `options.aiAssist.exclude` — `@sanity/assist`

排除规则在任意嵌套层级都生效；如果在自定义类型定义的 `options` 中设置，则会排除该类型的所有实例——与原生插件“字段或类型”的语义保持一致。`options.gt` 通过声明合并获得了完整的类型支持，而基于 id 的 `ignoreFields` / `skipFields` / `dedupeFields` 插件选项仍然保留，用于 slug 去重这类跨文档规则。

***

## 不兼容变更

### GT 的字段级 Studio UI 已被移除

`createInternationalizedArrayTypes` 导出项和 `FieldLevelUIComponents` 类型均已移除，同时 `GTFieldLevelLocalizationConfig` 中的 `typePrefix`、`includeCompatibilityTypes` 和 `components` 选项也一并移除——这些都没有对应的原生替代项。传入已移除的选项时，会记录一条警告并将其忽略。使用自定义 `typePrefix` 创建的数据将不再被识别；标准的 `internationalizedArray*` 数据不受影响。

### 更严格的深层 `localize: false` 生效范围

排除规则 (schema 选项和 legacy `localize: false`) 现在也会应用于顶层对象字段内的子字段，而这些字段此前不会被过滤。之前被误发去翻译的内容现在将不再发送——如果升级后某个字段似乎从翻译中“消失”了，请检查它是否带有排除标记。

***

## 链接

* [快速开始](/docs/integrations/sanity/quickstart)
* [配置指南](/docs/integrations/sanity/guides/configuring-sanity)
* [API 参考](/docs/integrations/sanity/reference/plugin-configuration)

## Sitemap

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