Next.js Quickstart

Overview

This quickstart guide will walk you through how to setup your Next.js application with gt-next.

By the end of this guide, you will have a Next.js app that is ready to start translating content.

In this guide, we will cover the following:

Installation

Configuration

Usage

Testing Your App

Deployment

Prerequisites

A Next.js application using the App Router
Basic knowledge of Next.js and JavaScript

Installation

Install the gt-next and gtx-cli packages:

npm i gt-next
npm i --save-dev gtx-cli

yarn add gt-next
yarn add --dev gtx-cli

bun add gt-next
bun add --dev gtx-cli

pnpm add gt-next
pnpm add --save-dev gtx-cli

Automatic Setup: We have an experimental Setup Wizard that can help you setup your project with gt-next.

Try it out by running npx gtx-cli@latest. You'll still need to manually internationalize strings, but it will help you get started.

See the Setup Wizard reference guide for more information.

Alternatively, if you would like your AI tool like Claude Code, Cursor, or Windsurf to automatically setup your project, you can use our mcp server.

Configuration

`withGTConfig`

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

Place this in your next.config.[js|ts] file.

next.config.ts

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

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

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

See the withGTConfig API Reference for more information.

`GTProvider`

gt-next also exports a GTProvider component. This component is used to provide context to client-side components in your Next.js application.

The GTProvider and withGTConfig work together to provide context to your application.

This context includes:

Managing the user's current locale
The relevant translations for that locale
Context for the useGT hook
Context for the useTranslations hook

First, add the GTProvider component to the root layout of your application. It should be placed as high up in your component tree as possible.

src/layout.tsx

import { GTProvider } from 'gt-next';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GTProvider>
          {children}
        </GTProvider>
      </body>
    </html>
  );
}

If you have multiple root layouts, place the GTProvider in each one.

Next, create a gt.config.json file in the root of your project. This file is used to configure both the gtx-cli tool and the gt-next library.

gt.config.json

{
  "defaultLocale": "en",
  "locales": ["fr", "es"]
}

You should customize the defaultLocale and locales to match your project. See the list of supported locales for more information.

withGTConfig will automatically detect the gt.config.json file in your project, and use it to configure the SDK.

Environment Variables

Set the following environment variables:

GT_API_KEY="" # Your General Translation Developer API key
GT_PROJECT_ID="" # Your General Translation project ID

Make sure your API key variable is only set in your development environment! It should not be set in production.

You can get a free API key and project ID by creating a General Translation account.

After creating an account, navigate to the Development API Keys page to get your Dev API key and project ID.

Alternatively, you can also use the CLI tool command npx gtx-cli auth to generate an API key and project ID for your project, saved to your .env.local file.

Usage

Great! If you've followed the steps above, your Next.js app is now setup to use gt-next.

The next step is to internationalize your content. Here, we'll give a brief overview of the different ways to translate content in your application.

`<T>` Component

The <T> component is the main component for translating JSX content in your application.

To use it, simply wrap the JSX you want to translate in the <T> component.

import { T } from 'gt-next';
<T>
  <div>Your content</div>
</T>

If you have dynamic content, you'll need to use variable components to pass in the dynamic values.

import { T, Var } from 'gt-next';

<T>
  <div>Hello, <Var>{name}</Var>!</div>
</T>

See the Translating JSX guide for more information.

`useGT` Hook

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

import { useGT } from 'gt-next'

const translate = useGT();
translate('Hello, world!');

The useGT hook can be used in both client-side and server-side components. For async components, use the async getGT() function instead.

See the Translating Strings guide for more information.

Utilizing the hot-reload translation functionality will be helpful for internationalizing your application.

To enable this, make sure you have the GT_API_KEY and GT_PROJECT_ID environment variables set in your development environment.

Testing Your App

Congratulations! 🥳 If you've followed the steps above, your app is now multilingual! Let's see it in action.

See Your App in a Different Language

Add the <LocaleSelector> component to your app. This will allow you to select a different language for your app.

Tip: You can also skip this step and just change your language in your browser settings.

Start your Next.js app in development mode.

npm run dev

yarn run dev

bun run dev

pnpm run dev

Open up your app in your preferred browser (usually at http://localhost:3000).

Deployment

Great! If you're satisfied with your translations and the functionality of your app, you can now deploy your application.

The behavior of gt-next in production is slightly different from development. Specifically, no translations will be performed at runtime (with the exception of the <Tx> component & tx function).

This means that you'll need to translate your content before deploying your application, in the build process.

Luckily, the gtx-cli tool has a translate command that can be used to automatically translate your content.

First, you'll need to get a Production API key from the General Translation platform.

Please note that this key is different from your Development API key, and begins with gtx-api-, instead of gtx-dev-.

Read about the difference between Development and Production keys here.

Add this environment variable to your CI/CD pipeline.

GT_PROJECT_ID=<your-project-id>
GT_API_KEY=<your-production-api-key>

Make sure that GT_API_KEY is NOT prefixed with NEXT_PUBLIC_!

If it is, you'll risk exposing your API key to the public.

Run the translate command to translate your content.

npx gtx-cli translate

You can configure the behavior of the translate command with the gt.config.json file.

See the CLI Tool reference guide for more information.

Add the translate command to your build process.

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}

Summary

In this guide, we covered how to setup your Next.js app with gt-next
We briefly covered the different ways to translate content in your application.
We also covered how to deploy your application after you've internationalized your content.

Next Steps

Learn about how to translate JSX content with the <T> component: Translating JSX
Learn about how to translate strings with the useGT hook: Translating Strings
Learn how to use local translations: Local Translations

Next.js Quickstart

Overview

Prerequisites

Installation

Configuration

`withGTConfig`

`GTProvider`

Environment Variables

Usage

`<T>` Component

`useGT` Hook

Testing Your App

See Your App in a Different Language

Troubleshooting

Deployment

Summary

Next Steps

On this page

Next.js Quickstart

What if I don't want to use the General Translation platform?

My app's language is not changing, even though I've changed my browser's language.

Why do languages take a long time to load in dev?

Why are some things translating and others not?

Why are some translations inaccurate?

What if I'm not using the General Translation platform?

On this page