# gt-next: General Translation Next.js SDK: withGTConfig
URL: https://generaltranslation.com/en-GB/docs/next/api/config/with-gt-config.mdx
---
title: withGTConfig
description: API reference for the withGTConfig(), formerly initGT()
---

## Overview

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

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

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

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

<Callout>
  **Legacy**

  `initGT` is the legacy way to configure the `gt-next` library. It returns a callback function, which is then called on the `NextConfig` object.
  The props for both functions are the same, except that `withGTProps` also requires `NextConfig` to be passed in.
</Callout>

Use `withGTConfig` to:

* Configure supported languages and the default locale (also known as the 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 through the SWC plugin.

<Callout>
  `withGTConfig` must be used in your `next.config.js` file to enable translation functionality.
</Callout>


## 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](/docs/next/api/config/gt-config-json) reference for more information about the configuration file.

<Callout>
  The CLI tool will only read the configuration from the `gt.config.json` file, so
  we recommend using the `gt.config.json` file as the source of truth for your app.

  Additional configuration options not in the `gt.config.json` file can be passed directly to `withGTConfig` as props.
</Callout>

### Required props

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

### Recommended props

<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` | Default locale for the application. English will be the fallback language when none is specified.                                                                                                                                       |
| `locales`       | An exclusive list of supported locales for the application. If an unsupported request is received, it will reroute to the browser&#39;s next preferred language in the list. It will fall back to `defaultLocale` if no match is found. |
| `description`   | A natural language description of the site, used to aid translation.                                                                                                                                                                    |

### Advanced props

<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,
      },

  }}
/>

| Prop                     | Description                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `projectId`              | Project ID. You can include it here or as an environment variable.                                                                                                                                                                                                                                                                                                    |
| `apiKey`                 | Although not recommended, you can include an API key here. It can also be included as an environment variable.                                                                                                                                                                                                                                                        |
| `devApiKey`              | Although not recommended, you can include a development API key here. It can also be included as an environment variable.                                                                                                                                                                                                                                             |
| `preferredModelProvider` | Your preferred AI model provider. Currently, only [Anthropic](https://anthropic.com) and [OpenAI](https://openai.com) are supported. Leave this blank and we&#39;ll determine the best provider on a translation-by-translation basis. During periods of high usage or when a provider is disabled, we can&#39;t guarantee that your preferred provider will be used. |
| `runtimeUrl`             | Base URL for the GT API. To disable automatic translation, set this to an empty string.                                                                                                                                                                                                                                                                               |
| `cacheUrl`               | URL where cached translations are stored. Can be customised to point to a custom cache server.                                                                                                                                                                                                                                                                        |
| `cacheExpiryTime`        | Time in milliseconds before locally cached translations expire.                                                                                                                                                                                                                                                                                                       |
| `renderSettings`         | An object specifying loading behaviour for runtime translations.                                                                                                                                                                                                                                                                                                      |
| `maxConcurrentRequests`  | Maximum number of concurrent translation requests allowed to the GT API.                                                                                                                                                                                                                                                                                              |
| `maxBatchSize`           | Maximum number of translations to batch together before sending a request.                                                                                                                                                                                                                                                                                            |
| `batchInterval`          | Interval in milliseconds between batched translation requests. Helps control the rate at which requests are sent.                                                                                                                                                                                                                                                     |
| `dictionary`             | Optional configuration file path for the dictionary. Similar to `i18n`, it accepts a string to specify a custom path. Dictionaries called `dictionary.js` (or `.jsx`, `.ts`, `.tsx` etc.) and placed at the root or in the `src` folder are supported by default.                                                                                                     |

### Returns

A `NextConfig` object enhanced 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 and missing.

***

## Render settings

Render settings control the behaviour of translations while they are loading.
This only applies to translations that happen at runtime.
If the translation is cached, response times are too low to justify loading behaviour.

<TypeTable
  type={{
method: {
    description: 'The method used to render the page.',
    type: '"skeleton" | "replace" | "default"',
    optional: false,
    default: "default"
},
timeout: {
    description: 'The time in milliseconds before the method times out.',
    type: 'number',
    optional: true,
    default: 8000,
},
}}
/>

| Prop      | Description                                                                           |
| --------- | ------------------------------------------------------------------------------------- |
| `method`  | The method used to render the page. Options are `skeleton`, `replace`, and `default`. |
| `timeout` | The time in milliseconds before the method times out. The default is 8000 ms.         |

### 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 only apply to runtime translations, or translations that need to be performed on demand because they have not been cached.

Timeouts are set to 8 seconds by default.
This design decision is intended to help 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 waiting for translations to load.
If the translation takes longer than 8 seconds, the method will time out and render the default-language content.

```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 = {
  // Your other Next.js configurations
};

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

***

## Notes

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

## Next steps

* Add [translation to your CD process](/docs/next/tutorials/quickdeploy).