# @braze/sanity-plugin-ai-translation 中文文档

规范地址：https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/

版本：0\.4\.0
npm 元数据更新时间：2026-11-04T19:30:58.625Z
中文译文更新时间：2026-11-08T14:24:38.374Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40braze/sanity-plugin-ai-translation
原文对照：https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/?lang=original
项目主页：https://github.com/braze-inc/sanity-plugin-ai-translation#readme
源码仓库：https://github.com/braze-inc/sanity-plugin-ai-translation

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

- 包体积（解压后）：845 kB，13 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12
- 运行依赖：13 个
- peer 依赖：react ^19\.2，sanity ^6\.12\.0，react-dom ^19\.2，@sanity/ui ^4，typescript ^5，styled-components ^6\.1，sanity-plugin-internationalized-array ^3\.1\.5 \|\| ^4 \|\| ^5
- 首次发布：2025-10-08T15:50:53.166Z
- 最新版本发布：2026-11-04T19:30:58.389Z
- 近 30 天下载量：3166（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：70（近 12 个月 50 个）

## 中文简介

一个为国际化文档提供AI翻译的Sanity Studio插件.

## 安装

```sh
npm install @braze/sanity-plugin-ai-translation
```

也可以使用：`pnpm add @braze/sanity-plugin-ai-translation`、`yarn add @braze/sanity-plugin-ai-translation`、`bun add @braze/sanity-plugin-ai-translation`

## README

# @braze/sanity-plugin-ai-翻译

一个添加 AI 动力的 Sanity Studio 插件 **翻译** 用于国际化内容的文件行动.

-   **默认提供者 :** 卫生代理动作( U)`client.agent.action.translate()`(中文(简体) )
-   **可选提供者 :** OpenAI( 通过 Sanity 函数) 用于大型文档/ 长样式向导
-   **输出 :** 翻译创建为 **内容版内版本文档** (分阶段出版)
-   **额外 :** 翻译引用文件、词汇表术语、被保护的短语、调试日志、字段排除和字段转换(便携式文本+标题)

**编辑:** 见独立用户指南 `docs/user-guide.md`。 。 。 .

* * *

## 目录

-   [此插件会做什么](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-what-this-plugin-does)
-   [先决条件](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-prerequisites)
-   [安装](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-install)
-   [配置( Studio)](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-configure-studio)
    -   [1) 配置文档国际化](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-1-configure-document-internationalization)
    -   [(2) 添加 AI 翻译插件](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-2-add-the-ai-translation-plugin)
    -   [(3) 添加翻译历史元数据](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-3-add-translation-history-metadata)
    -   [(4) 部署代理行动计划](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-4-deploy-schema-for-agent-actions)
-   [可选: OpenAI 模式](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-optional-openai-mode)
-   [用户指南(供编辑使用)](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-user-guide-for-editors)
    -   [翻译文档](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-translate-a-document)
    -   [选择内容发布](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-choose-a-content-release)
    -   [翻译选项](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-translation-options)
    -   [翻译引用文档](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-translate-referenced-documents)
    -   [创建什么](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-what-gets-created)
-   [内容配置(设置和词汇表)](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-content-configuration-settings--glossary)
    -   [`translationSettings`](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-translationsettings)
    -   [`translationGlossaryTerm`](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-translationglossaryterm)
-   [高级配置](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-advanced-configuration)
    -   [翻译中不包括字段](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-exclude-fields-from-translation)
    -   [外地转换](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-field-transforms)
    -   [货币和深度](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-concurrency-and-depth)
-   [调试出错( D)](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-debugging--troubleshooting)
-   [开发( 本回购)](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-development-this-repo)
-   [许可证](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-license)

* * *

## 此插件会做什么

当您在 Sanity Studio 打开文档时( 对于配置的 schema 类型), 插件会添加一个 **翻译** 行动。 你可以这样:

1.  选择一个或多个 **目标语言**
2.  选择 :
    -   是否从草案或已公布的版本翻译
    -   发布翻译内容(新或已有)
    -   是否也翻译引用的文档(带有深度控制)
