Next.js Quickstart

This guide describes how to add gt-next to a Next.js project which is using the App Router.

The two core components of the library are:

<T>, with which you mark the content you want to translate
<GTProvider>, which provides translations and language information from the server to client-side components using React's context API

Set up your local environment

Navigate to your existing Next.js app, or follow the instructions here 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 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-next

Set the `<html>` language

To create a list of approved locales your app supports, use the Next.js plugin in your next.config.js file. This is recommended but not required.

Browsers read the lang attribute of the <html> tag to check the language of a site. In Next.js, you set the lang attribute in your root layout.js file.

getLocale() is a function which returns the current language of the page, based on the user's language preferences and the translations available.

Make sure the value of lang is the result of the getLocale() function.

// app/layout.js
 
import { getLocale } from 'gt-next';
 
export default function RootLayout({ children }) {
    return (
        <html lang={getLocale()}>
            <body>{children}</body>
        </html>
    );
}

Use the `<T>` component

To mark JSX for translation, pass it as the children of your <T> component. Every <T> component you need translated should have a unique id prop:

import { T } from 'gt-next'
 
export default function Page() {
    return (
        <T id='my_id'>
            Hello, world
        </T>
    )
}

The text and structure of the tags inside your <T> component should be static. Attributes like className can be dynamic. To include dynamic variables inside your <T> component, use the <Var> component:

import { T, Var } from 'gt-next'
 
export default function Page() {
 
    const name = "Alice"; // or "Bob", "Charlie", etc.
 
    return (
        <T id='my_other_id'>
            Hello, <Var>{name}</Var>
        </T>
    )
}

The children of a <Var> component will never be translated and will remain private.

Learn how to include:

Plural forms with the <Plural> component
Formatted variables like numbers, currencies, and dates
Context for the AI model to use while translating
Translating strings rather than JSX elements

`<GTProvider>`

To provide translations 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>
    )
}

Try it out!

As of 10/11/24, on-demand translation only works in server components.

Now that content is loading in your defaultLocale (usually English), you can use on-demand translation to test it out. Simply change your browser language and reload the page. The first time you do this, translations will take a few seconds to load. Afterwards, they will be cached, and load instantly.

`gt-update`

In production, we recommend using the gt-update CLI tool to request translations, rather than translating everything on demand.

Install gt-update globally or as a developer dependency, so it doesn't increase your app's production bundle size.

npm i -g gt-update

To run a script that will scan through your project and send each item for translation, run npx i18n. This script requires your API key and projectID, but gt-update automatically reads your environment variables for GT_API_KEY and GT_PROJECT_ID, so you usually don't have to include them:

npx i18n --languages fr es ja

Or, with projectID and apiKey:

npx i18n --apiKey YOUR_API_KEY --projectID YOUR_PROJECT_ID --languages fr es ja

If the script is successful, you should see the following message in the console:

Project "YOUR_PROJECT_ID" updated: true. Languages: ["French", "Japanese", "Spanish"]. Translations are usually live within a minute. Check status: www.generaltranslation.com/dashboard.

Translations are usually ready within a minute, but could take up to five minutes in periods of high demand. When translations are ready should be able to access them via the cache in both your local and production projects.

Learn more about gt-update here.

Congratulations! Your app is now multilingual! 🥳

Next steps

Learn more about the <T> component, or dictionaries with getGT()
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.

Next.js Quickstart

On this page