GitHub

Prerequisites: Next.js App Router, basic JavaScript knowledge

Quick setup: Try npx gtx-cli@latest for automatic configuration. See the Setup Wizard guide or use our AI tools integration.

Installation

Install the gt-next and gtx-cli packages:

npm i gt-next gtx-cli

yarn add gt-next
yarn add --dev gtx-cli

bun add gt-next
bun add --dev gtx-cli

pnpm add gt-next
pnpm add --save-dev gtx-cli

Configuration

`withGTConfig`

The withGTConfig function initialises the SDK in your Next.js application. Add it to your next.config.[js|ts] file:

next.config.ts

import { withGTConfig } from 'gt-next/config';

const nextConfig = {
  // Your existing Next.js config
};

export default withGTConfig(nextConfig, {
  // Additional GT configuration options
});

`GTProvider`

The GTProvider component provides translation context to client-side components. It manages locale state and translations, and enables the useGT and useTranslations hooks.

Add the GTProvider to your root layout(s):

app/layout.tsx

import { GTProvider } from 'gt-next';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GTProvider>
          {children}
        </GTProvider>
      </body>
    </html>
  );
}

Create a gt.config.json file in your project root:

gt.config.json

{
  "defaultLocale": "en",
  "locales": ["fr", "es", "de"]
}

Customise the locales for your project. See supported locales for options.

Environment Variables

Add to your .env.local file for development hot reloading:

.env.local

GT_API_KEY="your-dev-api-key"
GT_PROJECT_ID="your-project-id"

Development only: Don’t set GT_API_KEY in production — it’s only for development hot reloading.

Get your free API keys at dash.generaltranslation.com or run:

npx gtx-cli auth

Usage

You can now start internationalising your content. There are two main approaches:

JSX Content with `<T>`

Wrap JSX elements to translate them using the <T> component:

import { T } from 'gt-next';

function Welcome() {
  return (
    <T>
      <h1>Welcome to our app!</h1>
    </T>
  );
}

For dynamic content, use variable components like <Var>:

import { T, Var } from 'gt-next';

function Greeting({ user }) {
  return (
    <T>
      <p>Hello, <Var>{user.name}</Var>!</p>
    </T>
  );
}

See the guide on using the <T> component for more information.

Plain strings with `useGT`

For attributes, labels, and plain text using the useGT hook:

import { useGT } from 'gt-next';

function ContactForm() {
  const t = useGT();
  
  return (
    <input 
      placeholder={t('Enter your email address')}
      aria-label={t('Email address input field')}
    />
  );
}

For server components, use getGT instead of useGT.

See the guide on translating strings for more information.

Testing Your App

Test your translations by switching languages:

Add a locale selection dropdown using <LocaleSelector>:

import { LocaleSelector } from 'gt-next';

function App() {
  return <LocaleSelector />;
}

Start your dev server:

npm run dev

yarn run dev

bun run dev

pnpm run dev

Visit localhost:3000 and change languages via the locale selection dropdown.

In development, translations happen on demand (you’ll see a brief loading time). In production, everything is pre-translated.

Troubleshooting

Deployment

For production, you need to pre-translate content since runtime translation is disabled (except for the <Tx> and tx functions).

Get a production API key from dash.generaltranslation.com.

Production keys begin with gtx-api- (unlike dev keys, which start with gtx-dev-). Learn more about environment differences.
Add to your CI/CD environment:
```
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```
Never prefix production keys with NEXT_PUBLIC_ — they must remain server-side only.
Run the translate command to translate your content:
```
npx gtx-cli translate
```
You can configure the behaviour of the translate command with the gt.config.json file.

See the CLI tool reference guide for more information.

Update your build script to translate before building:

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}

Next steps

<T> component guide - Deep dive into the <T> component and JSX translation
String translation guide - Using useGT and getGT
Variable components - Handle dynamic content with <Var>, <Num>, etc.

Prerequisites: Next.js App Router, basic JavaScript knowledge

Quick setup: Try npx gtx-cli@latest for automatic configuration. See the Setup Wizard guide or use our AI tools integration.

Installation

Install the gt-next and gtx-cli packages:

npm i gt-next gtx-cli

yarn add gt-next
yarn add --dev gtx-cli

