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 3 simple steps:

Setup

1. Running the setup wizard

The setup wizard will walk you through the process of internationalizing your project.

npx gtx-cli@latest init

To manually setup your project, follow the manual setup guide.

The setup wizard will:

1. Install the required libraries.
2. Configure your project's supported locales.
3. Wrap your project's JSX components with the <T> component.
4. Add withGTConfig() to your next.config.js file.
5. Generate a production API key and project ID for your project.

See the setup wizard docs for more information.

2. Adding environment variables

The setup wizard will create a .env.local file for you in the root of your project containing your production API key and project ID.

However, in order to use gt-next in development mode, you will need to add a development API key instead of a production one.

GT_API_KEY="YOUR_GT_API_KEY"
GT_PROJECT_ID="YOUR_GT_PROJECT_ID"

3. Cleaning up strings

The setup wizard will wrap all of your project's JSX components with the <T> component. However, you may notice that strings are unaffected.

For example, if you have a string constant like this:

export default function Example() {
  const greeting = "Hello, world!";
  return <p>{greeting}</p>;
}

The setup wizard will not touch this string.

To fix this, you can use the useGT() hook and getGT() function to translate the string.

import { useGT } from "gt-next/client";
export default function Example() {
  const t = useGT();
  return <p>{t("Hello, world!")}</p>;
}

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) and static site generation.
• Mirror your app to support right-to-left languages such as Arabic and Hebrew.

Manual Setup

If you prefer to do the setup manually, follow the steps below.

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>  
  );
}

For strings, you can use useGT() or getGT() for translation.

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"