# gt-sanity 中文文档

规范地址：https://npmcn.com/package/gt-sanity/

版本：4\.0\.31
npm 元数据更新时间：2026-11-03T18:10:04.736Z
中文译文更新时间：2026-11-03T19:24:52.434Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/gt-sanity
原文对照：https://npmcn.com/package/gt-sanity/?lang=original
项目主页：https://generaltranslation.com/
源码仓库：https://github.com/generaltranslation/gt

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.5 MB，177 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12
- 运行依赖：9 个
- peer 依赖：react \>=19\.2\.0，sanity ^6\.9\.2，@sanity/ui ^4\.0\.1，@sanity/icons ^5\.2\.1，@sanity/schema ^6\.9\.2，@sanity/mutator ^6\.9\.2
- 首次发布：2025-09-17T22:20:13.921Z
- 最新版本发布：2026-11-03T18:10:04.399Z
- 已发布版本数：123（近 12 个月 111 个）

## 中文简介

与Sanity的一般翻译集成

## 安装

```sh
npm install gt-sanity
```

也可以使用：`pnpm add gt-sanity`、`yarn add gt-sanity`、`bun add gt-sanity`

## README

[![General Translation](https://generaltranslation.com/brand/gt-logo-light.svg)](https://generaltranslation.com/docs/sanity)

[**文档**](https://generaltranslation.com/docs/sanity) · [报告错误](https://github.com/generaltranslation/gt/issues)

# gt-sanity

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

## 安装

```bash
npm install gt-sanity
```

## 快速启动

```ts
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' }] }],
    }),
  ],
});
```

看到 [完整的文档](https://generaltranslation.com/docs/sanity) 的指南和API参考。

## 字段级定位

字段级本地化由 [`sanity-plugin-internationalized-array`](https://github.com/sanity-io/sanity-plugin-internationalized-array) - - - - - - 参考Sanity插件。 `gtPlugin` 为您配置它 地区;gt-sanity没有发布自己的字段级UI，所以Studio的行为 总是匹配本地插件。

```ts
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` 禁用，所以类型只有 注册一次，只需将文档选择为字段级翻译即可：

```ts
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本地化插件的选项：

```ts
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的完整翻译。 在启用未完成的翻译之前导入它（如果这对您很重要）。

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

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

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

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

## 从其他地区翻译

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

```ts
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` 在另一语言环境中翻译原文是很困难的 按原文处理，可重新翻译。

## 自动操作

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

```ts
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` 组织他们 相反：每个可翻译类型展开为每个区域设置的窗格。

```ts
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()` 为 当没有其他列表项时的整个结构：

```ts
import { gtStructure } from 'gt-sanity';

structureTool({ structure: gtStructure() });
```

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

## 调试信息

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

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

## 常见问题

### gt-sanity 是什么？

与Sanity的一般翻译集成

### 如何安装 gt-sanity？

在项目目录运行 npm install gt-sanity，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19\.2\.0）、sanity（^6\.9\.2）、@sanity/ui（^4\.0\.1）、@sanity/icons（^5\.2\.1）、@sanity/schema（^6\.9\.2）、@sanity/mutator（^6\.9\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### gt-sanity 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### gt-sanity 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### gt-sanity 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.12。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### gt-sanity 可以商用吗？

gt-sanity 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### gt-sanity 还在维护吗？

最新版本 4\.0\.31 发布于 2026/11/04（今天）；至今共发布 123 个版本，其中过去 12 个月发布了 111 个；首次发布于 2025/09/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。