General Translation  
Next.js

Quickstart

For the Next.js 13+ App Router

Overview

This guide describes how to internationalize an existing Next.js project that uses the App Router with gt-next. We will cover four simple steps:

Install the gt-next library

Use the <T> component to translate your app

Add the <GTProvider> component

Update your env variables

Setup

1. Install gt-next

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

npm i gt-next

2. Translate with the <T> Component

To translate your app, wrap the content you want to translate in a <T> component. Just remember, every <T> component should have a unique id prop.

The text and structure of the tags inside your <T> component should be static. For dynamic content, use the <Var> component.

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

3. Wrap Your App with the <GTProvider> Component

To add translations to client <T> components, wrap your app in the <GTProvider> component.

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

4. Set up your local environment

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

Navigate to your GT Dashboard.

  • Production Environments: Navigate to the API Keys page in the sidebar.
  • 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 your Project ID and your 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

Before Shipping to Production...

Perform Translation Ahead of Time

In production, we strongly recommend translating your application ahead of time, rather than translating everything on demand. This has major performance benefits for your application, and can easily be integrated into your CI/CD pipeline.

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 before you run this command.

npx translate

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

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

Previous

Introduction

Next

<T>

On this page

Overview
Setup
1. Install gt-next
2. Translate with the <T> Component
3. Wrap Your App with the <GTProvider> Component
4. Set up your local environment
Let's Try It Out!
See Your App in a Different Language
Troubleshooting
Before Shipping to Production...
Perform Translation Ahead of Time
Next steps