Overview

withGTConfig is the primary way to configure the gt-next library. It directly wraps a NextConfig object.

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

const nextConfig = {
    // your existing next.config.js
}

export default withGTConfig(nextConfig, {
  // Additional configuration options
});

Use withGTConfig to:

• Configure supported languages and the default locale (a.k.a. fallback language).
• Set API keys and project IDs for accessing GT services.
• Set loading behaviour.
• Configure timeout settings.
• Set up custom endpoints.
• Customise translation behaviour, caching, and request batching.
• Configure build-time validation via the SWC plugin.

Reference

By default, withGTConfig will look for a gt.config.json file in the same directory as your next.config.js file.

This JSON file will be loaded and merged with the configuration passed to withGTConfig.

See the gt.config.json reference for more information on the configuration file.

Required props

Recommended Props

Advanced Props

Returns

A function (NextConfig) => NextConfig that augments the Next.js configuration object with the specified GT settings.

Exceptions

Throws an Error if the projectId is missing and default URLs are used, or if the API key is required but missing.

Render settings

Render settings control the behaviour of translations while they load. This only applies to translations that occur at runtime. If the translation is cached, the response time is too low to warrant loading behaviour.

Render methods

• skeleton: Renders a fragment.
• replace: Renders content in the default language while waiting.
• default: For locales with the same language (i.e. en-US and en-GB), behaves like replace. For locales with different languages (i.e. en-US and fr), behaves like skeleton.

Timeout

Timeouts apply only to runtime translations, i.e. translations performed on demand because they haven’t been cached.

By default, timeouts are set to 8 seconds. This design choice is to accommodate Vercel users, who have a default 10‑second timeout for serverless functions on the free plan.

Examples

Render settings

This example configures gt-next to render a skeleton while translations are loading. If loading takes longer than 8 seconds, the method times out and renders the default-language content.

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

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

const nextConfig = {
  // Your other next.js configurations
};

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

Build-time validation

This example configures the SWC plugin to treat dynamic content violations as build errors rather than warnings.

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

const nextConfig = {
  // Your other Next.js configurations
};

export default withGTConfig(nextConfig, {
  // Fail builds on dynamic JSX violations
  dynamicJsxCheckLogLevel: 'error',
  // Warn on dynamic string violations  
  dynamicStringCheckLogLevel: 'warn',
});

Notes

• withGTConfig integrates GT translation functionality into your Next.js app and must be used in the root configuration file.
• Parameters such as apiKey and projectId can be set directly in the configuration or as environment variables.
• Advanced parameters such as renderSettings and _batchInterval allow fine-grained control over translation behaviour and performance.

Next steps

• Add translation to your CD process.