initGT()

Overview

initGT() allows you to customize the behavior of the gt-next library. It is not required to use initGT() to enable translation functionality, but it is recommended to configure the library to suit your needs.

Use initGT() to:

• Configure supported languages and default locale (a.k.a fallback language).
• Set API keys and project IDs for accessing GT services.
• Set loading behavior.
• Configure timeout settings.
• Set up custom endpoints.
• Customize translation behavior, caching, and request batching.

Reference

Recommended Props

Advanced Props

Returns

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

Exceptions

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

Render settings

Render settings controls the behavior of translations while they are loading. This only applies to translations that are happening at runtime. If the translation is cached, response time is too low to justify loading behavior.

Render methods

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

Timeout

Timeouts only apply to runtime translations, or translations that need to be performed on demand as they have not been cached.

Timeouts are set to 8 seconds by default. This design decision is to facilitate vercel users who have a default 10-second timeout for serverless functions on the free plan.

Examples

Supported locales

This example configures gt-next with English (en-US) as the default locale. It exclusively supports translations in Spanish (es) and French (fr), and provides a description for context-aware translation.

The site will fallback to the best suited language if none of the locales match. It will look for matching languages (i.e., en-US and en-GB), as well as the other preferred languages the user has set in their browser. If all else fails, then it will fallback to the default language.

import { initGT } from 'gt-next/config';
 
const withGT = initGT({
    defaultLocale: 'en-US',
    locales: ['en-US', 'es', 'fr'],
    description: 'A personal blog about technology and travel',
});
 
export default withGT({});

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.

import { initGT } from 'gt-next/config';
 
// locales field is left empty, so this configuration supports all 100+ languages
const withGT = initGT({
    defaultLocale: 'en-US',
    renderSettings: {
        method: 'skeleton',
        timeout: 10000,
    },
});
 
export default withGT({});

Notes

• initGT() 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 behavior and performance.

Next Steps

• Read more about i18n configuration in our reference guide.
• Use the CLI tool to pre-translate your app for better performance.