3.  使用 :
    -   **危险代理动作** (违约),或
    -   **开放AI** (可选)

现存的译名总是被完整地再翻译;没有部分或只翻译模式.

翻译为: **版本文档** 在一个 **内容发布**,所以你可以审查并公布在您的日程表.

* * *

## 先决条件

您的工作室必须支持国际化的文件 .

要求 :

-   **卫生工作室 v 6. 12 或更新** 与 `@sanity/ui` v4,反应19.2+,和节点.js 22.12+ (插件通过 Studio 的客户端引用 Sanity 函数,需要 `@sanity/client` 8.3+; 第6.12工作室是捆绑它的第一个发布)
-   `@sanity/document-internationalization` 配置
-   `sanity-plugin-internationalized-array` 安装和配置(用于词汇翻译)
-   `@sanity/client` **7.1.0+ (单位:千美元)** (代理行动需要)

代理行动也需要:

-   您的策略必须部署在 Sanity , 这样 Agent Action 可以访问它(参见 [部署计划a](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-4-deploy-schema-for-agent-actions)(中文(简体) )
-   **重要的 API 版本要求 :** 客户端必须使用 `apiVersion: 'vX'` (不是日期版本). 基于日期的版本可能导致Agent Actions失败.

* * *

## 安装

使用您的工作室软件包管理器( 例如使用) `pnpm`:

```sh
pnpm add @braze/sanity-plugin-ai-translation
```

若你还没有安装

```sh
pnpm add @sanity/document-internationalization sanity-plugin-internationalized-array
pnpm add @sanity/client@^7.1.0
```

* * *

## 配置( Studio)

### 1) 配置文档国际化

此插件旨在与 `@sanity/document-internationalization`。先配置它.

您通常会将您的支持语言定义为:

```typescript
const SUPPORTED_LANGUAGES = [
  { id: "en-us", title: "English" },
  { id: "es", title: "Spanish" },
  { id: "fr", title: "French" },
];
```

然后为您要翻译的策略类型启用国际化:

```typescript
documentInternationalization({
  supportedLanguages: SUPPORTED_LANGUAGES,
  schemaTypes: ["post", "page"],
  languageField: "language", // your language field name (example)
});
```

### (2) 添加 AI 翻译插件

添加 `aiTranslationPlugin()` 之后 `documentInternationalization()`数字 :

```typescript
import { defineConfig } from "sanity";
import { documentInternationalization } from "@sanity/document-internationalization";
import { aiTranslationPlugin } from "@braze/sanity-plugin-ai-translation";

const SUPPORTED_LANGUAGES = [
  { id: "en", title: "English" },
  { id: "es", title: "Spanish" },
  { id: "fr", title: "French" },
];

export default defineConfig({
  // ...your config...
  plugins: [
    documentInternationalization({
      supportedLanguages: SUPPORTED_LANGUAGES,
      schemaTypes: ["post", "page"],
      languageField: "language",
    }),

    aiTranslationPlugin({
      supportedLanguages: SUPPORTED_LANGUAGES,
      translatableSchemaTypes: ["post", "page"],
      languageFieldName: "language",
      schemaId: "_.schemas.default",
      maxConcurrentTranslationJobs: 5,
      maxReferenceDepth: 3,
    }),
  ],
});
```

**页:1**

-   `schemaId` 通常为 `'_.schemas.default'` 大多数项目.
-   `languageFieldName` 必须匹配文档使用的字段(通常 `language`) (中文(简体) ).
-   `glossaryDataset` (可选)从同一项目的另一个数据集读取词汇术语. 见 [`translationGlossaryTerm`](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-translationglossaryterm)。 。 。 .

### (3) 添加翻译历史元数据

此插件可以通过您附加到的元数据计划存储翻译历史 `documentInternationalization`。 。 。 .

添加 `translationHistorySchema`数字 :

```typescript
import { translationHistorySchema } from "@braze/sanity-plugin-ai-translation";

documentInternationalization({
  supportedLanguages: SUPPORTED_LANGUAGES,
  schemaTypes: ["post", "page"],
  languageField: "language",
  metadataFields: [translationHistorySchema],
});
```

### (4) 部署代理行动计划

特工行动需要进入你的部署计划.

从您的 Studio 项目目录 :

```sh
npx sanity deploy
```

如果代理动作因与计划相关的错误而失败, 请重新检查 :

-   计划部署
-   `schemaId`
-   客户端 `apiVersion` 设置为 `'vX'` (不基于日期)

* * *

## 可选: OpenAI 模式

OpenAI模式是可选的. 如果启用, 用户可以选择 **开放AI** 作为翻译对话框中的翻译提供者.

工作室从不给OpenAI打电话或持有OpenAI API密钥. 它把组装的快件发送到一个已部署的 Sanity 功能 `client.functions.invoke(..., { sync: true })`,使用编辑室会话. 该函数使 OpenAI 调用 [服务器条目](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-server-entry) 并返回已翻译的文本.

示例配置 :

```typescript
aiTranslationPlugin({
  supportedLanguages: SUPPORTED_LANGUAGES,
  translatableSchemaTypes: ["post", "page"],
  languageFieldName: "language",
  schemaId: "_.schemas.default",

  openai: {
    enabled: true,
    stackId: "ST-xxxxxxxx", // blueprint stack that contains the function (required)
    functionName: "ai-translation",
    model: "gpt-6.1-sol", // one of OPENAI_MODELS; set it explicitly in production
    reasoningEffort: "medium", // 'low' | 'medium' | 'high'
    defaultMode: "openai-only", // 'sanity-only' | 'openai-only'
  },
});
```

**所需资源**

-   工作室的 Sanity 客户端必须是 `@sanity/client` 8.1或较新,增加 `client.functions.invoke`。如果是旧的,对话框显示 OpenAI 模式为不可用 .
-   在堆栈中必须部署带有所配置名称的 pubsub 函数 。 写着 `OPENAI_API_KEY` 从它自己的环境,允许列表模型,并返回 `requestOpenAICompletion`。 。 。 .
-   函数超时必须足够长的时间用于推理呼叫. 至少使用120秒; Sanity允许最多900秒. 插件等待引用的时间可达900秒.

**警卫**

-   不要在 Studio 配置或捆绑中放置 OpenAI API 密钥 。 它只属于函数环境中.
-   发送到功能上的有效载荷只包含信息、模型和推理努力。 它由客户端提供,因此功能必须验证它,并且不得将其中的任何字段当作身份检查.

**为什么使用OpenAI模式?**

-   较长文档和长样式指南的更大有效上下文窗口
-   确定序列化/去序化以保留结构
-   严格结构验证,防止数据腐败

**费用**

-   OpenAI 调用会根据符号使用产生 API 费用 .
-   每个请求中的稳定部分(全球快取,地语快取,词汇表,被保护的词组,指令)在文档之前发送,因此OpenAI的缓存输入定价适用于每一个被翻译为同一种语言时.

### 模型

`openai.model` 必须是其中之一 `OPENAI_MODELS` (从联合国出口) [服务器条目](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-server-entry)) (中文(简体) ). 该列表也是唯一的支出守护,因为任何工作室用户都可以引用翻译功能:不允许亲级,O系列或3.5型.

