# gt-next: General Translation Next.js SDK: withGTConfig
URL: https://generaltranslation.com/zh/docs/next/api/config/with-gt-config.mdx
---
title: withGTConfig
description: withGTConfig() 的 API 参考，原名为 initGT()
---

## 概述

`withGTConfig` 是配置 `gt-next` 库的主要方法。
它会直接包裹一个 `NextConfig` 对象。

```js title="next.config.mjs"
import { withGTConfig } from 'gt-next/config';

const nextConfig = {
    // 你现有的 next.config.js
}

export default withGTConfig(nextConfig, {
  // 其他配置选项
});
```

<Callout>
  **旧版**

  `initGT` 是配置 `gt-next` 库的旧方式。它会返回一个回调函数，随后用 `NextConfig` 对象调用该函数。
  两个函数的参数相同，唯一的区别是 `withGTProps` 还需要额外传入 `NextConfig`。
</Callout>

使用 `withGTConfig` 来：

* 配置支持的语言和默认区域设置 (也称为回退语言) 。
* 设置用于访问 GT 服务的 API 密钥和项目 ID。
* 设置加载行为。
* 配置超时设置。
* 设置自定义端点。
* 自定义翻译行为、缓存和请求批处理。
* 通过 SWC 插件配置构建时校验。

<Callout>
  必须在 `next.config.js` 文件中使用 `withGTConfig`，才能启用翻译功能。
</Callout>


## 参考

默认情况下，`withGTConfig` 会在与你的 `next.config.js` 文件相同的目录中查找 `gt.config.json` 文件。

该 JSON 文件会被加载，并与传递给 `withGTConfig` 的配置合并。

有关此配置文件的更多信息，请参阅 [gt.config.json](/docs/next/api/config/gt-config-json) 参考文档。

<Callout>
  CLI 工具只会读取 `gt.config.json` 文件中的配置，因此
  我们建议将 `gt.config.json` 作为应用配置的唯一可信来源。

  `gt.config.json` 文件中未包含的其他配置选项，可以直接作为属性传递给 `withGTConfig`。
</Callout>

### 必填属性

<TypeTable
  type={{
  "nextConfig": {
    type: 'NextConfig',
    optional: false,
  },
}}
/>

### 推荐的 属性

<TypeTable
  type={{
  "defaultLocale?": {
      type: 'string',
      optional: true,
      default: "locales[0] || 'en'"
  },
  "locales?": {
      type: 'string[]',
      optional: true,
      default: 'undefined',
  },
  "description?": {
      type: 'string',
      optional: true,
      default: 'undefined',
  },
}}
/>

| Prop            | Description                                                                 |
| --------------- | --------------------------------------------------------------------------- |
| `defaultLocale` | 应用的默认区域设置。未指定时，将回退为英语。                                                      |
| `locales`       | 应用支持的区域设置专属列表。如果收到不受支持的请求，会重定向到列表中浏览器下一个首选的语言。若找不到匹配项，则回退到 `defaultLocale`。 |
| `description`   | 站点的自然语言描述，用于帮助改进翻译。                                                         |

### 高级属性

<TypeTable
  type={{
      "projectId?": {
              type: 'string',
              optional: true,
      },
      "apiKey?": {
              type: 'string',
              optional: true,
      },
      "devApiKey?": {
              type: 'string',
              optional: true,
      },
      "preferredModelProvider?": {
              type: '"anthropic" | "openai"',
              optional: true,
      },
      "runtimeUrl?": {
              type: 'string',
              optional: true,
      },
      "cacheUrl?": {
              type: 'string',
              optional: true,
      },
      "cacheExpiryTime?": {
          type: 'number',
          optional: true,
          default: 60000,
      },
      "renderSettings?": {
          type: 'RenderSettings',
          optional: true,
      },
      "maxConcurrentRequests?": {
          type: 'number',
          optional: true,
          default: 100,
      },
      "batchInterval?": {
          type: 'number',
          optional: true,
          default: 50,
      },
      "maxBatchSize?": {
          type: 'number',
          optional: true,
          default: 25,
      },
      "dictionary?": {
          type: 'string',
          optional: true,
      },

  }}
/>

