Next.js Quickstart

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:

This entire process should take under 5 minutes.

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.

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.

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.

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

npx gtx-cli setup

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

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.

GT_API_KEY="YOUR_GT_API_KEY"
GT_PROJECT_ID="YOUR_GT_PROJECT_ID"

Let's Try It Out!

Congratulations! 🥳 Your app is now multilingual! Let's see it in action.

See Your App in a Different Language

npm run dev 

Troubleshooting

Shipping to Production

Follow our guide on shipping to production.

Next steps

• See our Next.js API reference for detailed information about the <T> component and other available components.
• Improve your content with <Num>, <Currency>, <Branch>, and <Plural> components.
• Learn how to improve SEO with i18n routing (adding routes for each locale, e.g. example.com/en, example.com/fr)
• Mirror your app to support right-to-left languages such as Arabic and Hebrew.
• Create a list of approved languages for your app with the Next.js plugin.