bun add gt-next
bun add --dev gtx-cli

pnpm add gt-next
pnpm add --save-dev gtx-cli

Configuration

`withGTConfig`

The withGTConfig function initialises the SDK in your Next.js application. Add it to your next.config.[js|ts] file:

next.config.ts

import { withGTConfig } from 'gt-next/config';

const nextConfig = {
  // Your existing Next.js config
};

export default withGTConfig(nextConfig, {
  // Additional GT configuration options
});

`GTProvider`

The GTProvider component provides translation context to client-side components. It manages locale state and translations, and enables the useGT and useTranslations hooks.

Add the GTProvider to your root layout(s):

app/layout.tsx

import { GTProvider } from 'gt-next';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GTProvider>
          {children}
        </GTProvider>
      </body>
    </html>
  );
}

Create a gt.config.json file in your project root:

gt.config.json

{
  "defaultLocale": "en",
  "locales": ["fr", "es", "de"]
}

Customise the locales for your project. See supported locales for options.

Environment Variables

Add to your .env.local file for development hot reloading:

.env.local

GT_API_KEY="your-dev-api-key"
GT_PROJECT_ID="your-project-id"

Development only: Don’t set GT_API_KEY in production — it’s only for development hot reloading.

Get your free API keys at dash.generaltranslation.com or run:

npx gtx-cli auth

Usage

You can now start internationalising your content. There are two main approaches:

JSX Content with `<T>`

Wrap JSX elements to translate them using the <T> component:

import { T } from 'gt-next';

function Welcome() {
  return (
    <T>
      <h1>Welcome to our app!</h1>
    </T>
  );
}

For dynamic content, use variable components like <Var>:

import { T, Var } from 'gt-next';

function Greeting({ user }) {
  return (
    <T>
      <p>Hello, <Var>{user.name}</Var>!</p>
    </T>
  );
}

See the guide on using the <T> component for more information.

Plain strings with `useGT`

For attributes, labels, and plain text using the useGT hook:

import { useGT } from 'gt-next';

function ContactForm() {
  const t = useGT();
  
  return (
    <input 
      placeholder={t('Enter your email address')}
      aria-label={t('Email address input field')}
    />
  );
}

For server components, use getGT instead of useGT.

See the guide on translating strings for more information.

Testing Your App

Test your translations by switching languages:

Add a locale selection dropdown using <LocaleSelector>:

import { LocaleSelector } from 'gt-next';

function App() {
  return <LocaleSelector />;
}

Start your dev server:

npm run dev

yarn run dev

bun run dev

pnpm run dev

Visit localhost:3000 and change languages via the locale selection dropdown.

In development, translations happen on demand (you’ll see a brief loading time). In production, everything is pre-translated.

Troubleshooting

Deployment

For production, you need to pre-translate content since runtime translation is disabled (except for the <Tx> and tx functions).

Get a production API key from dash.generaltranslation.com.

Production keys begin with gtx-api- (unlike dev keys, which start with gtx-dev-). Learn more about environment differences.
Add to your CI/CD environment:
```
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```
Never prefix production keys with NEXT_PUBLIC_ — they must remain server-side only.
Run the translate command to translate your content:
```
npx gtx-cli translate
```
You can configure the behaviour of the translate command with the gt.config.json file.

See the CLI tool reference guide for more information.

Update your build script to translate before building:

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}

Next steps

<T> component guide - Deep dive into the <T> component and JSX translation
String translation guide - Using useGT and getGT
Variable components - Handle dynamic content with <Var>, <Num>, etc.

Prerequisites: Next.js App Router, basic JavaScript knowledge

Quick setup: Try npx gtx-cli@latest for automatic configuration. See the Setup Wizard guide or use our AI tools integration.

Installation

Install the gt-next and gtx-cli packages:

npm i gt-next gtx-cli

yarn add gt-next
yarn add --dev gtx-cli

bun add gt-next
bun add --dev gtx-cli

pnpm add gt-next
pnpm add --save-dev gtx-cli

Configuration

`withGTConfig`

The withGTConfig function initialises the SDK in your Next.js application. Add it to your next.config.[js|ts] file:

next.config.ts

import { withGTConfig } from 'gt-next/config';

