概述

gt-sanity v2 是一次重大版本发布。此次发布将 plugin 升级为支持 Sanity v5 和 React 19，通过零配置的 translate 对话框简化了 setup，并新增了用于控制哪些字段会显示在翻译后的文档中的选项。

更新内容

更简单的 setup：翻译对话框

v2 中最大的变化，是开发者与翻译界面的交互方式发生了改变。此前，你必须为 structureTool 配置自定义的 defaultDocumentNode，才能在文档中添加“翻译”标签页。现在，plugin 会自动为每个文档添加一个翻译操作，点击后会打开一个包含完整翻译界面的对话框。

这意味着，最小 setup 只需两步：安装 plugin，并将其添加到配置中。

import { defineConfig } from 'sanity';
import { gtPlugin } from 'gt-sanity';

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

TranslationsTab 组件仍然会导出，供偏好专用标签页视图的用户使用，但现在已改为可选。

defaultLocale 配置选项

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

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

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

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

skipFields 选项

新的 skipFields 配置选项会将匹配到的字段从翻译后的文档中彻底移除。这与 ignoreFields 不同：后者会将源文档中的值复制到译文中，而 skipFields 会确保该字段完全不会出现在翻译后的文档里。

对于文档唯一 slug、SEO canonical URL，或仅用于源文档且不应带入译文的元数据等字段，请使用 skipFields：

gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'zh', 'ja'],
  skipFields: [
    { fields: [{ property: '$.slug', type: 'slug' }] },
    { fields: [{ property: '$.canonicalUrl' }] },
  ],
});

相较之下，ignoreFields 用于那些你不希望被翻译、但仍需从源内容复制过来的字段——例如分类、标签或内部元数据，这些字段在所有语言中都应保持相同的值。

与 ignoreFields 一样，你也可以通过 documentId 将跳过规则限定到特定文档，并为 property 使用 JSONPath 表达式。

改进后的 ignoreFields 行为

在 v1 中，被忽略的字段只会在翻译完成后从源文档恢复——内容仍会发送到翻译 API。在 v2 中，被忽略的字段现在会在序列化之前从文档中剔除，因此这些被忽略的内容绝不会发送到 API。

破坏性变更

Sanity v5 和 React 19

gt-sanity v2 需要 Sanity v5+ 和 React 19+。如果你仍在使用 Sanity v3 或 v4，请继续使用 gt-sanity v1。

翻译标签页不再自动注册

plugin 不再自动注册“翻译”标签页视图。默认交互方式现已改为使用“翻译”对话框。如果你仍想保留单独的标签页，可以手动添加——请参阅快速入门。

链接

• 快速入门
• 配置指南
• API 参考