# @focus-reactive/payload-plugin-translator 中文文档

规范地址：https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/

版本：0\.19\.0
npm 元数据更新时间：2026-11-17T11:48:06.742Z
中文译文更新时间：2026-11-17T12:34:25.749Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40focus-reactive/payload-plugin-translator
原文对照：https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/?lang=original
项目主页：https://github.com/focusreactive/payload-plugins/tree/main/packages/payload-plugin-translator
源码仓库：https://github.com/focusreactive/payload-plugins

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

- 包体积（解压后）：863 kB，787 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：8 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，payload ^3\.76\.0，@payloadcms/ui ^3\.76\.0，@payloadcms/richtext-lexical ^3\.76\.0
- 首次发布：2026-03-10T17:12:06.383Z
- 最新版本发布：2026-11-17T11:48:06.320Z
- 近 30 天下载量：7438（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：59（近 12 个月 59 个）

## 中文简介

有效载荷 CMS 3.x.的翻译插件. 使用任意的翻译提供者自动翻译您本地化的内容 .

## 安装

```sh
npm install @focus-reactive/payload-plugin-translator
```

也可以使用：`pnpm add @focus-reactive/payload-plugin-translator`、`yarn add @focus-reactive/payload-plugin-translator`、`bun add @focus-reactive/payload-plugin-translator`

## README

# 有效载荷