| 型号 | 预定用途 |
| --- | --- |
| `gpt-6.1-sol` | 默认. 每日营销与文献页面. |
| `gpt-6.1-terra` | 批量运行或低评分页的预算选项. |
| `gpt-6-luna` | 草稿和测试. |
| `gpt-6-astra` | 法律版或旗舰版的专注费. |
| `gpt-5.1`, (中文(简体) ), `gpt-5`, (中文(简体) ), `gpt-5-mini` | 上一代, 仍然支持已经使用它们的工作室 . |

`DEFAULT_OPENAI_MODEL` (单位:千美元)`gpt-6.1-sol`当 `model` 省略。 设定 `model` 因此,一个插件升级不能默默地改变工作室使用哪种模式和价格.

### 服务器条目

插件在 `@braze/sanity-plugin-ai-translation/server` 用于在浏览器外运行 OpenAI 调用(例如,在 Sanity 函数中)。 它不装入 React 或 Studio,它不是 Studio 捆绑的一部分,也不从环境中读取 API 密钥,所以被调用者传入.

```typescript
import {
  DEFAULT_OPENAI_MODEL,
  isOpenAIModel,
  OPENAI_MODELS,
  requestOpenAICompletion,
} from "@braze/sanity-plugin-ai-translation/server";

// payload: { model, messages, reasoningEffort?, temperature? } assembled in Studio
if (!isOpenAIModel(payload.model)) {
  throw new Error(`model must be one of ${OPENAI_MODELS.join(", ")}`);
}
const { content, tokensUsed } = await requestOpenAICompletion(payload, {
  apiKey: process.env.OPENAI_API_KEY!,
});
```

