# General Translation Integrations: 快速入门
URL: https://generaltranslation.com/zh/docs/integrations/payload/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 安装 gt-payload，将插件添加到 Payload CMS，并翻译你的第一个本地化文档。

`gt-payload` 插件为 Payload CMS 的集合 (collections) 和全局配置 (globals) 添加翻译控制项，可将本地化字段翻译为 Payload 配置中指定的各个区域设置。

## 开始之前 [#before-start]

你需要准备：

* Payload CMS 3.90.0 或更高版本，并已配置 `localization`
* Next.js 15.2.9 或更高版本
* React 19.0.1 或更高版本
* 一个 General Translation [项目 ID](/docs/platform/dashboard/get-started)，以及一个具有 **All** 权限的[项目 API Key](/docs/platform/dashboard/reference/api-keys#create-project-keys)
* 至少一个设置了 `localized: true` 的字段

## 快速入门 [#quickstart]

### 1. 安装 `gt-payload`

<Tabs items={['npm', 'yarn', 'bun', 'pnpm']}>
  <Tab value="npm">
    ```bash
    npm install gt-payload
    ```
  </Tab>

  <Tab value="yarn">
    ```bash
    yarn add gt-payload
    ```
  </Tab>

  <Tab value="bun">
    ```bash
    bun add gt-payload
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash
    pnpm add gt-payload
    ```
  </Tab>
</Tabs>

### 2. 配置本地化

在 Payload 配置中设置源区域设置和目标区域设置，然后将每个需要翻译的字段标记为 localized。

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

export default buildConfig({
  // ... 现有配置
  localization: {
    locales: ['en', 'es', 'fr'],
    defaultLocale: 'en',
  },
  collections: [
    {
      slug: 'pages',
      fields: [
        {
          name: 'title',
          type: 'text',
          localized: true,
        },
      ],
    },
  ],
});
```

如果配置中未启用 Payload 本地化，该插件不会对其做任何更改。

### 3. 添加插件

将 [`gtPlugin`](/docs/integrations/payload/reference/plugin-configuration) 添加到 `plugins` 数组中。

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

### 4. 设置凭据

在运行 Payload 的服务器上设置项目 ID 和项目 API Key：

```bash title=".env"
GT_PROJECT_ID=your-project-id
GT_API_KEY=your-project-api-key
```

请勿将 `GT_API_KEY` 暴露给客户端代码，也不要将其提交到版本控制系统中。

### 5. 更新 Payload

重新生成导入映射 (import map) ，以便管理面板能够加载插件组件：

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

该插件会添加用于存储翻译运行和锁的集合。如果使用 PostgreSQL 或 SQLite，请像处理其他 Payload schema 变更一样，创建并应用迁移：

```bash
npx payload migrate:create
npx payload migrate
```

### 6. 翻译文档

1. 启动 Payload 并打开管理面板。
2. 打开一个包含本地化字段的文档或全局配置 (global) 。
3. 保存所有待保存的修改。
4. 选择 **Translate**。
5. 选择一个或多个目标区域设置，然后选择 **Translate into …**。

插件会将每个翻译结果写入对应的 Payload 区域设置。如果启用了草稿，插件会将结果保存为草稿，且绝不会发布已翻译内容。

## Next steps

- /docs/integrations/payload/guides/translating-content
- /docs/integrations/payload/guides/managing-translations

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.