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:

Code copy container entitled "projectID"

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

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 initGT(). This function will let you add configuration options like a non-English default language (defaultLocale) or a list of approved languages to translate into (locales). Use the withGT() plugin it returns to configure Webpack to bundle your dictionary.js file into production builds of your app.

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

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

`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.

`projectID`

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

`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.

`dictionaryName`

Type: string
Default: "default"
Description: The user-defined name of the dictionary used for translation. Multiple dictionaries can exist within the same project if they each have different a dictionaryName.

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

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

`_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 function getLocale() {
    const cookieStore = 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.