第一个论据是客户端提供的请求,并在运行时被验证. 第二种持有服务器侧配置,如API密钥,从未从有效载荷读取.

-   超过20个信件的请求,或总共超过1,000,000个信件内容字符,在发送到OpenAI之前被拒绝.
-   仅 `role` 财务报告和审定财务报表 `content` 每个消息都会被发送。 有效载荷中的任何其他场被投放.
-   日志从不包含即时文本或文档文本,即使打开了插件日志。 它们只包括模型,消息角色,以及内容长度.

串行化,即时组装,结构验证,以及内容发布书写都留在工作室. 该条目不自行允许列表模型. 在打电话之前先在电话里说 `isOpenAIModel` (或 `OPENAI_MODELS`这是相同的列表 `openai.model` 插件选项接受,因此 Studio 和函数绝不对允许哪个模型有异议. GPT-5和GPT-6型号被送入了Resolution API;其他型号家庭回落到Chat Refulations.

#### 运行翻译元数据

插件将每个翻译记录在 `translation.metadata` 一旦在内容发布中创建了该版本。 当该发布被删除或版本被丢弃时,条目仍然会指向被移除的文档. `pruneTranslationMetadata` 删除 `translations` 财务报告和审定财务报表 `translationHistory` 目标已不复存在的条目。 保留作为已公布文件、草稿或任何发行版本仍然存在的目标。 存档的放出对象也是这样:存档删除了放出版本,并解除存档恢复了它们,所以它们的条目必须活下来.

该插件已经浏览了将要翻译的每个文档的元数据 。 要删除文档立即删除, 请部署一个删除事件“ Sanity” 函数 . `functions/` 在这个回购中是一个实例:

```typescript
// sanity.blueprint.ts
defineDocumentFunction({
  name: "prune-translation-metadata",
  event: {
    on: ["delete"],
    filter: "_type in ['course', 'lesson']", // your translatableSchemaTypes
    includeAllVersions: true,
    projection: "{_id}",
  },
});
```

```typescript
// functions/prune-translation-metadata/index.ts
import { pruneTranslationMetadata } from "@braze/sanity-plugin-ai-translation/server";
import { createClient } from "@sanity/client";
import { documentEventHandler } from "@sanity/functions";

export const handler = documentEventHandler(async ({ context, event }) => {
  const client = createClient({ ...context.clientOptions, apiVersion: "vX", useCdn: false });
  await pruneTranslationMetadata({ client, documentIds: [event.data._id] });
});
```

过 `dryRun: true` 以获取不写任何东西而删除的条目.

要清理已有的数据集, 请运行 `functions/scripts/fix-translation-metadata.mjs`。它会拖动条目,然后将同一源的重复元数据文档合并为最古老的。 如果两个重复在不同的活文件上指向同一种语言,脚本会报告该组,而不改变. 除非你通过,否则就完了 `--apply`。首先构建插件(`pnpm build`),然后在未进行翻译的情况下运行 :

```bash
SANITY_PROJECT_ID=... SANITY_DATASET=... SANITY_WRITE_TOKEN=... pnpm --filter ./functions fix-metadata
SANITY_PROJECT_ID=... SANITY_DATASET=... SANITY_WRITE_TOKEN=... pnpm --filter ./functions fix-metadata -- --apply
```

`SANITY_WRITE_TOKEN` 在数据集中需要编辑器角色或更高.

* * *

## 用户指南(供编辑使用)

### 翻译文档

1.  在 Studio 中打开其类型包含的文档 `translatableSchemaTypes`。 。 。 .
2.  打开文档动作菜单并单击 **翻译**。 。 。 .
3.  选择一种或多种目标语言.
4.  配置翻译选项(见下文).
5.  点击 **翻译** 然后进行飞行前检查 **翻译** 再次开始.

翻译时,您会看到每种目标语言的工作状态(如果启用的话,还会看到任何引用的文件)。 每个工作都带有文档的图案预览标题的标签,同样的标签工作室列表使用. **视图** 将完成的翻译用被绑住的放出窗格用新窗格打开,所以标题显示在放出决心中的真实标题和引用. 将发行版将整个工作室切换到它,而不只是新的面板:在切换回草稿之前,编辑到任何文档都会进入该发行版.

### 选择内容发布

翻译总是在 **内容发布**。 。 。 .

在对话框中,您通常可以:

-   创建新发布,或
-   将翻译添加到已有的活跃发行中

需要时使用释放 :

-   分阶段审查
-   一次协调出版多种译名

### 翻译选项

对话框提供 :

-   **从草稿翻译 / 从公布的草稿翻译**
    -   源文件的哪个版本(及其参考文献)被翻译.
-   **内容发布**
    -   创建新发行, 或者选择一个已有的活跃发行来添加翻译内容 .
-   **翻译参考文献**
    -   还翻译参考文件并更新本地化版本点的参考文献.
-   **最大参考深度**
    -   跨度参考图表(深度) `0` 意思是没有转弯).
