# General Translation Integrations: Quickstart
URL: https://generaltranslation.com/en-US/docs/integrations/payload/quickstart.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Install gt-payload, add the plugin to Payload CMS, and translate your first localized document.

The `gt-payload` plugin adds translation controls to Payload CMS collections and globals. It translates localized fields into the locales in your Payload config.

## Before you start [#before-start]

You need:

- Payload CMS 3.90.0 or later with `localization` configured
- Next.js 15.2.9 or later
- React 19.0.1 or later
- A General Translation [project ID](/docs/platform/dashboard/get-started) and [project API key](/docs/platform/dashboard/reference/api-keys#create-project-keys) with **All** permissions
- At least one field with `localized: true`

## Quickstart [#quickstart]

### 1. Install `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. Configure localization

Configure the source and target locales in your Payload config, then mark each field you want to translate as localized.

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

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

The plugin does not change a config without Payload localization.

### 3. Add the plugin

Add [`gtPlugin`](/docs/integrations/payload/reference/plugin-configuration) to the `plugins` array.

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

export default buildConfig({
  // ... your existing config
  localization: {
    locales: ['en', 'es', 'fr'],
    defaultLocale: 'en',
  },
  plugins: [gtPlugin()],
});
```

### 4. Set credentials

Set the project ID and project API key on the server that runs Payload:

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

Do not expose `GT_API_KEY` to client code or commit it to source control.

### 5. Update Payload

Regenerate the import map so the admin panel can load the plugin components:

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

The plugin adds collections for translation runs and locks. For PostgreSQL or SQLite, create and apply a migration as you would for any Payload schema change:

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

### 6. Translate a document

1. Start Payload and open the admin panel.
2. Open a document or global with localized fields.
3. Save any pending edits.
4. Choose **Translate**.
5. Select one or more target locales, then choose **Translate into …**.

The plugin writes each result into the matching Payload locale. It saves a draft when drafts are enabled and never publishes translated content.

## 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.