# General Translation Knowledge Base: 如何在 Payload CMS 中翻译内容？
URL: https://generaltranslation.com/zh/kb/translate-payload-content.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 在 Payload 配置中添加 localization，并为每个字段设置 localized true；此后 Payload 会为每个区域设置存储一个值，但不会自动填充。General Translation 的 gt-payload 插件会添加一个“翻译”按钮，用于写入每个目标区域设置：启用草稿时以草稿形式写入，否则直接写入。它从不发布内容。
Category: 工作流工具
Last updated: 2026-10-28
Authors: General Translation Team
Published: 2026-10-28

Payload CMS 在字段级别存储译文。配置中加入 `localization` 块后，每个标记为 `localized: true` 的字段都会在同一文档中为每个区域设置保存一个值，前端则通过 `locale` 参数请求对应语言。Payload 本身不会生成这些值，而填充它们又相当繁琐：Lexical 富文本 (Payload 的默认编辑器) 包含链接、标记和嵌入块；数组和块中嵌套着本地化字段；slug、关联关系和上传文件必须保持原样；此外，编辑人员对译文的修改也不应在下次更新时被覆盖。

## Payload 如何存储译文

在 Payload 3 中，本地化是 Payload 核心配置的一部分 ([Payload 本地化文档](https://payloadcms.com/docs/configuration/localization)) 。只需一次性列出所有区域设置：

```ts title="src/payload.config.ts"
import { buildConfig } from 'payload';

export default buildConfig({
  // ... 现有配置
  localization: {
    locales: ['en', 'es', 'fr'], // 或包含 code、label、rtl 和 fallbackLocale 的对象
    defaultLocale: 'en',
    fallback: true, // 默认值：缺失的值会回退到默认区域设置的值
  },
});
```

然后标记每个需要翻译的字段。`localized: true` 适用于任何具名字段，包括数组和块；本地化容器内的嵌套字段会变为按区域设置区分的集合。Payload 提醒，对已有数据的字段更改 `localized` 会导致该字段的现有数据丢失，因此请在加载内容之前确定好。

所有 API 都接受区域设置参数。REST 使用 `?locale=es` 和 `?fallback-locale=none`，GraphQL 接受 `locale` 和 `fallbackLocale` 参数，Local API 也支持相同的选项：

```ts
// 返回西班牙语值；若字段没有西班牙语值，则回退到英语
const page = await payload.findByID({ collection: 'pages', id, locale: 'es' });

// 仅返回西班牙语值；未翻译的字段返回为空
const strict = await payload.findByID({ collection: 'pages', id, locale: 'es', fallbackLocale: false });

// 一次性返回所有区域设置：all.title 为 { en: 'Pricing', es: 'Precios' }
const all = await payload.findByID({ collection: 'pages', id, locale: 'all' });
```

在一个 Payload 3.92 测试应用中，某个页面仅有英语和西班牙语标题，请求 `fr` 时默认返回英语标题；设置 `fallbackLocale: false` 后则返回空标题。这一默认行为值得留意：未翻译的区域设置不会报错，而是悄然返回源语言内容。

## 翻译 Payload 内容的几种方式

Payload 的官方插件包括 SEO、Redirects、Search 和 Import/Export，但都不提供内容翻译功能 ([Payload 插件](https://payloadcms.com/docs/plugins/overview)) 。可选方案如下：

| 方案                                                                                                 | 优势                                                                       | 译文如何写入 Payload                                                  | 需要你自行处理的工作                                                         |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------ |
| 编辑人员按区域设置逐一手动输入                                                                                    | 译者可在管理面板中直接看到每个字段                                                        | 切换管理面板的区域设置，逐一输入每个值                                             | 全部翻译工作，以及每次修改源内容后找出有变动的字段                                          |
| Payload 的 [Import/Export 插件](https://payloadcms.com/docs/plugins/import-export)，配合译者或翻译管理系统 (TMS)  | 将某个区域设置导出为 CSV 或 JSON，方便习惯基于文件翻译的人员                                      | 将翻译后的文件导入目标区域设置                                                 | 确保富文本、块和行 ID 在导出再导入的过程中保持完整，并在内容编辑后重新导出                           |
| 基于 AI API (OpenAI API、Claude API) 编写脚本                                                             | 一次运行即可翻译大量文档，并可在提示词中指定语气和术语                                              | 由你的脚本通过 `payload.update({ locale })` 写入                         | 遍历嵌套字段和 Lexical JSON、为每个字符串提供上下文、保持术语一致、审校以及重新运行                   |
| [Lingo.dev](https://lingo.dev/guides/payload) (`@lingo.dev/payloadcms`)                            | 保存源内容时自动翻译本地化文本和富文本                                                      | 由其托管服务写入每个区域设置，可直接发布或保存为草稿                                      | 需要 Lingo.dev 的 Enterprise 方案、带 API 密钥的 Payload 服务用户，以及 Lexical 编辑器 |
| General Translation (`gt-payload`)                                                                 | 翻译本地化的 `text`、`textarea` 和 Lexical `richText` (包括嵌套块) ，并应用项目的词汇表和自定义提示词 | 通过每个文档上的 **翻译** 按钮，或对整个站点执行一次运行，写入每个区域设置；如已启用草稿，则以草稿形式写入 | 在源内容编辑后启动运行、审校各区域设置的译文，以及发布草稿                                      |

如果文档数量不多，且每种语言都有专门的译者，可以手动输入译文。如果翻译工作已交由代理机构或 TMS 负责，并以文件形式进行，请使用 Import/Export。如果只是一次性批处理，且有专人审校，可以使用 AI API 脚本。如果文档包含富文本和块、更新频繁，并且需要与你的应用和文档保持术语一致，请使用 General Translation。 (两种服务的详细对比，请参阅 [General Translation 与 Lingo.dev 对比](/kb/general-translation-vs-lingo-dev)。)

## 使用 gt-payload 翻译 Payload 内容

General Translation 的 `gt-payload` 插件 (MIT 许可，版本 0.1.2) 要求：Payload 3.90.0 或更高版本且已配置 `localization`、Next.js 15.2.9 或更高版本、React 19.0.1 或更高版本，并且至少有一个本地化字段。

1. 使用 `npm install gt-payload` 安装插件。

2. 将插件添加到你的配置中。插件会从 Payload 读取你的区域设置和本地化字段，因此在常见场景下无需传入任何选项：

   ```ts title="src/payload.config.ts"
   import { buildConfig } from 'payload';
   import { gtPlugin } from 'gt-payload';

   export default buildConfig({
     // ... 你现有的配置
     localization: {
       locales: ['en', 'es', 'fr'],
       defaultLocale: 'en',
     },
     plugins: [gtPlugin()],
   });
   ```

3. 在运行 Payload 的服务器上设置 `GT_PROJECT_ID`，并将具有 **All** 权限的[项目 API 密钥](/docs/platform/dashboard/reference/api-keys#create-project-keys)设置为 `GT_API_KEY`。切勿将该密钥暴露给客户端代码。

4. 运行 `npx payload generate:importmap`，以便管理面板加载插件的组件。如果使用 PostgreSQL 或 SQLite，还需为插件新增的两个集合创建并应用迁移 (先运行 `npx payload migrate:create`，再运行 `npx payload migrate`) 。

5. 打开一个已保存的文档，选择 **翻译**，勾选目标区域设置，然后选择 **翻译为 …**。如需翻译全部内容，请改为在管理导航中打开 **Translations**。

在一个基于 Payload 3.92.1 的测试应用中，该插件已将其文档控件、**Translations** 视图以及 `gt-translation-runs` 和 `gt-translation-locks` 集合添加到导入映射和生成的类型中，且 `next build` 构建成功。插件的端点会拒绝未登录 Payload 用户发出的请求。完整步骤请参阅 [Payload 快速入门](/docs/integrations/payload/quickstart)。

## 翻译运行会做什么

该插件以默认区域设置作为源，将每个文档的本地化文本发送到你的 General Translation 项目，这些文本在项目中以其 Payload 标识 (`collection/id`，或全局配置的 slug) 显示。它会翻译本地化的 `text` 字段 (包括 `hasMany` 列表) 、`textarea` 字段以及 Lexical `richText`，无论这些字段位于组、标签页、数组、块还是富文本块中。富文本会保留其中的标记、链接、上传内容和块；如果某个字符串的标记无法与源匹配，该字符串会被跳过并报告，而不会写入损坏的内容。

以下内容不会被处理：slug 字段，只读、隐藏和虚拟字段，看起来像 URL、路径或电子邮件地址的 `text` 值，以及关联关系、上传、日期、数字和 ID。若要跳过某个字段 (例如 SKU) ，请在该字段上设置 `custom: { gt: { translate: false } }`。当译文超出字段的 `maxLength` 时，插件会请求更短的译文；只有仍然超长时，才会在单词边界处截断并添加省略号。 (参见[支持的内容](/docs/integrations/payload/reference/supported-content)。) 

翻译结果会写入同一文档中对应的各个目标区域设置。启用了[草稿](https://payloadcms.com/docs/versions/drafts)的集合和全局配置会生成草稿，其余则直接保存。插件从不执行发布。运行记录存储在 Payload 中，因此关闭标签页后仍会继续：下次访问管理后台时会恢复运行；如果配置了 `jobs.autoRun`，则由 Payload 的[任务队列](https://payloadcms.com/docs/jobs-queue/overview)完成。单个文档或区域设置失败不会撤销其他已完成的结果。

## 审校、发布并保留修改

在 Payload 的编辑器中逐个审校各区域设置，并按照你平常的 Payload 权限进行发布；插件的各项控件遵循当前登录用户的访问规则。如果编辑者在 Payload 中修正了某条译文，请在 **Translations** 抽屉中开启 **Save local edits before translating** (默认关闭) ，或选择 **Save local edits**，这样 General Translation 在后续运行中就会保留该措辞。保存后，Payload 中的值将成为唯一可信来源，并覆盖 General Translation 为该文档保存的内容。 (参见[管理翻译](/docs/integrations/payload/guides/managing-translations)。) 

翻译质量取决于上下文。为项目分配一个[上下文分组](/docs/platform/dashboard/guides/defining-context-for-translations)后，其词汇表和自定义提示词将指导每一次 Payload 运行，确保产品名称或方案等级在 CMS 页面和应用中的译法保持一致。如需在自己的代码中 (例如钩子或定时任务) 发起翻译，请调用 `gt-payload` 中的 [`translateDocument`](/docs/integrations/payload/reference/api#translate-document) 或 `translateSite`。用量按 [General Translation 的定价](https://generaltranslation.com/pricing)计费。

多语言网站的其他方面 (例如按语言区分的 URL 和 `hreflang`) 请参见[如何让网站支持多语言？](/kb/make-website-multilingual)。如需在其他 CMS 中完成同样的任务，请参见 [Sanity](/kb/translate-sanity-content) 和 [Storyblok](/kb/translate-storyblok-content) 的相关文章。

## 要点总结

* Payload 3 按字段存储译文：在配置中添加 `localization`，设置 `localized: true`，并通过 `locale` 和 `fallback-locale` 读取。
* 在默认的 `fallback: true` 设置下，尚未翻译的区域设置会直接返回源文本，因此在上线某种语言的链接之前，请先检查翻译覆盖率。
* Payload 没有官方翻译插件，但可以借助其 Import/Export 插件，将某个区域设置的内容导出为 CSV 或 JSON，交给译者处理。
* General Translation 的 `gt-payload` 提供了 `gtPlugin()`、**翻译** 按钮和全站范围的 **Translations** 页面；它可以翻译已本地化的 text、textarea 和 Lexical 富文本字段，并在启用草稿的情况下将每个区域设置保存为草稿，绝不会直接发布。
* 开启 **Save local edits before translating**，即可确保在 Payload 中所做的修改在后续运行中不会被覆盖。

## Related questions

- [如何在 Sanity 中翻译内容？](https://generaltranslation.com/zh/kb/translate-sanity-content.mdx): 将每种语言存储为独立文档，或在每个字段中按区域设置分别存储值，然后将源内容翻译为每个目标区域设置。General Translation 的 gt-sanity 插件会在 Sanity Studio 中添加 Translate 操作，并默认将每条译文导入为草稿，供你审校后发布。
- [如何在 Storyblok 中翻译内容？](https://generaltranslation.com/zh/kb/translate-storyblok-content.mdx): 在 Storyblok 中，先将目标语言添加到空间，再为每个可翻译字段按语言分别设置值。General Translation 的 Storyblok 集成可在仪表板中通过“同步并应用”填充这些值，并生成草稿，供你在 Storyblok 中审阅并发布。
- [如何让网站支持多语言？](https://generaltranslation.com/zh/kb/make-website-multilingual.mdx): 先确定译文放在哪里：代理、CMS 插件、建站工具，还是你自己的代码；然后按照 Google 的建议，为每种语言分配独立的 URL。完整翻译页面以及标题和元描述，用 hreflang 关联各语言版本，并提供语言切换器，而不是自动重定向访问者。
- [如何审阅和编辑译文？](https://generaltranslation.com/zh/kb/review-translations.mdx): 将每条译文与其源内容及其他区域设置的版本进行对比，修正读着别扭的地方。借助 General Translation，你可以在仪表板的翻译页面中编辑译文，并通过标签和评论跟踪审阅进度；其 AI 智能体 Locadex 下一次运行翻译时，会将这些修改纳入拉取请求。
- [General Translation 与 Lingo.dev：该选哪一个？](https://generaltranslation.com/zh/kb/general-translation-vs-lingo-dev.mdx): Lingo.dev 以可配置的翻译引擎为核心，并提供 CLI、React 和 GitHub 工具来调用这些引擎。General Translation 是一个本地化平台，提供库、代码上下文、共享术语、所有方案均可用的仪表板审校，以及还能为代码完成国际化改造的 Locadex。如果你需要按语言对控制模型，请选择 Lingo.dev。

## Previous and next questions

- Previous question: [如何在 AI 翻译中保持术语一致？](https://generaltranslation.com/zh/kb/ai-translation-glossary.mdx)
- Next question: [如何翻译 Flask 或 FastAPI 应用？](https://generaltranslation.com/zh/kb/translate-python-app.mdx)

## Sitemap

See the [Knowledge Base sitemap](https://generaltranslation.com/zh/kb/sitemap.md) for every article.