-   **提供者** (仅在启用 OpenAI 模式时)
    -   Sanity Agent Actions or OpenAI. (原始内容存档于2018-09-25). Sanity Agent Actions.

现有译名总能被完整地再译. 没有覆盖的切换, 也没有任何 diff 唯一的模式: 发行时持有完整的新译名, 您在出版前审查它 .

### 飞行前检查

点击 **翻译** 首先进行飞行前检查 翻译只开始于通过时 :

-   **验证**:每个要翻译的文档都必须通过它的计划验证. 有错误的文档被列出,链接打开并修正它们,然后 **重新扫描**。 。 。 .
-   **未公布的参考资料更改**: 列出带有草稿的引用文档,以便确认草稿或已公布的来源是你想要的.
-   **现有译文汇编草稿**:如果即将被替换的译名有未公布的草稿,对话框会警告草稿会过时. 从显示的链接中发布或丢弃每个草稿,或单击 **继续吧** 继续,不管怎样.
-   **释放冲突**: 当添加到已经包含同一文档和语言版本的现有版本中时,对话框会显示相互冲突的翻译,并要求您选择:
    -   **取消** 回去选择另一个释放,
    -   **全部替换** 删除发行中的现有版本并创建新的版本,或
    -   **跳过冲突** 只翻译非冲突文档/语言对.

### 翻译引用文档

如果您启用引用翻译 :

-   该插件会穿行引用( 最多到所配置的深度) .
-   它翻译符合条件的引用文件(类型包括: `translatableSchemaTypes`) (中文(简体) ).
-   它更新了翻译文件中的参考文献,以指向本地化版本.

这对内容如:

-   参考作者员额
-   参考共享章节
-   参考相关内容的文件

### 创建什么

对于每个选定的目标语言,插件创建一个 **已版本文档** 在选定的内容发布中.

当引用被翻译时,翻译版本中的引用被重写到被翻译的目标上,即工作室本身链接未发表文件的方式: `_weak: true` 与 `_strengthenOnPublish: { type }`. 它们在发布时成为了强烈的参考,因此发布时没有验证错误而发布,而Studio可以使发布外的字段出场.

那样你就可以:

-   审查和编辑翻译版本
-   准备好就发布

* * *

## 内容配置(设置和词汇表)

插件引入了两种文档类型用于配置 :

### `translationSettings`

以 `_id == "translation-settings"` 来配置 :

