Overview

Introduction

The General Translation Next.js SDK is an open-source internationalization (i18n) library for Next.js.

It offers a set of tools to help you internationalize your Next.js application in a easy and maintainable way, with feature parity to other popular i18n libraries. It is built on top of the React SDK, and offers additional features specific to Next.js.

The Next.js SDK can be used without the General Translation platform, and will act very similarly to other i18n libraries.

However, it also integrates with our platform, offering additional features such as:

• Translation Hot Reloading in Development
• Automatic AI translations
• Syncing translations with the General Translation platform
• Native integration with our translation CDN
• On-demand translation of React components in production (on the server side)

Concepts

There are 5 main concepts to understand about the SDK.

Initialization with withGTConfig

The withGTConfig function is a function that is used to initialize the SDK in a Next.js application.

It should be placed in your next.config.[js|ts] file, and is used to configure the SDK.

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

const nextConfig = {
  // Your next.config.ts options
};

export default withGTConfig(nextConfig, {
  // Your GT configuration
});

See the withGTConfig API Reference for more information.

The <GTProvider> component

import { GTProvider } from 'gt-next';

The <GTProvider> component is the main component that you need to add to your application.

It is used to provide the rest of your application with context.

This context includes the current language and the relevant translations for that language.

The provider is only required if you are using any client-side features. If you are only using server-side features, the provider is not required, but can still be included.

Important Considerations

• The provider should wrap your entire application.
• Ideally, it should be placed as high in the tree as possible, such as in your root layout.

See the GTProvider page for more information.

The <T> component

The <T> component is the recommended way to translate content in your application.

It is a React component that can be used to wrap any JSX element, and will automatically render the content of the element into a supported language.

Examples

<T>
  <div>Hello, world!</div>
</T>

<T>
  <div>
    <h1> Here is an image </h1>
    <img src="https://example.com/image.png" alt="Example" />
  </div>
</T>

<T>
  Formatting can be done easily with the `<T>` component.
  <Num>{1000}</Num>
  <DateTime>{new Date()}</DateTime>
  <Currency>{1000}</Currency>
</T>

See the components guide to learn about the different ways to use the <T> component.

See the T API Reference for the API of the <T> component.

The useGT hook

The useGT hook is a React hook that can be used similarly to the <T> component, with some trade-offs.

The hook returns a function that can be used to translate strings.

const translate = useGT();

translate('Hello, world!');

Compared to the <T> component, the useGT hook allows for more flexibility in your codebase.

For example, if you have a complex data structure with nested strings, a <T> component would be more difficult to use.

const t = useGT();
const data = {
  title: t('Hello, world!'),
  description: t('This is a description'),
};

See the strings guide to learn more about the useGT hook.

See the useGT API Reference for more information.

The useDict hook

The useDict hook is a React hook that returns a function that can be used to retrieve translations for a given key.

const dictionary = {
  hello: {
    world: 'Hello, world!',
  },
};

const translate = useDict();
translate('hello.world');

This behavior is similar to other translation libraries, such as react-i18next and next-intl.

See the dictionaries guide to learn more about the useDict hook.

See the useDict API Reference for more information.

Next Steps

• Learn about how to setup your Next.js project with the SDK: Quickstart
• Learn about how to translate strings with the useGT hook: Translating Strings
• Learn about how to translate JSX content with the <T> component: Translating JSX