| 属性                       | 说明                                                                                                                                                 |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `projectId`              | 项目 ID，可在此处指定，也可通过环境变量提供。                                                                                                                           |
| `apiKey`                 | 虽然不推荐，但也可以在此处提供 API 密钥；也可通过环境变量提供。                                                                                                                 |
| `devApiKey`              | 虽然不推荐，但也可以在此处提供开发环境 API 密钥；也可通过环境变量提供。                                                                                                             |
| `preferredModelProvider` | 你首选的 AI 模型提供商。目前仅支持 [Anthropic](https://anthropic.com) 或 [OpenAI](https://openai.com)。将此项留空后，我们会针对每次翻译自动选择最佳提供商。在使用高峰期或某个提供商不可用时，无法保证一定会使用你首选的提供商。 |
| `runtimeUrl`             | GT API 的基础 URL。要禁用自动翻译，请将其设为空字符串。                                                                                                                  |
| `cacheUrl`               | 缓存翻译的存储 URL。可自定义为指向你自己的缓存服务器。                                                                                                                      |
| `cacheExpiryTime`        | 本地缓存的翻译在过期前保留的时间 (毫秒) 。                                                                                                                            |
| `renderSettings`         | 用于指定运行时翻译加载行为的对象。                                                                                                                                  |
| `maxConcurrentRequests`  | 允许发送到 GT API 的最大并发翻译请求数。                                                                                                                           |
| `maxBatchSize`           | 发送请求前，单个批次可包含的最大翻译数。                                                                                                                               |
| `batchInterval`          | 批量翻译请求之间的间隔时间 (毫秒) 。有助于控制请求发送速率。                                                                                                                   |
| `dictionary`             | `dictionary` 的可选配置文件路径。与 `i18n` 类似，它接受字符串来指定自定义路径。默认支持位于根目录或 `src` 文件夹中的 `dictionary.js` (或 `.jsx`、`.ts`、`.tsx` 等) 字典文件。                           |

### 返回值

一个 `NextConfig` 对象，应用了指定的 GT 设置。

### 异常

如果缺少 `projectId` 且使用的是默认 URL，或需要 API 密钥但未提供，则会抛出 `Error`。

***

## 渲染设置

渲染设置用于控制翻译加载期间的行为。
这仅适用于在运行时进行的翻译。
如果翻译已缓存，响应时间通常很短，无需设置加载行为。

<TypeTable
  type={{
method: {
    description: '用于渲染页面的方法。',
    type: '"skeleton" | "replace" | "default"',
    optional: false,
    default: "default"
},
timeout: {
    description: '该方法超时前的时间（以毫秒为单位）。',
    type: 'number',
    optional: true,
    default: 8000,
},
}}
/>

| Prop      | Description                                       |
| --------- | ------------------------------------------------- |
| `method`  | 用于渲染页面的方法。可选值包括 `skeleton`、`replace` 和 `default`。 |
| `timeout` | 该方法超时前的时间 (以毫秒为单位) 。默认值为 8000 毫秒。                 |

### 渲染方法

* `skeleton`: 渲染一个片段。
* `replace`: 等待期间渲染默认语言的内容。
* `default`: 对于语言相同的区域设置 (如 `en-US` 和 `en-GB`) ，其行为与 `replace` 相同。对于语言不同的区域设置 (如 `en-US` 和 `fr`) ，其行为与 `skeleton` 相同。

### 超时

超时仅适用于运行时翻译，或那些因尚未缓存而需要按需执行的翻译。

默认超时时间为 8 秒。
这样设计是为了照顾 Vercel 用户，因为其免费套餐中的无服务器函数默认超时为 10 秒。

***

## 示例

### 渲染设置

此示例将 `gt-next` 配置为在等待翻译加载时显示骨架屏。
如果翻译加载时间超过 8 秒，该方法会超时，并渲染默认语言的内容。

```json title="gt.config.json"
{
  "defaultLocale": "en-US",
  "locales": ["en-US", "es", "fr"],
}
```

```js title="next.config.mjs" copy
import { withGTConfig } from 'gt-next/config';

const nextConfig = {
  // 你的其他 Next.js 配置
};

export default withGTConfig(nextConfig, {
  renderSettings: {
    method: 'skeleton',
    timeout: 10000,
  },
});
```

***

## 注意事项

* `withGTConfig` 用于将 GT 的翻译功能集成到你的 Next.js 应用中，并且必须在根配置文件中使用。
* `apiKey` 和 `projectId` 等参数既可以直接在配置中设置，也可以通过环境变量设置。
* `renderSettings` 和 `_batchInterval` 等高级参数可让你精细控制翻译行为和性能。

## 后续步骤

* 将[翻译集成到你的 CD 流程](/docs/next/tutorials/quickdeploy)中。