返回

gt-sanity@2.1.0

Brian Lou avatarBrian Lou
gt-sanityv2.1.0sanitycmstranslationminor

概览

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

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

新变化

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

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

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

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

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

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 中使用它们：

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

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

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 中列出的文档类型使用数组策略；其余文档则保持文档级别。
gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'fr'],
  translateDocuments: [{ type: 'post' }, { type: 'siteSettings' }],
  internationalizedArray: { enabled: true },
  translationLevel: 'mixed',
  fieldLevelDocuments: [{ type: 'siteSettings' }], // 原地本地化
});

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

原地导入

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

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

链接