# gt: General Translation CLI tool: PO / POT
URL: https://generaltranslation.com/zh/docs/cli/formats/po.mdx
---
title: PO / POT
description: 如何使用 General Translation 自动翻译 PO/POT 文件
---

## 概述

`gt` 可用于自动翻译项目中的 [PO (Portable Object)](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html) 和 POT (PO Template) 文件。它们是 [GNU gettext](https://www.gnu.org/software/gettext/) 使用的标准文件格式，而 GNU gettext 是最早且应用最广泛的国际化系统之一。

POT 文件包含从代码中提取的源字符串，PO 文件则包含特定区域设置的译文。

我们将按以下 4 个步骤进行：

<Steps>
  <Step>
    添加环境变量
  </Step>

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

  <Step>
    创建一个 `gt.config.json` 文件
  </Step>

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

***

## 第 1 步：添加环境变量

将生产环境 API 密钥和项目 ID 添加到环境变量中。
这是使用 `gt` 工具的前提。
你可以在 [General Translation 仪表板](https://generaltranslation.com/dashboard) 获取这些信息。

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

## 第 2 步：安装 `gt`

在项目中安装 `gt` 工具。

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

## 第 3 步：创建 `gt.config.json` 文件

在项目的 root 目录中创建一个 `gt.config.json` 文件。

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

你可以按需自定义 `gt.config.json` 文件。更多信息请参阅[配置](/docs/cli/reference/config)文档。

请更新 `pot` 文件格式，使 `include` 路径与项目结构一致。

`transformationFormat` 选项会告知 `gt` 将翻译后的文件输出为 `.po` 文件，而不是 `.pot` 文件。这是标准工作流：POT 文件是源模板，PO 文件则包含每个区域设置的实际译文。

<Callout type="info">
  **注意：**译文将保留原始 PO/POT 字符串语法。
</Callout>

## 第 4 步：将 `gt translate` 命令添加到你的 build 流程

在执行 build 命令之前，将 `gt translate` 命令添加到你的 build 或 CI 流程中，以便自动将译文添加到你的项目中。

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

这会为你的所有区域设置生成译文，并将其保存到项目中。
如果你想把这些文件 commit 到仓库，也可以改为在 commit 之前运行此命令。

这样就完成了！现在，每当项目发生变化时，你的项目都会自动更新所有翻译 PO/POT 文件。

***

## 说明

* 你可以使用 [`gt translate`](/docs/cli/translate#translate) 命令，自动将译文添加到项目中。
* 如果你想提交翻译文件，应在提交前先运行 `gt translate` 命令。
* 要配置译文的输出路径，请参阅[配置](/docs/cli/reference/config)文档。
* 在 `gt.config.json` 中，`pot` 和 `POT` 都可以作为配置键使用。

## 后续步骤

* 有关 CLI 的详细用法，请参阅 [translate 命令](/docs/cli/translate)。
* 如需了解针对每个键的翻译说明，请参阅 [键级元数据](/docs/cli/reference/keyed-metadata)。