# gt: General Translation CLI tool: MDX 和 Markdown
URL: https://generaltranslation.com/zh/docs/cli/reference/formats/mdx-md-files.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: 使用 General Translation CLI 翻译 MDX 和 Markdown 文件。MDX 和 Markdown 文件格式的 API 参考。

CLI 可翻译 MDX (`mdx`) 和 Markdown (`md`) 文件。源文件中的所有语法和格式都会在翻译后的文件中保留。

## 概览 [#overview]

| 主题                       | 说明                       |
| ------------------------ | ------------------------ |
| [配置](#config)            | 选择源文件和翻译输出路径。            |
| [自定义标题 ID](#heading-ids) | 保留显式的标题锚点。               |
| [静态数据导出](#data-exports)  | 在符合条件的导出中复用未更改的字符串。      |
| [翻译后的文件名](#transform)    | 使用 `transform` 重映射输出文件名。 |
| [链接和资源](#localize)       | 本地化 URL、导入和相对资源。         |

## 配置 [#config]

在 `files` 下添加一个 `mdx` 或 `md` 条目，并在 `include` 数组中填入 glob 模式。使用 `[locale]` 占位符，这样 CLI 就能找到源文件，并将译文保存到正确的路径。

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

这会翻译 `content/docs/en` 下的所有 MDX 文件，并将结果保存到 `content/docs/ja`。对于 Markdown 文件，请改用 `md` 键。有关所有文件键，请参阅[配置参考](/docs/cli/reference/config#files)。

## 自定义标题 ID [#heading-ids]

Mintlify 风格的 `{#id}` 后缀在翻译后仍会保留在对应的标题上：

```markdown
## 配置客户端 {#configure-client}
```

显式标题 ID 需要 `gt` 2.17.3 或更高版本。

当 `experimentalAddHeaderAnchorIds` 设置为 `'mintlify'` 时，CLI 会在每个翻译后的标题上写入 Mintlify 原生的 `{#id}` 语法，并复用源标题的 ID。嵌套在 JSX 中的标题在必要时会被移至左边缘，因为 Mintlify 只能识别前导空格不超过三个的标题上的该后缀。此模式需要 `gt` 2.20.4 或更高版本。

## 更新静态数据导出 [#data-exports]

当更新后的 MDX 文件包含静态数据导出时，General Translation 会复用先前翻译中匹配的字符串，并且只翻译新增或发生变更的字符串。当区块中的每个导出变量仅包含静态字符串、数字、bigint、布尔值或 `null` 字面量、数组和普通对象时，可以进行复用。支持 TypeScript 断言包装器。

包含展开运算符、标识符、函数调用、模板字面量、JSX 或计算对象键的导出则会走标准翻译流程。运行 [`gt translate --force`](/docs/cli/reference/commands/translate) 或应用词汇表翻译也会跳过这种增量复用。

## 重命名翻译后的文件 [#transform]

`transform` 键用于重新映射输出文件名。在上面的示例中，`*.[locale].mdx` 会将翻译后的文件扩展名改为 `.ja.mdx`。当你的文档框架要求将区域设置放在文件名中，而不是放在目录路径中时，请使用此项。

## 本地化链接和资源 [#localize]

有几个实验性的 [`gt translate`](/docs/cli/reference/commands/translate#experimental) 标志专门用于 `md` 和 `mdx` 输出：

* `--experimental-localize-static-urls` — 本地化翻译后的文件中的 URL。
* `--experimental-localize-static-imports` — 本地化翻译后的文件中的静态导入。
* `--experimental-localize-relative-assets` — 重写翻译后的文件中的相对图片资源 URL。
* `--experimental-hide-default-locale` — 在本地化路径中隐藏默认区域设置。

## Sitemap

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