withGTConfig()

概述

withGTConfig() 是配置 gt-next 库的主要方式。 它直接包装一个 NextConfig 对象。

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

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

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

使用 withGTConfig() 可以：

• 配置支持的语言和默认语言环境（即回退语言）。
• 设置用于访问 GT 服务的 API 密钥和项目 ID。
• 设置加载行为。
• 配置超时设置。
• 设置自定义端点。
• 自定义翻译行为、缓存和请求批处理。
• 通过 SWC 插件配置构建时验证。

参考

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

该 JSON 文件将被加载并与传递给 withGTConfig() 的配置进行合并。

有关配置文件的更多信息，请参阅 gt.config.json 参考文档。

必需 Props

推荐 Props

高级 Props

返回值

返回一个 (NextConfig) => NextConfig 函数，用指定的 GT 设置增强 Next.js 配置对象。

异常

当缺少 projectId 且使用默认 URL 时，或当需要但缺少 API 密钥时，会抛出 Error 异常。

渲染设置

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

渲染方法

• skeleton：渲染一个片段。
• replace：在等待时以默认语言渲染内容。
• default：对于相同语言的地区（如 en-US 和 en-GB），行为与 replace 相同。对于不同语言的地区（如 en-US 和 fr），行为与 skeleton 相同。

超时

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

超时时间默认设置为 8 秒。 此设计决策是为了方便 vercel 用户，因为其免费计划下 serverless 函数的默认超时时间为 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 流程中。