# gt: General Translation CLI tool: PO / POT
URL: https://generaltranslation.com/en-GB/docs/cli/formats/po.mdx
---
title: PO / POT
description: How to automatically translate PO/POT files with General Translation
---

## Overview

`gt` can be used to automatically translate your project's [PO (Portable Object)](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html) and POT (PO Template) files. These are the standard file formats used by [GNU gettext](https://www.gnu.org/software/gettext/), one of the oldest and most widely adopted internationalisation systems.

POT files contain the source strings extracted from your code, and PO files contain the translations for a specific locale.

We will follow these 4 steps:

<Steps>
  <Step>
    Add your environment variables
  </Step>

  <Step>
    Install [`gt`](/docs/cli)
  </Step>

  <Step>
    Create a `gt.config.json` file
  </Step>

  <Step>
    Run [`gt translate`](/docs/cli/translate#translate)
  </Step>
</Steps>

***

## Step 1: Add your environment variables

Add your production API key and project ID to your environment variables.
This is necessary to use the `gt` tool.
You can get these from the [General Translation dashboard](https://generaltranslation.com/dashboard).

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

## Step 2: Install `gt`

Install the `gt` tool in your project.

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

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

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

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

## Step 3: Create a `gt.config.json` file

Create a `gt.config.json` file at the root of your project.

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["zh", "es", "ja"],
  "files": {
    "pot": {
      "include": ["locales/[locale]/*.pot"],
      "transformationFormat": "PO"
    }
  }
}
```

Feel free to customise the `gt.config.json` file to suit your needs. See the [configuration](/docs/cli/reference/config) docs for more information.

Update the `pot` file format so that the `include` path matches your project structure.

The `transformationFormat` option tells `gt` to output translated files as `.po` files instead of `.pot` files. This is the standard workflow: POT files are source templates, and PO files contain the actual translations for each locale.

<Callout type="info">
  **Note:** Translations will preserve the original PO/POT string syntax.
</Callout>

## Step 4: Add the `gt translate` command to your build process

Add the `gt translate` command to your build or CI process before the build command to automatically add translations to your project.

```json title="package.json"
{
  "scripts": {
    "translate": "npx gt translate",
    "build": "npm run translate && <your build command>"
  }
}
```

This will generate translations for all your locales and save them to your project.
If you want to commit these files to your repo, you can run this command instead before committing.

You&#39;re done! Your project will now automatically update all your translation PO/POT files whenever your project changes.

***

## Notes

* You can automatically add translations to your project with the [`gt translate`](/docs/cli/translate#translate) command.
* If you want to commit your translation files, you should run the `gt translate` command before committing.
* To configure the output path for your translations, see the [configuration](/docs/cli/reference/config) docs.
* Both `pot` and `POT` are accepted as configuration keys in `gt.config.json`.

## Next steps

* See the [translate command](/docs/cli/translate) for CLI usage details.
* Learn about [keyed metadata](/docs/cli/reference/keyed-metadata) for per-key translation instructions.