-   **全球提示** (适用于所有翻译)
-   **语言提示** (按目标语言说明)
-   **受保护的短语** (从未翻译这些名词;例如:品牌名)

示例形状 :

```typescript
{
  _type: 'translationSettings',
  _id: 'translation-settings',
  globalPrompt: 'Maintain a professional tone. Preserve formatting and links.',
  localePrompts: [
    {_key: 'es', value: 'Use formal Spanish (usted).'},
    {_key: 'fr', value: 'Use formal French.'},
  ],
  protectedPhrases: ['Braze', 'iOS', 'Android', 'SDK']
}
```

注释:

-   `localePrompts` 用途 `_key` 用于本地地址( 必须与您的 `supportedLanguages[].id`) (中文(简体) ).
-   被保护的短语可以被过滤到仅出现在源文档中的短语(以保持提示较小).

### `translationGlossaryTerm`

创建术语表文档,强制对关键术语进行一致翻译.

这个计划用的是 `internationalizedArrayString` 您可以提供每个地方一个值.

概念实例:

```typescript
{
  _type: 'translationGlossaryTerm',
  translations: [
    {_key: 'en', value: 'dashboard'},
    {_key: 'es', value: 'panel de control'},
    {_key: 'fr', value: 'tableau de bord'},
  ]
}
```

词汇名词用于构建针对地语的翻译指令.

默认情况下,术语表从正在翻译的文件的数据集中读取. 共用一个数据集的词汇表 `glossaryDataset` 到同一工程中的另一个数据集:

```typescript
aiTranslationPlugin({
  // ...
  glossaryDataset: "production",
});
```

-   术语与编辑室现有的会话一起读取,因此编辑需要读取该数据集的访问权限.
-   只有词汇表术语来自 `glossaryDataset`。 。 。 . `translationSettings` (global proone, locale proones, 被保护的短语)仍然从文档的数据集读取.
-   这两套数据集的词汇表都没有写入任何内容.

* * *

## 高级配置

### 翻译中不包括字段

使用 `excludeFields` 防止某些字段被翻译(slugs, enums, 旗帜等).

支持 :

-   字段名称在任何地方匹配(例如). `'status'`(中文(简体) )
-   精确路径( 例如 ). `'seo.title'`(中文(简体) )
-   数组路径/通配符(例如). `'body[*].imageType'`(中文(简体) )

示例

```typescript
aiTranslationPlugin({
  // ...
  excludeFields: ["slug", "status", "seo.canonicalUrl", "body[*].variant"],
});
```

重要行为:

-   插件将 **没有** 允许 `languageFieldName` 将被排除在外。 如果包含的话,会被去除以防止翻译出错.
-   Sanity系统字段`_id`, (中文(简体) ), `_type`, (中文(简体) ), `_key`, (中文(简体) ), `_rev`, (中文(简体) ), `_createdAt`, (中文(简体) ), `_updatedAt`,以及任何其他 `_`\- 前置字段)从不需要排除. 两个提供者都没有翻译它们: Agent Action 从 id 的数据集读取文档, OpenAI 序列器跳过 `_`\-前置钥匙 以它们为目标的模式(例如: `_id` 或者说 `body[*]._key`)被以警告而忽略,因为剥去它们会去掉id和管道所依赖的密钥.

### 外地转换

一些字段(如可移植文本或标题格式)在翻译前从转换中受益.

在此序列中运行的变换 :

1.  过滤排除字段
2.  应用变换( 生成可变表示)
3.  翻译( 聖物代理或 OpenAI)
4.  恢复变换( 回到原始结构)
5.  恢复排除字段(语言除外)
6.  在发行时创建版本文档

内置变迁包括:

-   `richTextTransform` 便携式文本
-   `vttCaptionTransform` vTT 标题
-   `wistiaCaptionTransform` 用于 Wistia 标题( 如果您的计划使用)

示例设置 :

