文档 · 报告错误

gt-sanity

一般翻译插件的理智工作室v3。

安装

npm install gt-sanity

快速启动

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

export default defineConfig({
  plugins: [
    gtPlugin({
      sourceLocale: 'en',
      locales: ['es', 'fr'],
      // Initialize translated document slugs with a unique locale suffix,
      // e.g. "hello-world" -> "hello-world-es".
      dedupeFields: [{ fields: [{ property: '$.slug' }] }],
    }),
  ],
});

看到 完整的文档 的指南和API参考。

字段级定位

字段级本地化由 sanity-plugin-internationalized-array - - - - - - 参考Sanity插件。 gtPlugin 为您配置它 地区;gt-sanity没有发布自己的字段级UI，所以Studio的行为 总是匹配本地插件。

gtPlugin({
  sourceLocale: 'en',
  locales: ['es', 'fr'],
  translateDocuments: ['post'],
  // Documents matched above are localized in place with
  // internationalized arrays instead of per-locale documents.
  translationLevel: 'internationalizedArray',
  fieldLevelLocalization: {
    enabled: true,
    fieldTypes: ['string', 'text'],
  },
});

然后在模式中使用生成的类型 （type: 'internationalizedArrayString'等)。

带上你自己的插件实例

已经注册 sanity-plugin-internationalized-array 自己吗?保持 您的setup - GT翻译只读取和写入存储的 { _key, _type, language, value } 数据，不管谁注册的 模式类型。离开 fieldLevelLocalization 禁用，所以类型只有 注册一次，只需将文档选择为字段级翻译即可：

plugins: [
  internationalizedArray({
    languages: [
      { id: 'en', title: 'English' },
      { id: 'es', title: 'Spanish' },
    ],
    fieldTypes: ['string'],
  }),
  gtPlugin({
    sourceLocale: 'en',
    locales: ['es'],
    translateDocuments: ['post'],
    translationLevel: 'internationalizedArray',
    // No fieldLevelLocalization — your plugin instance owns the types.
  }),
],

要验证：打开匹配类型的文档，从 文档操作菜单（或Translations工具），并确认每个本地化 字段获取目标区域设置的项，而Studio UI(每个语言 添加按钮，语言标签)保持与您的插件配置完全一样。

从翻译中排除字段

在模式中标记字段，而不是在插件中维护列表 配置。Gt-sanity尊重它自己 options.gt.exclude 加上排除 标准Sanity本地化插件的选项：

defineField({
  name: 'internalNotes',
  type: 'string',
  options: {
    gt: { exclude: true }, // excluded from GT translation
    // Also honored:
    // documentInternationalization: { exclude: true }, // @sanity/document-internationalization
    // aiAssist: { exclude: true }, // @sanity/assist
  },
});

排除适用于任何深度，包括嵌套对象类型的字段，以及 也可以在自定义类型定义上设置 options 排除每一个 该类型的出现（与本地插件的“字段或类型”匹配） 语义)。遗留 localize: false 字段属性仍然受支持。对于基于id的或 跨文档规则（例如段塞重复数据删除），插件级 ignoreFields / skipFields / dedupeFields 选项仍然可用。

保留对翻译的编辑

翻译后的内容通常会在工作室中进行润色 一般翻译，稍后的翻译运行通常会重新生成它。 这个 保存本地编辑 翻译工具中的toggle会改变： 有了它，翻译目前在理智上传到一般 翻译前先进行一次翻译运行，这样内容的源文本就没有了 从Sanity版本重用而不是重新生成。

这是 默认关闭;打开它显示了对这种权衡的解释 首先，这个选择是为该项目和数据集记住的。打开它意味着本地化 内容覆盖任何通用翻译持有的源版本 包括尚未导入Sanity的完整翻译。 在启用未完成的翻译之前导入它（如果这对您很重要）。

从插件配置中设置切换的初始状态：

gtPlugin({
  // ...
  preserveExistingTranslations: true,
});

上传已经在Sanity中的翻译，而不启动翻译运行 -当在其他地方翻译的项目上采用插件时非常有用- 使用 保存本地编辑． 它会上传所需的源文件，但不会 输入任何翻译。

重新翻译，并故意放弃现有的翻译 运行,使用 从头开始重新翻译 在翻译全部对话框中。

从其他地区翻译

