Next.js App Router

This guide describes how to add gt-next to a Next.js (opens in a new tab) project which is using the App Router (opens in a new tab).

Set up your local environment

Navigate to your existing Next.js app, or follow the instructions here (opens in a new tab) to create a new one.

In your local environment, usually .env.local, set two environment variables:

GT_API_KEY=""
GT_PROJECT_ID=""

An API key (GT_API_KEY) is a 36-character string beginning gtx- which is used to authenticate your app with our cloud translation service. Create one on the API Keys (opens in a new tab) page.

Your Project ID can also be found on the Dashboard:

Code copy container entitled "projectID"

Install the library

To install gt-next, navigate to your Next.js project's root directory and run:

npm i gt-react

Install the plugin

In the root directory of your project, there should be a file called next.config.js (or .ts, .mjs, .cjs).

my-app/
├── src/
│   ├── app/
│   │    └── page.js
│   └── components/
│       ├── Header.js
│       └── Footer.js
├── public/
│   └── favicon.ico
├── next.config.js
├── .gitignore
├── package.json
└── README.md

Edit your next.config.js file to run initGT(). This function will let you add configuration options like a non-English default language (defaultLocale) or a list of approved languages to translate into (locales). Use the withGT() plugin it returns to configure Webpack (opens in a new tab) to bundle your dictionary.js file into production builds of your app.

// next.config.mjs
 
import { initGT } from 'gt-next/config'
 
const withGT = initGT()
 
export default withGT({});

Dictionaries

Keeping translatable content in a single .json or .js file is a common technique in web app development. Using a single dictionary allows for easier management of translations and ensures consistency across the application.

Uniquely, gt-react dictionaries don't just support strings. You can write content in JSX too! This means you can usually copy and paste the content of your components directly into a gt-react dictionary.

A simple dictionary could look something like:

// dictionary.js
 
const dictionary = {
    "landing": {
        "hero": <h1>Welcome to our site!</h1>,
        "get_started_button": (
            <a href='/signin'><button>Get Started</button></a>
        )
    },
    "dashboard": {
        "welcome": <p><b>Welcome</b> to the Dashboard!</p>
    }
}
 
export default dictionary;

Dictionaries can include plural forms, variables, and context for the AI model to use while translating.

Create a file called dictionary.js (or .jsx, .ts, .tsx) and place it into the root directory of your project (or src/dictionary.js if you are using the src folder).

my-app/
├── src/
│   ├── app/
│   │    └── page.js
│   ├── components/
│   │   ├── Header.js
│   │   └── Footer.js
│   └── dictionary.js
├── public/
│   └── favicon.ico
├── next.config.js
├── .gitignore
├── package.json
└── README.md

`getGT()`

Once you've installed the plugin in next.config.js and created a dictionary.js file, you can begin using items from your dictionary in your application:

// page.js
// will work as a server component
// or as a client component if the child of a <GTProvider>
 
import { getGT } from 'gt-next'
 
export default function Page() {
 
    const t = getGT(); // you can pass a string as an optional prefix to getGT()
 
    return (
        <main>
            {t('landing.hero')}
        </main>
    )
}

`<GTProvider>`

To provide the dictionary to client components, you should use <GTProvider>. Make sure every client component in which you use items from your dictionary is the descendant of a <GTProvider>.

// page.json
 
import { GTProvider } from 'gt-next'
import SomeClientComponent from './SomeClientComponent'
 
export default function Page() {
    return (
        <main>
            <GTProvider>
                <SomeClientComponent/>
            </GTProvider>
        </main>
    )
}

If you only want to provide a subset of your dictionary, use the id prop of <GTProvider>:

// page.json
 
import { GTProvider } from 'gt-next'
import Dashboard from './Dashboard'
 
export default function Page() {
    return (
        <main>
            <GTProvider id='dashboard'>
                <Dashboard/>
            </GTProvider>
        </main>
    )
}

In this example, getGT() on the client side will only be able to access items in the dictionary beginning "dashboard.". (Do not include "dashboard.", in the id parameter of your t() or getGT() functions.)

Next steps

Learn more about the t() function, including how to handle variables and plurals.
Set up i18n routing (adding routes for each locale, e.g. example.com/en, example.com/fr) for better SEO
Set up your app so that the UI is mirrored for languages like Arabic and Hebrew, which are written right-to-left.

Introduction React