Next.js Quickstart

Internationalize your Next.js App in 5 minutes with gt-next

Overview

This guide describes how to internationalize an existing Next.js project that uses the App Router.

For a project using the Pages Router, follow the React docs.

We will cover 4 simple steps:

Installing gt-next and gtx-cli

Select languages

Add the <T> component

Add your environment variables

This entire process should take under 5 minutes.

Are you using the Next.js pages router? Follow the React Quickstart guide instead.


Setup

1. Install libraries

Install the gt-next and gtx-cli libraries.

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

2. Add the withGTConfig() plugin

Add withGTConfig() to your next.config.js file. You can specify the languages you want to support by passing an array of locale codes.

next.config.js
import { withGTConfig } from 'gt-next/config';
 
const nextConfig = {};
 
export default withGTConfig(nextConfig, {
  locales: ['pt', 'es'], // Support for Portuguese and Spanish
});

3. Add the <T> component

Wrap any nested JSX content in the <T> component to make it translatable. For more information, check out the guide on using <T> components.

Example.js
import { T } from "gt-next";
 
export default function Example() {
  return (
    <T>
      <p>
        This gets translated.
      </p>
    </T>  
  );
}

Use the <Var> component to designate JSX content that should not be translated.

Example.js
import { T, Var } from "gt-next";
 
export default function Example() {
  return (
    <T>
      <p>
        This gets translated. <Var>This does not.</Var>
      </p>
    </T>  
  );
}

Tip: To save time, run the setup command. This will scan your codebase for translatable JSX and insert the <T> tags for you.

shell
npx gtx-cli setup

For strings, you can use useGT() or getGT() for translation. For more information, check out this guide.

Example.js
import { useGT } from "gt-next/client";
import { getGT } from "gt-next/server";
 
export default function Example() {
  const t = useGT(); // client side
  const t = await getGT(); // server side
  return (
    <p>
      {t("This gets translated.")}
    </p>
  );
}

4. Add your environment variables

Add your API key and Project ID to your local environment.

Navigate to the Dashboard. Go to the Developer Keys page in the sidebar.

Click Create Dev API Key.

Add the Project ID and Development API key to your environment.

.env.local
GT_API_KEY="YOUR_GT_API_KEY"
GT_PROJECT_ID="YOUR_GT_PROJECT_ID"

Protect Your API Keys!

Development keys should only ever be used in development. Likewise, production keys should only ever be used in production. Never commit your API keys to a public repository!


Let's Try It Out!

Congratulations! 🥳 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 change your language in your browser settings.

Start your Next.js app in development mode.

npm run dev 

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

Troubleshooting


Shipping to Production

Follow our guide on shipping to production.

Next steps

On this page