**翻译本地化 [有效载荷CMS](https://payloadcms.com/) 内容为 AI 提供者,而不离开管理面板**

选择一个源语言和一个或多个目标;一个背景任务可以填入每个本地化文本,文本区和富文本字段.

[![npm version](https://img.shields.io/npm/v/@focus-reactive/payload-plugin-translator)](https://www.npmjs.com/package/@focus-reactive/payload-plugin-translator) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/focusreactive/payload-plugins/blob/main/packages/payload-plugin-translator/LICENSE)

有效载荷会将您的内容本地化, 但不会翻译它—— 一个编辑器仍然用手复制本地语言之间的文本 。 这个插件会关闭这个空白: 每个本地化的字段都得到翻译, 不管它有多深, 它都坐落在组合, 阵列, 块和标签中, 由您选择的翻译服务 .

## 安装

```bash
npm install @focus-reactive/payload-plugin-translator openai
```

`openai` 这是可选的 —— 它背面的食谱下面, 任何 OpenAI 兼容的端点 都可以代替它 .

| 所需经费 | 版本 |
| --- | --- |
| `payload` | `^3.76.0` |
| `@payloadcms/ui` | `^3.76.0` |
| `@payloadcms/richtext-lexical` | `^3.76.0` |
| `react` | `^19` ——该插件接受 `^18` 也一样,但当前 `@payloadcms/ui` 财务报告和审定财务报表 `@payloadcms/richtext-lexical` 建筑需要19个 |
| `openai` | `^4.50.0` (可选) |

您的有效载荷配置必定有 [本地化](https://payloadcms.com/docs/configuration/localization) 启用,您想要翻译的字段必须被标记 `localized: true`。 。 。 .

> \[注\] 还在 `0.x`:合同在微小的放行之间变化,而下一位大将去掉一个好交易——从不首先贬低它. [版本](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-versioning) 有条件和已经发生的事情的清单.

## 快速启动

将您传递给的相同收藏对象交给插件 `buildConfig`而不是那些从 `payload.collections`原作仍然随身携带 `localized: true` 在筑巢地上.

这是一个完整的配置, 这样它可以按显示运行; 在您的工程中保存自己的数据库适配器, 并设定 `PAYLOAD_SECRET` 在环境开始之前.

```ts
// payload.config.ts
import { sqliteAdapter } from '@payloadcms/db-sqlite'
import OpenAI from 'openai'
import { buildConfig } from 'payload'
import type { CollectionConfig } from 'payload'
import {
  createPayloadJobsRunner,
  createTranslationProvider,
  openAIComplete,
  translatorPlugin,
} from '@focus-reactive/payload-plugin-translator'

const Posts: CollectionConfig = {
  slug: 'posts',
  fields: [
    { name: 'title', type: 'text', localized: true },
    { name: 'summary', type: 'textarea', localized: true },
  ],
}

export default buildConfig({
  collections: [Posts],
  db: sqliteAdapter({ client: { url: 'file:./payload.db' } }),
  localization: { defaultLocale: 'en', locales: ['en', 'de', 'fr'] },
  secret: process.env.PAYLOAD_SECRET ?? '',
  plugins: [
    translatorPlugin({
      collections: [Posts],
      translationProvider: createTranslationProvider({
        complete: openAIComplete({
          client: new OpenAI({ apiKey: process.env.OPENAI_API_KEY }),
          model: 'gpt-5.4-mini',
        }),
      }),
      runner: createPayloadJobsRunner(),
    }),
  ],
})
```

重新生成管理员导入地图, 以便 Biveload 捡取插件的组件 :

```bash
npx payload generate:importmap
```

打开 a `posts` 文档。 翻译控件现在位于文档控件旁边: 选择 `en` 作为来源和 `de` 作为目标,德国的地块在一分钟内填入.

> \[TIP\] 重运行 `payload generate:importmap` 添加或删除后 `documentLevel()` 或者说 `collectionLevel()`,或管理员不受控制. `fieldLevel()` 不添加管理员组件, 因此不需要再生 .

## 尽你所能

-   **翻译一个文档** ——编辑视图上的控件会为您所选择的目标地块排队,选择策略以及是否在填入后公布地块.
-   **翻译整个收藏** ——列表视图上方的仪表板会运行所选文档,或全部,并报告每个地段的进展.
-   **一次翻译为多个地方** —— 说 `targetSelection: 'multi'` 将文档和收藏中的目标字段都变成一个多选择的字段,每个选定的文档都被翻译成你选择的每个地方。 默认为每跑一个地块 .
-   **翻译单个字段** ——控制球场本身,在不排队的情况下就位回答. 两者都需要 `fieldLevel()` 内 `levels` 财务报告和审定财务报表 `withFieldTranslation` 在球场上.
-   **保存时自动翻译** - 将收藏包入 `withAutoTranslate(collection, { targets })` 并编辑源语言 队列 自己翻译, 没有人按任何东西。 在一个有草稿的集合上,它能够等到文件出版;没有草稿,它就向每个保存点开火。 快速编辑合并为一个运行.
-   **保护手写副本** - 那个 `skip_existing` 策略只填充空目标字段,以及 `withFieldTranslation(field, { exclude: true })` 完全保留一个字段的翻译.
-   **引导它如何翻译** —— 说 `systemPrompt` 将发送的指令替换为每个请求, 因此音调、 寄存器、 词汇表、 或品牌名称必须保持不翻译, 由您设定 .
-   **带来任何翻译服务** ——框中一个OpenAI相容的适配器船;其他任何东西都是您所写的单一函数,它接收了文本并返回了回复. 您不分析它, 也不检查它。 这是插件的工作 .
-   **在背景或内含中运行** ——有效载荷工作默认,因此编辑器不会被留等,运行可以被取消或再试. `createSyncRunner()` 转而翻译为内行,用于测试和脚本.
-   **保持丰富的文本完整** ——丰富文本字段的结构活下来了翻译,块类型也是如此. 块和阵列项目也保留其ID,但内部除外 `localized` 容器,每个地方拥有自己的行并获得新鲜行.
-   **零星的翻译** 与 `provenance` 上面,行政官会标出自翻译以来 源头改变的地方, 编辑可以不重新翻译就开除一个旗帜.

**什么样的旅行:** 本地化 `text`, (中文(简体) ), `textarea` 财务报告和审定财务报表 `richText` 字段,在组合、数组、制表符和块内的任何深度。 所有其他字段类型都未改变地到达目标地块.

> \[注\] 在富于文字的段落中,单词顺序跟随源语言,一旦目标语言重排句子,内在强调就可以落在错误的词上. [容器模式](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-experimental-rich-text-one-container-at-a-time),自 `0.13.0` 在选入的旗帜后面 既修补了两个.

> \[大 每个标记 **叶子** 字段 `localized: true` 你自己来 有效载荷让包装器(组、阵列、块、标签)携带 `localized` 并有筑巢的田地继承它,没有它的叶子,就剩它了.
> 
> ```ts
> // Skipped — the nested title is not explicitly localized
> { name: 'meta', type: 'group', localized: true, fields: [{ name: 'title', type: 'text' }] }
> 
> // Translated
> { name: 'meta', type: 'group', localized: true, fields: [{ name: 'title', type: 'text', localized: true }] }
> ```

## 目录

-   [安装](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-install)
-   [快速启动](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-quickstart)
-   [尽你所能](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-what-you-can-do)
-   [配置](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-configuration)
-   [草稿和出版](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-drafts-and-publishing)
-   [翻译提供者](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-translation-providers)
-   [任务执行者](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-task-runners)
-   [访问控制](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-access-control)
-   [生命周期召回](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-lifecycle-callbacks)
-   [证明和陈旧](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-provenance-and-staleness)
-   [HTTP 端点可以调用](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-http-endpoints-you-can-call)
-   [出口参考](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-exports-reference)
-   [实验性:丰富的文本 一次一个容器](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-experimental-rich-text-one-container-at-a-time)
-   [版本](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-versioning)
-   [折旧的别名](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-deprecated-aliases)
-   [解决问题](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-troubleshooting)
-   [许可证](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-license)

## 配置

```
translatorPlugin(config: TranslatorPluginConfig)
```

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `collections` | `CollectionConfig[]` | —— 说 | **要求.** 原始收藏配置来使可变. |
| `translationProvider` | `TranslationProvider` | —— 说 | **要求.** 真正翻译文字的是什么. |
| `runner` | `TaskRunnerProvider` | —— 说 | **要求.** 翻译内容是什么——背景,还是内含. |
| `levels` | `TranslationLevel[]` | `[documentLevel(), collectionLevel()]` | 要启用哪些翻译 . |
| `access` | `AccessGuard` | —— 说 | **要求.** 谁能唤作翻译端点. `new AnyAccessGuard()` 随意打开. |
| `basePath` | `string` | `'/translate'` | 插件端点的基础路径 . |
| `targetSelection` | `'single' | 'multi'` | `'single'` | `'multi'` 让编辑器选择几个目标区域进行一次运行. _从v.1.0._ |
| `provenance` | `boolean | { slug?: string }` | `false` | 添加一个集合,记录每个地方的翻译内容,这样管理员就可以给这些地方贴上标签。 默认弹片 `translator-provenance`。 。 。 . |
| `lifecycle` | `TranslationLifecycleCallbacks` | `{}` | 服务器侧 `onQueued` 编号 : `onCompleted` 编号 : `onFailed` 召回电话. |

### 翻译职等

_自0.5.0起; `fieldLevel()` 从六点半开始._

等级是插件添加的表面. 列出您想要的; 每人最多一次出现 .

| 职等 | 上面写的 |
| --- | --- |
| `documentLevel()` | 在文档编辑视图上翻译弹出. |
| `collectionLevel()` | 列表表上方的批量翻译仪表板. |
| `fieldLevel()` | 打开每个场的控制。 不在默认设定中 . |

```ts
import { documentLevel, collectionLevel, fieldLevel } from '@focus-reactive/payload-plugin-translator'

translatorPlugin({
  collections: [Posts],
  translationProvider,
  runner,
  levels: [documentLevel(), collectionLevel(), fieldLevel()],
})
```

`fieldLevel()` 仅显示在您所包围的字段中 `withFieldTranslation`。 。 。 .

### 外地控制和排除

```ts
import { withFieldTranslation } from '@focus-reactive/payload-plugin-translator'

export const Posts: CollectionConfig = {
  slug: 'posts',
  fields: [
    // A Translate control appears above this input (text, textarea, richText)
    withFieldTranslation({ name: 'title', type: 'text', localized: true }),

    // Never sent to the translation provider (any field type)
    withFieldTranslation({ name: 'sku', type: 'text', localized: true }, { exclude: true }),
  ],
}
```

控件翻译自您选择的源语言,读取 **已保存** 文档在 locate 中的值, 并将结果写入您正在编辑的地方 。 形式上未保存的编辑内容对其来说是隐形的.

控件是输入上方的图标按钮. 它打开一个显示方向的小弹出——一个源 - 本地选择,一个箭头,然后将您正在编辑的地块作为固定目标(`en → fr`) (中文(简体) ). 您选择源; 目标总是位于您的位置 。 请注意,这是文件和收藏控制器的相反方向 _调出_ 你住的地方吗.

控制需要保存的文档, 因此它在您创建时会隐藏 。 其结果以未保存的表单出地——没有保存,没有队列——而一个 Undo 恢复了以前的值.

`withFieldTranslation` 接受 `text`, (中文(简体) ), `textarea` 财务报告和审定财务报表 `richText`; 任何其他类型都是编译错误, 因此通过 `{ exclude: true }` 这些。 块内的字段被支持.

> \[尖叫声\] **本地化软件 `blocks` 或者说 `array` 容器没有每个外地的翻译.** 包好叶子,不是容器 当容器本身是本地化的时,每个地块都拥有自己的顺序和内容,所以没有单一的字段来翻译它们: 控制答案有通知告诉你翻译整个文档,而处理这个案件.

`{ exclude: true }` 表示 _永不将此字段发送给提供者_ -没有 _别管它_。一个被排除的字段在它有目标值时会保留它的目标值,在目标为空时会从源语言被填充(因此一个需要的字段不会在保存时失败验证),并且永远不会被发送去翻译. 排除胜过 `overwrite` 战略.

### 源变化自动翻译

_从v. 9.0._

将一个收藏包包装并编辑到源语言队列中。 在一个收藏 `versions.drafts` 启用此选项会等待文档的发布; 而无需每个保存的草稿都会触发它 。 关闭,除非你选择加入, 一个未触动可转换内容队列的保存 什么都没有.

```ts
import { withAutoTranslate } from '@focus-reactive/payload-plugin-translator'

translatorPlugin({
  collections: [withAutoTranslate(Articles, { targets: ['de', 'fr'], debounceMs: 2000 })],
  translationProvider,
  runner,
})
```

| 密钥 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `targets` | `string[]` | —— 说 | **要求.** 要翻译的语境. 源语言被始终排除. |
| `strategy` | `'overwrite' | 'skip_existing'` | `'overwrite'` | 替换每个目标字段, 或者只填入空域 . |
| `debounceMs` | `number` | `0` | 排队任务运行前的延迟, 合并快速编辑 . |
| `sourceLocale` | `string` | `localization.defaultLocale` | 此收藏的源语言覆盖 . |

> \[大 自动翻译只安排工作。 没有翻译,除非你的跑步者真的运行它 [任务执行者](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-task-runners)。 。 。 .

> \[尖叫声\] **自动翻译出版其所写的.** 其排队的已出版保存的翻译依次发布,而不是作为草稿留下,而且没有设置来阻止它. 如果翻译在启用前需要审查,则从管理员控制中触发翻译,代之以停发翻译.

## 草稿和出版

适用于每个触发器——管理控制, `POST {basePath}/enqueue`,并自动翻译.

下面的一切都描述了一个收藏 `versions.drafts` 启用 . **没有草稿,就没有什么可说的:** 翻译直接写在现场文件上 要求在翻译上发表毫无作用.

**不出版翻译** 译文作为草稿编写。 该文件的已发布状态未受影响:一个活页保留活页,一个未发布者保留活页保留活页,新地块除非有人发布否则不会到达公共网站.

**与出版翻译** 译名作为草稿写出,然后发表目标地语——无论是否实际需要翻译任何字段都会发生这种情况. 只有被翻译的地语被出版;其他地语保持他们当时的状态. 翻译一个目前没有出版的文档确实能让它活下来,只携带着这个地块的内容.

源头是源头的地盘 **拥有当前内容** ——当一个版本存在时,更新的草稿,否则公布的版本,从不从另一个地块中算出一个值的"有效载荷"替代. 翻译 _从_ 您尚未填入的地块 .

在依靠它之前有两个值得知道的后果:

-   **出版出版现行稿件,不论内容如何.** 包括有待编辑的无人翻译,以及非本地化的字段,这些字段每个文件都存储一次,无法覆盖一个地方。 值得在翻译和出版之前记住.
-   **`skip_existing` 计算所翻译的非空的任何东西.** 在草稿中等待未公布的译文,因此评论员更正后的案文按原样公布,而不是再翻译. 它没有概念 _审查_,而过时的治理旗仍然被省略([118号](https://github.com/focusreactive/payload-plugins/issues/118)) (中文(简体) ).

## 翻译提供者

_从v0.11.0._

提供者是一种方法:采取 `{ 0: "Hello", 1: "World" }` 加上源和目标语言,并返回翻译过的同一种密钥。 从单一请求函数中构建一个 `createTranslationProvider`数字 :

```ts
import { createTranslationProvider } from '@focus-reactive/payload-plugin-translator'

const provider = createTranslationProvider({
  complete: async ({ systemPrompt, userContent, responseSchema }) => {
    const reply = await myService.chat({ systemPrompt, userContent, schema: responseSchema })
    return reply.text // return the reply as it came; the plugin reads it
  },
})
```

或执行 `TranslationProvider` 如果您需要完全控制,则直接接口.

### 引导提示

`systemPrompt` 以每个翻译请求取代发送的指令——语气、注册、词汇表或品牌名词的位置,这些名词必须保留在未经翻译的情况下。 它接收源和目标语言代码加上插件会发送的提示,因此可以扩展而不是替换:

```ts
createTranslationProvider({
  complete: openAIComplete({ client, model: 'gpt-5.4-mini' }),
  systemPrompt: ({ sourceLang, targetLang, defaultPrompt }) =>
    `${defaultPrompt}\nUse formal register. Leave product names in ${sourceLang} unchanged.`,
})
```

`sourceLang` 当服务商要检测语言本身时为空.

### OpenAI 和 OpenAI 兼容的网关

`openAIComplete` 与任何显示聊天补全的客户端合作 `chat.completions.create` ——OpenAI SDK,Azure OpenAI,OpenRouter,公司代理. 你构建客户端,所以SDK版本由你来选择.

```ts
createTranslationProvider({
  complete: openAIComplete({
    client: new OpenAI({
      apiKey: process.env.OPENROUTER_API_KEY,
      baseURL: 'https://openrouter.ai/api/v1',
    }),
    model: 'anthropic/claude-sonnet-4.5',
    sampling: { temperature: 0 },
    structuredOutput: 'json_object',
  }),
})
```

`structuredOutput` 选择要求答案的方式 :

-   `'json_schema'` (默认)——答复必须满足一个计划,所以一个符合的模型不能掉出一个字段. 更古老的模型和一些网关以400来拒绝它,而"计划"(schema)有一个可以被非常大的文件所超过的每个模型的地产上限.
-   `'json_object'` ——只要求有效的JSON. 没有天花板,但一个字段,模型在之后作为失败的翻译而浮出水面,而不是被阻止.

`sampling` 只有在设置时才会发出——几个模型直接拒绝参数。 过 `{ temperature: 0 }` 当你想要翻译出同样的方式两次.

> \[注\] `createOpenAIProvider({ apiKey })` 仍然存在,并为您构建客户端。 它被贬为赞成以上两行——见: [折旧的别名](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-deprecated-aliases)。 。 。 .

### 提供者错误

提供者失败作为打出错误运抵,每个错误都有 `code` 和原始失败 `cause`。 。 。 .

| 错误 | `code` |
| --- | --- |
| `NoContentError` | `no-content` |
| `UnparseableReplyError` | `unparseable-reply` |
| `KeySetMismatchError` | `key-set-mismatch` |
| `TransportError` | `transport` |
| `ProviderConfigurationError` | `config` |

全部扩展 `TranslationProviderError`; 代码联盟导出为 `TranslationFailureCode`。 。 。 .

### 没有网络的测试

里面没有内置的假货 自己供应 `complete`,它没有到达,不需要 API 键:

```ts
const fake = createTranslationProvider({
  complete: async ({ userContent }) => {
    const input: Record<string, string> = JSON.parse(userContent)
    return JSON.stringify(
      Object.fromEntries(Object.entries(input).map(([k, v]) => [k, `[de] ${v}`]))
    )
  },
})
```

## 任务执行者

| 运行者 | 行为 |
| --- | --- |
| `createPayloadJobsRunner(options?)` | 在背景中翻译,每个文档一个有效载荷任务。 正常的选择. |
| `createSyncRunner(options?)` | 立即翻译,在呼叫回来之前 没有要运行的队列——方便测试和脚本. |

`PayloadJobsRunnerOptions`数字 :

| 选项 | 类型 | 默认 |
| --- | --- | --- |
| `taskName` | `string` | `'translate_document'` |
| `queueName` | `string` | `'translations'` |
| `jobsCollection` | `CollectionSlug` | `'payload-jobs'` |
| `autoRun` | `false | { cron?: string; limit?: number }` | `{ cron: '* * * * *', limit: 50 }` |
| `staleJobTimeoutMs` | `number` | `300000` |
| `retries` | `{ attempts?: number; backoff?: { delay?: number; type: 'exponential' | 'fixed' } }` | `{ attempts: 3, backoff: { type: 'exponential', delay: 5000 } }` |

> \[尖叫声\] `staleJobTimeoutMs` 翻译时间必须超过一个文件翻译能够合法使用的时间最长。 设置太低,一个仍在运行的译名再次开始——该文件被翻译了两次,并两次计费.

> \[大 Cron 自动运行不会向Vercel等无服务器主机开火,所以任务排队等待. 过 `createPayloadJobsRunner({ autoRun: false })` 将队列从您的 cron 或工人通过 `POST {basePath}/run/:id`。 。 。 .

`createSyncRunner` 保留存储器中运行的状态——最后100个任务,持续一个小时,可调整使用 `maxSize` 财务报告和审定财务报表 `ttlMs`。重启会忘记它们。 除了报告之外,没有什么是丢失的:翻译本身已经写好了.

### 查看已完成的工作

有效载荷会在完成时删除一个工作,因此"完成"状态从未出现在状态面板中. 设定 `jobs: { deleteJobOnComplete: false }` 在你身边 **有效载荷** 配置来保留它们——这是活塞的选择,而不是插件的选择,而用你的方法来管理所积累的东西.

## 访问控制

```ts
import type { AccessGuard } from '@focus-reactive/payload-plugin-translator'

const signedInOnly: AccessGuard = {
  check: ({ req }) => Boolean(req.user),
}

translatorPlugin({ collections, translationProvider, runner, access: signedInOnly })
```

返回时 `false` 请求被驳回 `403 Forbidden`。守护者接收请求头、经认证的用户和有效载荷实例,并且可能是Aync —— 所以角色或权限检查是外出查找,由您自己生成的形状 `TypedUser`。 。 。 .

## 生命周期召回

_从v. 7.0起._

除"相会"外,没有别的设置——没有收藏,没有迁徙. 投出回调被记录, 并且从未失败翻译 .

```ts
translatorPlugin({
  collections,
  translationProvider,
  runner,
  lifecycle: {
    onQueued: (task) => log.info(task, 'translation queued'),
    onCompleted: (task) => log.info(task, 'translation done'),
    onFailed: (task, error) => log.error({ task, error }, 'translation failed'),
    onCancelled: (task) => log.info(task, 'translation cancelled'),
  },
})
```

每个 `task` 携带 `{ collection, id, sourceLng, targetLng, strategy, handle }`。 。 。 . `handle` 名称 翻译该地块的运行 —— 顺序回答给出的值, 以及一个 `DELETE /translate/cancel` 收回来. _从v.16.0起._

每次召回火最多一次 每个目标地区,从来没有尝试: `onQueued` 当赛跑者接球时 `onCompleted`, (中文(简体) ), `onFailed` 或者说 `onCancelled`。 。 。 . **`onFailed` 表示不会翻译语言** ——复试是跑者自己的活儿,不报出,所以没有必要去禁用. _自v.16.0起; `onFailed` 之前对每次失败的尝试都开火._

"最多一次"两个音符. 第二次对一个活运行的地块的要求已经覆盖了连接运行而不是启动另一个,所以两个请求都看到相同的手柄和一组事件. 并宣布取消运行时已经翻译的地块 `onCancelled` 并可能仍然以 `onCompleted`。 。 。 .

## 证明和陈旧

_从v. 7.0起._

设定 `provenance: true` 和插件添加一个集合,用于记录每个文档和目标地块,当该地块被翻译时源的外观。 管理员用它来指代其来源自此已发生变化的旗地,而编辑者可以免去一面旗帜而无需再翻译. 记录类型导出为 `TranslationProvenanceRecord` 如果你想自己看的话.

> \[大 在 SQL 数据库中,此选项会添加一个表格 。 生成并运行迁移( E)`payload migrate:create`,则 `payload migrate`; dev push works in development.). 互联网档案馆的存檔,存档日期2013-12-22. MongoDB推断它没有迁移。 离开 `provenance` 关闭意味着没有收集,没有迁移和行为改变.

> \[注\] **从0.11.1以下升级.** 升级后,一个地方可以读取为过时,不需要重新翻译。 免去正旗或再通译后平定.

## HTTP 端点可以调用

三个终点都是为了你 它们挂在您的有效载荷API路线外加 `basePath` —— 说 `/api/translate/...` - 默认的 - 所有经过 `access` 警卫.

| 方法 | 路径 | 当你需要的时候 |
| --- | --- | --- |
| `POST` | `/enqueue` | 从你自己的代码开始翻译——一个迁移,一个导入,任何脚本. |
| `POST` | `/run/:id` | 执行排队任务 。 任何自动运行的地方都不得开火,如Vercel. |
| `POST` | `/field` | 翻译出一个字段,然后得到结果回来。 仅在 `levels` 包含 `fieldLevel()`。 。 。 . |

`POST /enqueue` 带 `source_lng`, (中文(简体) ), `target_lng` (一个地方或一个清单), `collection_slug` 财务报告和审定财务报表 `collection_id[]`附加可选 `select_all`, (中文(简体) ), `strategy` (单位:千美元)`'overwrite' | 'skip_existing'`默认值 `'overwrite'`和 `publish_on_translation` (默认) `false`) (中文(简体) ). 字段名称为蛇 case.

> \[注\] 插件在相同的路由下挂载更多路由 `basePath` (b) 服务于自己的管理小组——地位、取消和僵化。 它们不是已公布合同的一部分,可在任何发行中更改;驱动插件通过上述三个版本.

## 出口参考

| 导出 | 仁爱 | 目的 |
| --- | --- | --- |
| `translatorPlugin` | 函数 | 插件本身 . |
| `documentLevel`, (中文(简体) ), `collectionLevel`, (中文(简体) ), `fieldLevel` | 函数 | 翻译表面 `levels`。 。 。 . |
| `withFieldTranslation` | 函数 | 附加每个字段的控制,或排除一个字段. |
| `withAutoTranslate` | 函数 | 将一个集合选择为自动翻译 . |
| `createTranslationProvider` | 函数 | 从一个建立提供者 `complete` 函数. |
| `openAIComplete` | 函数 | 聊天补全 `complete` 为您构建的客户端. |
| `createPayloadJobsRunner`, (中文(简体) ), `createSyncRunner` | 函数 | 二法出行一译. |
| `toTaskFilter` | 函数 | 构建文档过滤器,使运行者接受. |
| `TranslationProviderError` 和子类 | 类 | 类型提供者失败 . |
| `TranslatorPluginConfig`, (中文(简体) ), `AccessGuard`, (中文(简体) ), `AccessGuardRequest` | 类型 | 插件配置 . |
| `TranslationProvider`, (中文(简体) ), `TranslationInput`, (中文(简体) ), `TranslationOutput` | 类型 | 供货商合同. |
| `CompletionFn`, (中文(简体) ), `CompletionRequest`, (中文(简体) ), `TranslationProviderConfig` | 类型 | 这个 `complete` 合同. |
| `SystemPromptBuilder`, (中文(简体) ), `SystemPromptContext`, (中文(简体) ), `JsonSchemaObject` | 类型 | 即时定制. |
| `OpenAIClientShape`, (中文(简体) ), `OpenAISamplingParams`, (中文(简体) ), `OpenAIStructuredOutput` | 类型 | OpenAI适配器. |
| `TaskRunnerProvider`, (中文(简体) ), `PayloadJobsRunnerOptions`, (中文(简体) ), `TaskFilter` | 类型 | 任务跑者. |
| `TranslationLevel`, (中文(简体) ), `TargetSelectionMode` | 类型 | 表面与目标选择. |
| `AutoTranslateConfig`, (中文(简体) ), `AutoTranslateStrategy`, (中文(简体) ), `FieldTranslationConfig` | 类型 | 收集与战地配置. |
| `TranslationTask`, (中文(简体) ), `TranslationLifecycleCallbacks` | 类型 | 寿命周期召回. |
| `TranslationProvenanceRecord` | 类型 | 一个存储的出处记录. |

## 实验性:丰富的文本 一次一个容器

> \[尖叫声\] 运入 `0.13.0` 后面 `experimental: { inlineMarks: true }`,默认关闭,并在到达时贬值——下一个主机去掉旗帜,使容器模式成为唯一的模式. 把它当作一个时间表,而不是一个永久的开关:不要建立在选项本身之上.

随着国旗被关闭,一个被翻译的句子会保留出源语言的单词顺序,粗体或链接会最终出现在错误的词上. `a **red** car` 法兰西语又变了 **卢格** voiture——不语法,强调错位.

随着国旗的被打上,整个容器——一个段落,一个标题,一个列表项目——作为一个单一的字符串,其格式被写成编号标记:

```
<1>a </1><2>red</2><3> car</3>
```

您的提供者必须完整地归还这些标记——翻译和重新排列为目标语言需要,但既不翻译自己,也不丢掉。 同样的句子,然后回来作为取出 **卢格**:强调它所属的词,并将旅行与他们的词联系起来.

除非您的提供商声明可以处理标记,否则旗帜什么都不做:

```ts
createTranslationProvider({
  complete: openAIComplete({ client, model: 'gpt-5.4-mini' }),
  capabilities: { inlineMarks: true },
})
```

声明它只是为了一个你信任的服务来还原没有被破坏的标记——一个简单的机器翻译API会翻译或丢掉它们. 一个答复被打碎的容器用其原始语言写出,而不是半译回.

切换后旗只更改未来的翻译;在其下已翻译的文档保持其结构.

## 版本

此软件包已打开 `0.x`这不是一个形式。 水面仍在移动,合同仍在改变,下一个主机会占用相当的金额. 它不会做的是悄悄地行动——这些条件包括:

-   **不先去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去去.** 旧名一直沿用到下一个主修 [`docs/DEPRECATIONS.md`](https://github.com/focusreactive/payload-plugins/blob/main/packages/payload-plugin-translator/docs/DEPRECATIONS.md) 记录为什么每个人都去.
-   **释放跟随分解**,所以破碎的改变 从来没有作为补丁.
-   **之后增加的任何东西 `0.5.0` 说它到达哪一个释放** - 作为一名 _自兹_ 特稿旁边的音符,作为 `@since` 因此你的编辑也回答了问题。 较老的API在会前,没有标记.

已经安排了下个主要课程: [折旧的别名](https://npmcn.com/package/%40focus-reactive/payload-plugin-translator/#readme-deprecated-aliases),则 `experimental.inlineMarks` 当容器模式成为唯一的模式时。 不使用这些,升级是一个版本的凸起.

## 折旧的别名

仍然出口,在下个大调中移除. 背后的推理是: [`docs/DEPRECATIONS.md`](https://github.com/focusreactive/payload-plugins/blob/main/packages/payload-plugin-translator/docs/DEPRECATIONS.md)。 。 。 .

| 折旧 | 改为使用 |
| --- | --- |
| `createTranslatePlugin`, (中文(简体) ), `TranslateCollectionPlugin` | `translatorPlugin` |
| `TranslateCollectionPluginConfig` | `TranslatorPluginConfig` |
| `translateKitField` | `withFieldTranslation` |
| `TranslateKitFieldConfig` | `FieldTranslationConfig` |
| `OpenAITranslationProvider`, (中文(简体) ), `createOpenAIProvider` | `createTranslationProvider` + 键 `openAIComplete` |
| `dryRun` 在提供者配置上 | 属于你的 `complete` 函数 |

## 解决问题

**翻译控制没有出现 .** 运行 `payload generate:importmap` 在注册插件后,并重新启动dev服务器.

**内嵌本地字段被跳过 .** 你通过了消毒的配置. `collections` 必须收到您给的相同对象 `buildConfig` - 有效载荷的消毒条 `localized` 从田地上筑起 在一个本地化的祖先之下.

**工作永远排队.** 没什么能排出排队的 检查自动运行是否启用, 或触发 `POST /api/translate/run/:id` 在cron不运行的平台上.

**`ProviderConfigurationError` 表示该模型不支持 json schema 响应格式, 或该计划被拒绝 .** 模型或网关不会接受计划请求,或者文档太大无法接受. 切换到 `structuredOutput: 'json_object'`。 。 。 .

**非文本字段的每个字段控制 .** `withFieldTranslation` 仅将控件添加到 `text`, (中文(简体) ), `textarea` 财务报告和审定财务报表 `richText`; 必须通过任何其他字段类型 `{ exclude: true }`。 。 。 .

## 许可证

麻省理工学院 [焦点反应](https://focusreactive.com/)

## 常见问题

### @focus-reactive/payload-plugin-translator 是什么？

有效载荷 CMS 3\.x\.的翻译插件\. 使用任意的翻译提供者自动翻译您本地化的内容 \.

### 如何安装 @focus-reactive/payload-plugin-translator？

在项目目录运行 npm install @focus-reactive/payload-plugin-translator，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）、payload（^3\.76\.0）、@payloadcms/ui（^3\.76\.0）、@payloadcms/richtext-lexical（^3\.76\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @focus-reactive/payload-plugin-translator 支持 TypeScript 吗？

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

### @focus-reactive/payload-plugin-translator 支持 ESM 还是 CommonJS？

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

### @focus-reactive/payload-plugin-translator 可以商用吗？

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

### @focus-reactive/payload-plugin-translator 的下载量有多少？

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

### @focus-reactive/payload-plugin-translator 还在维护吗？

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

