# gt: General Translation CLI tool: Markdown
URL: https://generaltranslation.com/zh/docs/cli/formats/mdx.mdx
---
title: Markdown
description: 如何使用 General Translation 为项目中的 Markdown 文件设置自动翻译
---

## 概览

`gt` 可用于自动翻译项目中的 Markdown (MD 和 MDX) 文件。

<Callout type="info">
  原始文件中的所有语法和格式都会在译文文件中保留。
</Callout>

我们将按以下 4 个步骤操作：

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

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

  <Step>
    配置项目的 [`gt.config.json`](/docs/cli/reference/config) 文件
  </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` 文件

在项目根目录下创建一个 `gt.config.json` 文件，内容如下：

```json title="gt.config.json"
{
  "defaultLocale": "en",
  "locales": ["es", "fr"],
  "files": {
    "mdx": {
      "include": ["docs/[locale]/**/*.mdx"]
    }
  }
}
```

<Callout type="info">
  如果你的文件是 MD 文件，可以使用 `md` 键，而不是 `mdx`。
</Callout>

将 `defaultLocale` 和 `locales` 改为与你的项目 locales 一致。

`include` 键中的字符串数组应为一个 glob 模式，用于匹配你的所有 MDX 文件。

它应使用 `[locale]` 占位符来匹配文件的 locales。

如需了解 `gt.config.json` 文件的更多信息，请参阅[配置](/docs/cli/reference/config)文档。


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

在执行构建命令之前，将 `gt translate` 命令加入你的构建或 CI 流程中，以自动为你的项目添加翻译。

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

这会为你的所有 locales 生成翻译，并将其保存到项目中。
如果你想把这些文件提交到代码仓库，也可以改为在提交前运行此命令。

完成了！现在，每当项目发生更改时，项目都会自动更新所有 Markdown 文件。

***


## 说明

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

## 后续步骤

* 有关 CLI 用法的详细信息，请参阅 [translate 命令](/docs/cli/translate)。