Next.js Quickstart

Prerequisites: Next.js 13+ with App Router

Quick Setup: Try npx gtx-cli@latest for automatic configuration. Run the Setup Wizard or use Locadex to set it up for you.

Installation

Install the gt-next and gtx-cli packages:

npm i gt-next
npm i -D 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 initializes the SDK in your NextJS 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, 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"]
}

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

Environment variables

Add to your .env.local file for development hot-reloading and on-demand translations:

.env.local

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

Dev vs prod keys: Use a gtx-dev- key locally. Use a gtx-api- key in CI/CD if you run gtx-cli translate during deploy. Never expose GT_API_KEY to the browser or commit it to source control.

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

npx gtx-cli auth

Usage

Now you can start internationalizing 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 gt = useGT();

  return (
    <input
      placeholder={gt('Enter your email')}
      aria-label={gt('Email 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, translations are pre-generated by the CLI.

Troubleshooting

Deployment

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

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

Production keys begin with gtx-api- (different from 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 should remain server-side only.
Run the translate command to translate your content:
```
npx gtx-cli translate
```
You can configure the behavior 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 13+ with App Router

Quick Setup: Try npx gtx-cli@latest for automatic configuration. Run the Setup Wizard or use Locadex to set it up for you.

Installation

Install the gt-next and gtx-cli packages:

npm i gt-next
npm i -D 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 initializes the SDK in your NextJS 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, 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"]
}

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

Environment variables

Add to your .env.local file for development hot-reloading and on-demand translations:

.env.local

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

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

npx gtx-cli auth

Usage

Now you can start internationalizing 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 gt = useGT();

  return (
    <input
      placeholder={gt('Enter your email')}
      aria-label={gt('Email 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, translations are pre-generated by the CLI.

Troubleshooting

Deployment

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

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

Production keys begin with gtx-api- (different from 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 should remain server-side only.
Run the translate command to translate your content:
```
npx gtx-cli translate
```
You can configure the behavior 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 13+ with App Router

Quick Setup: Try npx gtx-cli@latest for automatic configuration. Run the Setup Wizard or use Locadex to set it up for you.

Installation

Install the gt-next and gtx-cli packages:

npm i gt-next
npm i -D 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 initializes the SDK in your NextJS 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, 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"]
}

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

Environment variables

Add to your .env.local file for development hot-reloading and on-demand translations:

.env.local

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

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

npx gtx-cli auth

Usage

Now you can start internationalizing 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 gt = useGT();

  return (
    <input
      placeholder={gt('Enter your email')}
      aria-label={gt('Email 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, translations are pre-generated by the CLI.

Troubleshooting

Deployment

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

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

Production keys begin with gtx-api- (different from 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 should remain server-side only.
Run the translate command to translate your content:
```
npx gtx-cli translate
```
You can configure the behavior 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

Can I use my own translations?

My app's language is not 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

Can I use my own translations?

My app's language is not 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

Can I use my own translations?

My app's language is not 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