概述

withGTConfig 是配置 gt-next 库的主要方式。 它会直接对一个 NextConfig 对象进行封装。

import { withGTConfig } from 'gt-next/config';

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

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

使用 withGTConfig 可以：

• 配置支持的语言和默认 locale（即 fallback 语言）。
• 设置 API Keys 和项目 ID 以访问 GT 服务。
• 配置加载行为。
• 配置 timeout（超时）设置。
• 设置自定义端点。
• 自定义翻译行为、缓存与请求合并。
• 通过 SWC 插件配置构建时校验。

参考

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

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

参见 gt.config.json 参考文档，了解该配置文件的更多信息。

必填 Props

推荐的 Props

高级 Props

返回值

一个函数 (NextConfig) => NextConfig，用于将指定的 GT 设置应用到 Next.js 配置对象以进行增强。

异常

在缺少 projectId 且使用默认 URL，或需要 API key 但未提供时，将抛出 Error。

渲染设置

渲染设置用于控制翻译加载时的表现。 这仅适用于运行时进行的翻译。 如果翻译已被缓存，响应足够快，无需任何加载处理。

渲染方式

• skeleton：渲染一个片段（fragment）。
• replace：等待期间渲染默认语言的内容。
• default：对于语言相同的 locale（如 en-US 和 en-GB），行为与 replace 相同；对于语言不同的 locale（如 en-US 和 fr），行为与 skeleton 相同。

超时

超时仅适用于运行时翻译，即由于未缓存而需要按需执行的翻译。

默认超时为 8 秒。 此设计是为了方便 Vercel 用户，其免费方案中无服务器函数的默认超时为 10 秒。

示例

渲染设置

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

{
  "defaultLocale": "en-US",
  "locales": ["en-US", "es", "fr"],
}

import { withGTConfig } from 'gt-next/config';

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

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

构建时校验

此示例将 SWC 插件配置为把动态内容违规视为构建错误而非警告。

import { withGTConfig } from 'gt-next/config';

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

export default withGTConfig(nextConfig, {
  // 动态 JSX 违规时构建失败
  dynamicJsxCheckLogLevel: 'error',
  // 动态字符串违规时发出警告  
  dynamicStringCheckLogLevel: 'warn',
});

注意事项

• withGTConfig 会将 GT 翻译功能集成到你的 Next.js 应用中，必须在根配置文件中使用。
• apiKey 和 projectId 等参数可以直接在配置中设置，或通过环境变量提供。
• renderSettings 和 _batchInterval 等高级参数可对翻译行为和性能进行精细化控制。

下一步

• 将翻译集成到你的 CD 流程。