Next.js Quickstart

Overview

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

We will cover 3 simple steps:

Installing the required libraries

Run the CLI tool to setup your codebase

Update your env variables

This entire process should take under 5 minutes.

Setup

1. Install libraries

Install the gt-next and gt-react-cli libraries.

npm i gt-next gt-react-cli

2. Run our CLI tool

Run the gt-react-cli tool to setup your project for translation.

This will scan your codebase for translatable content and automatically wrap it in <T> components.

shell

npx gt-cli setup

See the CLI tool documentation for more information.

Experimental

This feature is currently experimental and may not work perfectly. If you run into any issues, please let us know by creating an issue on our GitHub repository. In particular, note that some manual edits may be required.

Example

The CLI tool will wrap any JSX elements containing translatable content in <T> components. Each component will be given a unique id prop.

See the <T> component documentation for more information.

app/page.js

import { T } from "gt-next"; 
import { Card, CardHeader, CardContent } from "@components/ui/Card";
 
export default function Page() {
  return (
    <T id="app.page.0">
      {/* This text will be translated */}
      <b>Shakespeare&apos;s</b> quotes
      {/* Any arbitrary components and their children will also be translated */}
      <Card>
        <CardHeader>Hamlet</CardHeader>
        <CardContent>
          <p>&quot;To be, or not to be: that is the question...&quot;</p>
        </CardContent>
      </Card>
    </T> 
  );
}

3. Set up your local environment

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

Navigate to your GT Dashboard.

For Production Environments: Navigate to the API Keys page in the sidebar.
For Development Environments: Navigate to the Developer Keys page in the sidebar.

Click Create Dev API Key or Create API Key then copy the API key and Project ID to your clipboard.

Add the Project ID and 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!

Production API keys should only be used in production environments and never in non-production environments. Likewise, development API keys should only be used for local environments.

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

Start by changing your preferred browser's language settings. This will change which language is displayed.

Change your language in Chrome
Change your language in Firefox
Change your language in Edge

Start your Next.js app in development mode.

npm run dev

Open up your app in your preferred browser (usually at http://localhost:3000). If you want to switch languages, just select a different language in your browser settings and refresh the page.

Troubleshooting

Shipping to Production

CLI Tool

In order to ship your app to production, you will need to run our CLI tool to parse your codebase and validate your content.

Security

Due to the nature of client-sided rendering in React and Next.js client components, you must pre-authorize your content with the CLI tool before it can be translated. This means that you must run the CLI tool before deploying to your production environment.

Just run the following command in your project's root directory. Make sure to add your production API key and project ID to your environment variables before you run this command.

npx gt-cli translate

Additionally, if your project has CI/CD, you should add this command to your deployment pipeline.

For more information, see the CLI tool documentation.

For Production Only!

This CLI tool is meant to only be used for production deployments. Make sure you have the correct API key and project ID in your environment variables, and make sure that you are translating the same content that is being used for production (i.e., the branch you are on when you run this command is the branch used for 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.

Next.js Quickstart

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

Why do new languages take a long time to load?

On this page