```typescript
import {
  aiTranslationPlugin,
  richTextTransform,
  vttCaptionTransform,
  wistiaCaptionTransform,
} from "@braze/sanity-plugin-ai-translation";

aiTranslationPlugin({
  // ...
  fieldTransforms: [
    {
      ...vttCaptionTransform,
      matcher: { schemaType: "video", fieldName: "captions" },
    },
    {
      ...wistiaCaptionTransform,
      matcher: { schemaType: "videoDoc", fieldName: "wistiaCaptions" },
    },
    richTextTransform,
  ],
});
```

**秩序事项:** 第一场比赛获胜.

### 货币和深度

-   `maxConcurrentTranslationJobs` 控制同时运行的翻译数量(默认行为是保守的).
-   `maxReferenceDepth` 控制引用的深度(设置为 `0` 以禁用 traversal .

* * *

## 调试出错( D)

### 启用调试日志

此插件使用一个集中调试日志 。 输出默认关闭 。 要打开它, 请在主机工作室中设置此环境变量, 然后重新启动 dev 服务器或重建( 值在构建时内含) :

```sh
# Standalone Sanity Studio
SANITY_STUDIO_AI_TRANSLATION_PLUGIN_LOGGING=true

# Studio embedded in Next.js
NEXT_PUBLIC_SANITY_STUDIO_AI_TRANSLATION_PLUGIN_LOGGING=true
```

要关闭, 删除变量或设置到其它值 .

### 共同问题

**代理动作立即失败**

-   确认 `@sanity/client` 实值 **7.1.0+ (单位:千美元)**
-   确认您的客户端 API 版本 `apiVersion: 'vX'` (不基于日期)
-   确认计划已部署: `npx sanity deploy`
-   确认 `schemaId` 匹配您部署的策略( 通常 `'_.schemas.default'`(中文(简体) )

**翻译完成但内容没有改变**

-   确保文档类型包含在内 `translatableSchemaTypes`
-   请检查排除字段或变换是否阻碍更新
-   如果使用 OpenAI 模式, 结构验证可以拒绝修改非文本字段的翻译

**引用翻译缓慢**

-   减少 `maxReferenceDepth`
-   减少 `maxConcurrentTranslationJobs`
-   确保您不会不必要地翻译大参考图

* * *

## 开发( 本回购)

此寄存器是一个 pnpm 单列波 :

-   `package/` ——插件包
-   `demo-nextjs/` 用嵌入式工作室演示 Next.js 应用程序

常见命令 :

```sh
pnpm dev
pnpm build

cd package
pnpm test
pnpm typecheck
pnpm lint
```

CI (中文(简体) )`.github/workflows/ci.yml`运行 `biome ci`,插件类型检查、测试套件和插件基于每个拉出请求和推出 `main`。 。 。 .

检查一下 [服务器条目](https://npmcn.com/package/%40braze/sanity-plugin-ai-translation/#readme-server-entry) 对抗真实的 OpenAI API, 运行 `pnpm check:openai-server` 从 repo 根或从 `package/`它写着: `OPENAI_API_KEY` 来自环境或 `.env` 文档。 见 `package/scripts/README.md` 详细情况.

* * *

## 许可证

麻省理工学院

## 常见问题

### @braze/sanity-plugin-ai-translation 是什么？

一个为国际化文档提供AI翻译的Sanity Studio插件\.

### 如何安装 @braze/sanity-plugin-ai-translation？

在项目目录运行 npm install @braze/sanity-plugin-ai-translation，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.2）、sanity（^6\.12\.0）、react-dom（^19\.2）、@sanity/ui（^4）、typescript（^5）、styled-components（^6\.1）、sanity-plugin-internationalized-array（^3\.1\.5 \|\| ^4 \|\| ^5）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @braze/sanity-plugin-ai-translation 支持 TypeScript 吗？

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

### @braze/sanity-plugin-ai-translation 支持 ESM 还是 CommonJS？

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

### @braze/sanity-plugin-ai-translation 需要什么版本的 Node\.js？

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

### @braze/sanity-plugin-ai-translation 可以商用吗？

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

### @braze/sanity-plugin-ai-translation 的下载量有多少？

根据 npm 官方下载统计，@braze/sanity-plugin-ai-translation 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,166 次，日均约 106 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @braze/sanity-plugin-ai-translation 还在维护吗？

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