默认情况下，只有文档 sourceLocale 可以翻译。翻译 用另一种语言环境编写的文档-例如，只存在于法语中的页面- 从该文档的翻译对话框中打开 allowNonDefaultSourceLocales：

gtPlugin({
  // ...
  allowNonDefaultSourceLocales: true, // off by default
});

开启后，此类文件的目标包括 sourceLocale。

每个翻译组(a translation.metadata 文档)只有一个 原件，其他文件都是翻译的，不可能是 翻译:

• 任何组中的文件都不是原件。
• 在现有的组中， sourceLocale 文件是原件，和以前一样。
• 当get -sanity首先在外部翻译文档时 sourceLocale，它记录了 那份文件对小组的描述是 gtSourceLanguage，还有 文件成为原件。

一组没有原稿，没有标记，没有 sourceLocale 文件，或 标记原文已被删除-无法翻译。

翻译所有 只适用于 sourceLocale． 它忽略了 在其他地方的原件和他们的翻译，并报告了多少 它跳过了那些原件（已经被早期的翻译标记了）。 保存本地编辑 仅适用于original为in的组 sourceLocale，而领域级本地化总是从 sourceLocale。

把 allowNonDefaultSourceLocales 一旦组被标记，再次关闭 不受支持的。然后，Gt-sanity会忽略该标记，就像它在该选项之前所做的那样 存在，所以 sourceLocale 在另一语言环境中翻译原文是很困难的 按原文处理，可重新翻译。

自动操作

文档上的翻译对话框可以刷新状态，将翻译导入为 它一着陆，就重新指向引用，并发布结果。每个都是一个开关 在该对话框中，每个都有一个插件级别的默认值：

gtPlugin({
  // ...
  autoRefresh: true, // poll for completed translations
  autoImport: true, // import a translation as soon as it completes
  autoPatchReferences: false, // repoint references after import
  autoPublish: false, // publish translated documents after import
});

默认情况下，只打开读取或写入草稿的功能，并删除任何内容 可以触及读者：

• autoRefresh 只有轮询状态和自动导入依赖于它。
• autoImport 写草稿，这是廉价的丢弃。
• autoPatchReferences 通常也写草稿，但当一个翻译 文档已经发布，没有草稿，参考重写是 用于从它衍生出来的草稿，而不是发表的文件。 仍然选择加入，因为它编辑的文档您可能认为已完成。
• autoPublish 发布，关闭开关将不发布任何内容。

这些是起点，而不是锁。无论用户在Studio中设置的是什么 记得在 localStorage 对于该项目和数据集，首选和 在他们下次来访时的配置。这个 保存本地编辑 切换 （preserveExistingTranslations)以同样的方式被记住；仍然启用它 首先显示其解释。

翻译后的文档总是创建为 草稿． 与 autoPublish 从 它们一直保持这种状态，直到有人出版它们——所以如果翻译看起来 在运行后丢失，在假设它不是之前检查草稿透视图 创建。

按地区浏览翻译

默认情况下，翻译后的文档与其源文档位于相同的列表中 Type的列表在每个区域设置中增加一个条目。 gtStructureItems 组织他们 相反：每个可翻译类型展开为每个区域设置的窗格。

import { structureTool } from 'sanity/structure';
import { gtStructureItems } from 'gt-sanity';

structureTool({
  structure: (S, context) =>
    S.list()
      .title('Content')
      .items([
        ...gtStructureItems(S, context),
        S.divider(),
        ...S.documentTypeListItems(),
      ]),
});

这是可选的：结构工具的布局属于 structureTool() 在 你的Studio配置，所以插件不能为你设置它。使用 gtStructure() 为 当没有其他列表项时的整个结构：

import { gtStructure } from 'gt-sanity';

structureTool({ structure: gtStructure() });

源窗格包括语言字段未设置的文档，因为内容 在插件没有语言之前。就地本地化的类型 国际化数组将被跳过——它们的翻译存在于源代码中 文档，所以没有什么要分组的。通过 types 来覆盖哪些类型是 分组, sourceTitle / localeTitle 更改窗格标题。

调试信息

翻译工具页脚显示安装的插件版本和一个 调试 信息 按钮。它打开插件的有效配置解析源 目标地区， translationLevel，匹配哪些文档，字段 规则，活动首选项，以及是否发现了机密文档 一个用于复制支持请求的按钮。

不包括API密钥，只包括是否设置了一个。