const nextConfig = {
  // Your existing Next.js config
};

export default withGTConfig(nextConfig, {
  // Additional GT configuration options
});

`GTProvider`

The GTProvider component provides translation context to client-side components. It manages locale state and translations, and enables the useGT and useTranslations hooks.

Add the GTProvider to your root layout(s):

app/layout.tsx

import { GTProvider } from 'gt-next';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <GTProvider>
          {children}
        </GTProvider>
      </body>
    </html>
  );
}

Create a gt.config.json file in your project root:

gt.config.json

{
  "defaultLocale": "en",
  "locales": ["fr", "es", "de"]
}

Customise the locales for your project. See supported locales for options.

Environment Variables

Add to your .env.local file for development hot reloading:

.env.local

GT_API_KEY="your-dev-api-key"
GT_PROJECT_ID="your-project-id"

Development only: Don’t set GT_API_KEY in production — it’s only for development hot reloading.

Get your free API keys at dash.generaltranslation.com or run:

npx gtx-cli auth

Usage

You can now start internationalising your content. There are two main approaches:

JSX Content with `<T>`

Wrap JSX elements to translate them using the <T> component:

import { T } from 'gt-next';

function Welcome() {
  return (
    <T>
      <h1>Welcome to our app!</h1>
    </T>
  );
}

For dynamic content, use variable components like <Var>:

import { T, Var } from 'gt-next';

function Greeting({ user }) {
  return (
    <T>
      <p>Hello, <Var>{user.name}</Var>!</p>
    </T>
  );
}

See the guide on using the <T> component for more information.

Plain strings with `useGT`

For attributes, labels, and plain text using the useGT hook:

import { useGT } from 'gt-next';

function ContactForm() {
  const t = useGT();
  
  return (
    <input 
      placeholder={t('Enter your email address')}
      aria-label={t('Email address input field')}
    />
  );
}

For server components, use getGT instead of useGT.

See the guide on translating strings for more information.

Testing Your App

Test your translations by switching languages:

Add a locale selection dropdown using <LocaleSelector>:

import { LocaleSelector } from 'gt-next';

function App() {
  return <LocaleSelector />;
}

Start your dev server:

npm run dev

yarn run dev

bun run dev

pnpm run dev

Visit localhost:3000 and change languages via the locale selection dropdown.

In development, translations happen on demand (you’ll see a brief loading time). In production, everything is pre-translated.

Troubleshooting

Deployment

For production, you need to pre-translate content since runtime translation is disabled (except for the <Tx> and tx functions).

Get a production API key from dash.generaltranslation.com.

Production keys begin with gtx-api- (unlike dev keys, which start with gtx-dev-). Learn more about environment differences.
Add to your CI/CD environment:
```
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```
Never prefix production keys with NEXT_PUBLIC_ — they must remain server-side only.
Run the translate command to translate your content:
```
npx gtx-cli translate
```
You can configure the behaviour of the translate command with the gt.config.json file.

See the CLI tool reference guide for more information.

Update your build script to translate before building:

package.json

{
  "scripts": {
    "build": "npx gtx-cli translate && <...YOUR_BUILD_COMMAND...>"
  }
}

Next steps

<T> component guide - Deep dive into the <T> component and JSX translation
String translation guide - Using useGT and getGT
Variable components - Handle dynamic content with <Var>, <Num>, etc.

Next.js Quickstart

What if I don't want to use the General Translation platform?

My app's language isn’t changing, even though I’ve changed my browser’s language.

Why do languages take a long time to load in dev?

Why are some translations inaccurate?

What if I'm not using the General Translation platform?

On this page

Next.js Quickstart

What if I don't want to use the General Translation platform?

My app's language isn’t changing, even though I’ve changed my browser’s language.

Why do languages take a long time to load in dev?

Why are some translations inaccurate?

What if I'm not using the General Translation platform?

On this page

Next.js Quickstart

What if I don't want to use the General Translation platform?

My app's language isn’t changing, even though I’ve changed my browser’s language.

Why do languages take a long time to load in dev?

Why are some translations inaccurate?

What if I'm not using the General Translation platform?

On this page

GitHubStar on GitHub

GitHubStar on GitHub

Star on GitHub

Star on GitHub