Next.js Quickstart
Easily internationalize your Next.js App with gt-next
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.
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
useDict
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.
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.
{
"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/client';
const translate = useGT();
translate('Hello, world!');
The useGT
hook is a client-side hook, and should only be used in client-side components.
For server-side 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).
Troubleshooting
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.
{
"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
How is this guide?