# General Translation Changelog: gt-sanity 2.1.0: 字段级本地化
URL: https://generaltranslation.com/zh/blog/gt-sanity_v2_1_0.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 
Authors: Brian Lou
Published: 2026-07-14

## 概览

`gt-sanity` v2.1 新增了**字段级本地化**：现在，你无需为每个区域设置创建单独的文档，而是可以通过国际化数组将各语言的值存储在同一份文档中。该插件会为你生成 schema 类型，提供内联的按区域设置编辑 UI，并沿用你现有的 GT 工作流来处理翻译——翻译后的值会直接原地合并回源文档。

数据结构与 [`sanity-plugin-internationalized-array`](https://github.com/sanity-io/sanity-plugin-internationalized-array) (`[{ _key, _type, language, value }]`) 保持一致，因此现有的 internationalized-array 内容无需迁移即可直接使用。

***

## 新变化

### 字段级 (国际化数组) 本地化

文档级翻译仍是默认模式：每个区域设置都有各自的文档，并通过 `@sanity/document-internationalization` 关联起来。该模型适用于所有内容都会因语言而变化的文档。

新的字段级模型则保留单个文档，直接在各个字段上进行本地化：

```typescript
{
  _id: 'post-123',
  _type: 'post',
  title: [
    { _key: 'x1', _type: 'internationalizedArrayStringValue', language: 'en', value: 'Hello' },
    { _key: 'x2', _type: 'internationalizedArrayStringValue', language: 'es', value: 'Hola' },
  ],
}
```

使用新的 `internationalizedArray` 选项 (或更具描述性的别名 `fieldLevelLocalization`) 来启用此功能：

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

export default defineConfig({
  plugins: [
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'fr', 'ja'],
      translateDocuments: [{ type: 'post' }],
      internationalizedArray: { enabled: true },
      translationLevel: 'internationalizedArray',
    }),
  ],
});
```

### 生成的 schema 类型

启用后，插件会基于你已传给 `gtPlugin` 的同一组 `sourceLocale` / `locales` 生成 `internationalizedArray*` schema 类型 (例如 `internationalizedArrayString`、`internationalizedArrayText`) ，因此区域设置标识只需定义一次。你可以像使用其他类型一样在 schema 中使用它们：

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

`fieldTypes` 用于控制生成哪些类型。它的默认值是 `['string', 'text']`，支持将 `'block'` 用于 Portable Text，也支持自定义对象定义来表示任意值结构：

```typescript
internationalizedArray: {
  enabled: true,
  fieldTypes: [
    'string',
    'text',
    'block',
    { name: 'seo', type: 'seoFields' }, // 生成 internationalizedArraySeo
  ],
},
```

你也可以用 `typePrefix` 自定义生成的类型名称 (默认会保留标准 `internationalizedArray*` 名称下的兼容别名) ，并通过 `languageTitles` 或 `getLanguageTitle` 自定义 Studio 中显示的区域设置标签。

### 按区域设置分别编辑的内联 UI

生成的类型自带一个专门设计的 Studio 输入组件：每种语言都会渲染为一个带标签的内联编辑器 (没有折叠的对象行或编辑对话框) ，并配有各区域设置各自的添加按钮和删除按钮。源语言不能删除。

如果你更希望使用自己的 UI，`components` 选项允许你覆盖 `input`、`item` 和 `field` 插槽——也可以传入 `false`，回退到 Sanity 的默认渲染。无论采用哪种方式，都不会影响翻译，因为它基于存储的数据，而不是这些组件来运行。

### `translationLevel` 和混合模式

Schema 生成和翻译路由是相互独立的：启用 `internationalizedArray` 只会添加可编辑的字段类型。新的 `translationLevel` 选项用于控制匹配文档的翻译方式：

* `'document'` (默认) — 整篇文档翻译，每个区域设置对应一份文档，这一点与 v2.0 相同。
* `'internationalizedArray'` — 所有匹配文档都会通过国际化数组在原地本地化。
* `'mixed'` — `fieldLevelDocuments` 中列出的文档类型使用数组策略；其余文档则保持文档级别。

```typescript
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'fr'],
  translateDocuments: [{ type: 'post' }, { type: 'siteSettings' }],
  internationalizedArray: { enabled: true },
  translationLevel: 'mixed',
  fieldLevelDocuments: [{ type: 'siteSettings' }], // 原地本地化
});
```

原地本地化的文档类型会自动从 `@sanity/document-internationalization` 中排除，因此不会显示语言徽章，也不会按区域设置生成文档模板。

### 原地导入

字段级文档会沿用你当前使用的同一套 GT 工作流。导入时，译文会合并回同一份文档：只更新目标区域设置，其他所有语言——包括翻译进行期间所做的修改——都不会受影响。

现在，Studio 中的翻译状态在原地导入和页面刷新后也能保持准确，不会再把已完成的翻译显示为“未开始”。

***

## 相关链接

* [快速入门](/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.