Configuration

Set environment variables

Set two environment variables:

GT_API_KEY=""
GT_PROJECT_ID=""

An API key (GT_API_KEY) is a 36-character string beginning gtx- which is used to authenticate your app with our cloud translation service. Create one on the API Keys page.

Your Project ID can also be found on the Dashboard:

These environment variables will be used:

• To access the translation CDN (GT_PROJECT_ID)
• For on-demand translation (GT_API_KEY)
• In the gt-update CLI tool so you can push dictionaries from the command line(GT_API_KEY)

Install the plugin

import { initGT } from 'gt-next/config'

In the root directory of your project, there should be a file called next.config.js (or .ts, .mjs, .cjs).

my-app/
├── src/
│   ├── app/
│   │    └── page.js
│   └── components/
│       ├── Header.js
│       └── Footer.js
├── public/
│   └── favicon.ico
├── next.config.js
├── .gitignore
├── package.json
└── README.md

Edit your next.config.js file to run the initGT() function. This is optional, but it lets you add useful configuration options like a non-English default language (defaultLocale) or a list of approved languages to translate into (locales).

// next.config.mjs
 
import { initGT } from 'gt-next/config'
 
const withGT = initGT()
 
export default withGT({});

Add parameters to initGT() to configure gt-next:

// next.config.mjs
 
import { initGT } from 'gt-next/config'
 
const withGT = initGT({
    defaultLocale: "en-US", // the default language of your app, usually "en" or "en-US"
    locales: ["en-US", "es", "fr"] // the languages your app is available in
    description: "A personal website for John Smith" // a natural language description of your site used to aid in translation
});
 
export default withGT({});

Parameters of initGT()

Recommended Parameters

locales

• Type: string[]
• Description: A list of supported locales for the application. If not provided, it defaults to the first locale or the default locale set.

defaultLocale

• Type: string
• Default: locales[0] || 'en'
• Description: Default locale for the application. This will be the fallback language when none is specified.

description

• Type: string
• Description: A natural language description of the site, used to aid translation.

// next.config.mjs
 
import { initGT } from 'gt-next/config'
 
const withGT = initGT({
    defaultLocale: "en-US",
    locales: ["en-US", "es", "fr"] // English, Spanish, French,
    description: "A personal website for John Smith"
});
 
export default withGT({});

Advanced Parameters

projectID

• Type: string
• Description: Project ID, which can be included here or as an environment variable.

preferredModelProvider

• Type: "anthropic" | "openai"
• Description: Your first choice AI model provider. Currently only Anthropic or OpenAI are enabled. Leave this blank and we'll figure out the best provider on a translation-by-translation basis. In periods of high usage or when a provider is disabled, we can't guarantee that your preferred provider will be used.

// one app
const withGT = initGT({
    defaultLocale: "en-US",
    locales: ["en-US", "de"]
    description: "A B2B SaaS dashboard"
});

// another app
const withGT = initGT({
    defaultLocale: "en",
    locales: ["en", "fr", "es", "de"]
    description: "A B2B SaaS marketing site"
});

baseURL

• Type: string
• Default: https://prod.gtx.dev
• Description: Base URL for the GT API. To disable automatic translation, set this to an empty string.

cacheURL

• Type: string
• Default: https://cache.gtx.dev
• Description: URL where cached translations are stored. Can be customized to point to a custom cache server.

renderSettings

• Type: { fallbackToPrevious: boolean, method: "skeleton" | "replace" | "hang" | "subtle", timeout: number | null }
• Default: { "fallbackToPrevious": true, "method": "skeleton", "timeout": null }
• Description: An object specifying how on-demand translations should be rendered.

_maxConcurrentRequests

• Type: number
• Default: 2
• Description: Maximum number of concurrent translation requests allowed to the GT API.

_batchInterval

• Type: number
• Default: 1000
• Description: Interval in milliseconds between batched translation requests. Helps control the rate at which requests are sent.

i18n

• Type: string
• Description: Optional configuration filepath for custom getLocale() functions. If provided as a string, it will be resolved as a path. Otherwise, defaults are used (recommended).

// src/i18n.js
// A file which defines a custom getLocale() function
 
import { cookies } from "next/headers";
 
export async function getLocale() {
    const cookieStore = await cookies();
    return cookieStore.get('myCustomLocaleCookie') || 'en';
}

dictionary

• Type: string
• Description: Optional configuration filepath 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.