General Translation Next.js SDK

https://generaltranslation.com/en-US/docs/next/
Admin
General Translation is an open-source internationalization library for Next.js that provides...
Tokens:63,365
Snippets:814
Trust Score:7.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Navigate and start the development server

Source: https://generaltranslation.com/en-US/docs/next/tutorials/examples/currency-converter/setup

Commands to enter the project directory, install dependencies, and launch the local development environment.

```bash
cd currencies
npm install
npm run dev
```

--------------------------------

### Initialize Next.js project

Source: https://generaltranslation.com/en-US/docs/next/tutorials/examples/currency-converter/setup

Run this command to start the interactive setup wizard for a new Next.js application.

```bash
npx create-next-app@latest
```

--------------------------------

### Start Development Server

Source: https://generaltranslation.com/en-US/docs/next/tutorials/examples/next-speedrun

Launches the Next.js development server to verify the internationalization setup.

```bash
npm run dev
```

--------------------------------

### Install gt-next and CLI

Source: https://generaltranslation.com/en-US/docs/next/guides/migration

Install the necessary packages using your preferred package manager.

```bash
npm i gt-next gt
```

```bash
yarn add gt-next
yarn add --dev gt
```

```bash
bun add gt-next
bun add --dev gt
```

```bash
pnpm add gt-next
pnpm add --save-dev gt
```

--------------------------------

### Start Development Server

Source: https://generaltranslation.com/en-US/docs/next

Launch the local development server using the preferred package manager.

```bash
npm run dev
```

```bash
yarn dev
```

```bash
bun dev
```

```bash
pnpm dev
```

--------------------------------

### Install gt-next library

Source: https://generaltranslation.com/en-US/docs/next/tutorials/examples/currency-converter/preptx

Run this command in your project root to install the necessary dependency.

```bash
npm i gt-next
```

--------------------------------

### Install gt-next-lint

Source: https://generaltranslation.com/en-US/docs/next-lint

Install the package as a development dependency.

```bash
npm install --save-dev @generaltranslation/gt-next-lint
```

--------------------------------

### Install GT Dependencies

Source: https://generaltranslation.com/en-US/docs/next/tutorials/examples/next-speedrun

Installs the necessary General Translation packages in the project root.

```bash
cd next-quickstart
npm i gt-next
npm i gt
```

--------------------------------

### Run GT Setup CLI

Source: https://generaltranslation.com/en-US/docs/next/tutorials/examples/next-speedrun

Executes the CLI tool to automatically configure the codebase for translation.

```bash
npx gt setup
```

--------------------------------

### Quickstart with useGT

Source: https://generaltranslation.com/en-US/docs/next/guides/strings

Basic implementation of the useGT hook within a functional component to translate input attributes.

```jsx
import { useGT } from 'gt-next';

function MyComponent() {
  const gt = useGT();
  return (
    <input 
      placeholder={gt('Enter your email')}
      title={gt('Email address field')}
    />
  );
}
```

--------------------------------

### Configure Jest setup file

Source: https://generaltranslation.com/en-US/docs/next/faqs

Register the polyfill file in your Jest configuration to ensure the environment is correctly initialized.

```json
{
  "setupFiles": ["./jest.setup.js"]
}
```

--------------------------------

### Define dictionary structure

Source: https://generaltranslation.com/en-US/docs/next/guides/migration

Example of a JSON dictionary file structure used in the migration process.

```json
{
  "hello": {
    "description": "Hello, world!"
  }
}
```

--------------------------------

### Initialize Next.js Middleware

Source: https://generaltranslation.com/en-US/docs/next/guides/middleware

Basic setup for the middleware in proxy.ts, including the required matcher configuration to exclude static files and API routes.

```ts
import { createNextMiddleware } from 'gt-next/middleware';

export default createNextMiddleware();

export const config = {
  // Match all paths except API routes, static files, and Next.js internals
  matcher: ['/((?!api|trpc|_next|_vercel|.*\..*).*)']
};
```

--------------------------------

### Define dictionary entries

Source: https://generaltranslation.com/en-US/docs/next/api/dictionary/get-translations

Example of defining a basic translation entry in the dictionary file.

```jsx
const dictionary = {
  greeting: <>Hello, Alice!</>, // [!code highlight]
};
export default dictionary;
```

--------------------------------

### URL-based routing structure

Source: https://generaltranslation.com/en-US/docs/next/guides/languages

Example of how locale-prefixed URLs map to localized content.

```text
/en/products  → English products page  
/es/products  → Spanish products page
/fr/products  → French products page
```

--------------------------------

### Supported function syntax for Derive

Source: https://generaltranslation.com/en-US/docs/next/api/components/derive

Examples of statically analyzable function syntax supported by the Derive component.

```jsx
function getExamples(key) {
  switch (key) {
    case 'literals':
      if (condition1) {
        return 'The boy';
      } else if (condition2) {
        return 22;
      } else {
        return true;
      }
    case 'jsx':
      return (
        <>
          Hello, <Derive>{getTitle(title)}</Derive>. How are you,{' '}
          <Var>{name}</Var>?
        </>
      );
    case 'ternary':
      return condition ? 'The boy' : 'The girl';
    case 'function_calls':
      return otherStaticFunction();
  }
}
```

--------------------------------

### Representing variables in GT JSX

Source: https://generaltranslation.com/en-US/docs/next/reference/gt-jsx

Examples of mapping JSX variable components to the GT JSX object format.

```jsx
<T>Hello, <Var>{name}</Var>!</T>
```

```ts
["Hello, ", { k: "_gt_var_1", i: 1 }, "!"]
```

```jsx
<T>The count is <Num>{count}</Num></T>
```

```ts
["The count is ", { k: "count", v: "n", i: 1 }]
```

```jsx
<T>This product costs <Currency name="cost">{amount}</Currency></T>
```

```ts
["This product costs ", { k: "cost", v: "c", i: 1 }]
```

--------------------------------

### Configure CLI

Source: https://generaltranslation.com/en-US/docs/next/guides/local-tx

Run the configuration command to set up local storage preferences.

```bash
npx gt configure
```

--------------------------------

### Apply recommended configuration preset

Source: https://generaltranslation.com/en-US/docs/next-lint

Use the built-in recommended configuration to enable default warnings.

```javascript
import gtNext from "@generaltranslation/gt-next-lint";

export default [
  gtNext.configs.recommended,
];
```

--------------------------------

### Initialize Next.js Project

Source: https://generaltranslation.com/en-US/docs/next/tutorials/examples/next-speedrun

Creates a new Next.js application with TypeScript, Tailwind CSS, ESLint, and the App Router.

```bash
npx create-next-app next-quickstart --ts --tailwind --eslint --app --use-npm --src-dir
```

--------------------------------

### Get direction for the current locale

Source: https://generaltranslation.com/en-US/docs/next/api/helpers/use-locale-direction

Retrieves the text direction for the current locale from the GTProvider context.

```jsx
'use client';
import { useLocaleDirection } from 'gt-next';

export default function DirectionWrapper({ children }) {
  const dir = useLocaleDirection(); // [!code highlight]
  return <div dir={dir}>{children}</div>;
}
```

--------------------------------

### Basic usage of createNextMiddleware

Source: https://generaltranslation.com/en-US/docs/next/api/middleware/create-next-middleware

Add this function and the path matcher to your proxy file to enable locale routing.

```javascript
import { createNextMiddleware } from 'gt-next/middleware'

export default createNextMiddleware();

export const config = {
  matcher: [
    /*
      * Match all request paths except for the ones starting with:
      * - api (API routes)
      * - _next (internal files)
      * - static files
      */
    "/((?!api|trpc|_next|_vercel|.*\..*).*)",
  ],
}
```

--------------------------------

### Initialize SDK with withGTConfig

Source: https://generaltranslation.com/en-US/docs/next/introduction

Wrap your Next.js configuration object with withGTConfig in next.config.ts to enable SDK functionality.

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

const nextConfig = {
  // Your next.config.ts options
};

export default withGTConfig(nextConfig, {
  // Your GT configuration
});
```

--------------------------------

### Basic Var usage

Source: https://generaltranslation.com/en-US/docs/next/api/components/var

Demonstrates the standard implementation of the Var component for rendering dynamic content.

```jsx
<Var>{user.name}</Var>
```

--------------------------------

### Configure Environment Variables

Source: https://generaltranslation.com/en-US/docs/next

Define the required API credentials in a local environment file.

```bash
GT_API_KEY="your-api-key"
GT_PROJECT_ID="your-project-id"
```

--------------------------------

### Representing elements in GT JSX

Source: https://generaltranslation.com/en-US/docs/next/reference/gt-jsx

Examples of mapping JSX tags and nested structures to the GT JSX object format.

```jsx
<T>Hello, <b>world</b>!</T>
```

```ts
["Hello, ", { c: "world", i: 1 }, "!"]
```

```jsx
<T><b>Hello</b>, my name is <i><Var>{name}</Var></i></T>
```

```ts
[
    { t: "b", c: "Hello", i: 1 },
    ", my name is ",
    { 
        t: "i",
        c: { k: "_gt_var_3", i: 3 }, 
        i: 2 
    }
]
```

```jsx
<T>
    <Plural 
        n={count} 
        one={<>I have <Num>{count}</Num> item</>} 
        other={<>I have <Num>{count}</Num> items</>}
    />
</T>
```

```ts
{ 
    i: 1,
    d: {
        t: "p",
        b: {
            one: {
                c: ["I have", { k: "_gt_num_4", v: "n", i: 3 }, "item"],
                i: 2 
            },
            other: {
                c: ["I have", { k: "_gt_num_4", v: "n", i: 3 }, "items"],
                i: 2 // note the same ID is used for parallel branches
            }
        }
    }
}
```

--------------------------------

### Polyfill TextEncoder for Jest

Source: https://generaltranslation.com/en-US/docs/next/faqs

Use this setup file to resolve ReferenceError: TextEncoder is not defined when running tests in older jsdom environments.

```js
const { TextEncoder, TextDecoder } = require('util');
global.TextEncoder = TextEncoder;
global.TextDecoder = TextDecoder;
```

--------------------------------

### Basic useGT implementation

Source: https://generaltranslation.com/en-US/docs/next/api/strings/use-gt

Initializes the translation hook and wraps content for translation.

```jsx
const gt = useGT();

<p>{gt('This text will be translated')}</p>;
```

--------------------------------

### Get direction for a specific locale

Source: https://generaltranslation.com/en-US/docs/next/api/helpers/get-locale-direction

Retrieves the direction for a specific BCP 47 locale code. This usage is synchronous and does not require awaiting.

```jsx
import { getLocaleDirection } from 'gt-next/server';

export default function SpecificDirection() {
  const dir = getLocaleDirection('ar'); // 'rtl' — no await needed [!code highlight]
  return <p>Arabic text direction: {dir}</p>;
}
```

--------------------------------

### Define Dictionary Files

Source: https://generaltranslation.com/en-US/docs/next/guides/dictionaries

Create a dictionary file in the project root or src directory using either TypeScript or JSON format.

```ts
const dictionary = {
  greetings: {
    hello: 'Hello, world!',
    welcome: 'Welcome to our app!'
  },
  navigation: {
    home: 'Home',
    about: 'About',
    contact: 'Contact'
  }
};

export default dictionary;
```

```json
{
  "greetings": {
    "hello": "Hello, world!",
    "welcome": "Welcome to our app!"
  },
  "navigation": {
    "home": "Home", 
    "about": "About",
    "contact": "Contact"
  }
}
```

--------------------------------

### Authenticate via CLI

Source: https://generaltranslation.com/en-US/docs/next

Use the CLI tool to authenticate and retrieve API keys.

```bash
npx gt auth
```

--------------------------------

### Get direction for the current locale

Source: https://generaltranslation.com/en-US/docs/next/api/helpers/get-locale-direction

Retrieves the direction for the current user's locale. This usage is asynchronous and requires the await keyword.

```jsx
import { getLocaleDirection } from 'gt-next/server';

export default async function DirectionWrapper({ children }) {
  const dir = await getLocaleDirection(); // [!code highlight]
  return <div dir={dir}>{children}</div>;
}
```

--------------------------------

### createNextMiddleware(options)

Source: https://generaltranslation.com/en-US/docs/next/api/middleware/create-next-middleware

Initializes a middleware function for Next.js to handle locale-based routing and path localization.

```APIDOC
## createNextMiddleware(options)

### Description
Creates a middleware function for use with Next.js to enable i18n routing and path localization.

### Parameters
#### Options
- **pathConfig** (PathConfig) - Optional - A nested object that specifies localized paths for your application.
- **localeRouting** (boolean) - Optional - A flag to enable or disable i18n routing. Default: true.
- **prefixDefaultLocale** (boolean) - Optional - A flag to enable or disable the removal of the locale prefix from the default locale. Default: false.
- **ignoreSourceMaps** (boolean) - Optional - A flag to enable or disable ignoring source maps. Default: true.

### Usage Example
```js
import { createNextMiddleware } from 'gt-next/middleware'

export default createNextMiddleware({
  pathConfig: {
    "/about": "/about",
    "/airplanes": {
      "zh": "/飞机",
    }
  },
  prefixDefaultLocale: true
});
```
```

--------------------------------

### Initialize GTProvider in Root Layout

Source: https://generaltranslation.com/en-US/docs/next/guides/migration

Wrap the application content with the GTProvider component in the root layout.

```tsx
import { GTProvider } from 'gt-next'

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

--------------------------------

### Configure Currency Converter Files

Source: https://generaltranslation.com/en-US/docs/next/tutorials/examples/currency-converter/setup

Use these files to define the application layout and the main page content for the currency converter.

```tsx
import './globals.css';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}
```

```tsx
export default function Page() {
  return (
    <main>
      <h1>Currency Converter</h1>
      <p>Exchange rate: 1 USD = 0.92 EUR</p>
    </main>
  );
}
```

--------------------------------

### Component Pattern Implementation

Source: https://generaltranslation.com/en-US/docs/next/guides/dictionaries

Demonstrates the recommended approach using the <T> component for direct translation.

```tsx
// Direct component usage - recommended
function MyComponent() {
  return <T><div>Hello, world!</div></T>;
}
```

--------------------------------

### Configure build script for production

Source: https://generaltranslation.com/en-US/docs/next

Add the translation command to the build script to pre-generate translations at build time.

```json
{
  "scripts": {
    "build": "npx gt translate && next build"
  }
}
```

--------------------------------

### Set production environment variables

Source: https://generaltranslation.com/en-US/docs/next

Configure the required environment variables in your hosting provider for production.

```bash
GT_PROJECT_ID=your-project-id
GT_API_KEY=gtx-api-your-production-key
```

--------------------------------

### Configure environment variables

Source: https://generaltranslation.com/en-US/docs/next/tutorials/examples/currency-converter/preptx

Add your API credentials to a .env file in the project root to authenticate with the General Translation service.

```dotenv
GT_API_KEY="YOUR_GT_API_KEY"
GT_PROJECT_ID="YOUR_GT_PROJECT_ID"
```

--------------------------------

### Integrate with build process

Source: https://generaltranslation.com/en-US/docs/next/guides/local-tx

Add the translation generation command to your package.json build script.

```json
{
  "scripts": {
    "build": "npx gt translate && <...YOUR_BUILD_COMMAND...>"
  }
}
```

--------------------------------

### Basic usage of getLocaleProperties

Source: https://generaltranslation.com/en-US/docs/next/api/helpers/get-locale-properties

Demonstrates how to import and use the synchronous getLocaleProperties function within a server component to retrieve locale metadata.

```jsx
import { getLocaleProperties } from 'gt-next/server';

export default function LocaleInfo() {
  const props = getLocaleProperties('en-US'); // [!code highlight]
  return (
    <div>
      <p>Name: {props.name}</p>
      <p>Native name: {props.nativeName}</p>
      <p>Region: {props.regionName}</p>
    </div>
  );
}
```

--------------------------------

### Basic Branch Conditional Rendering

Source: https://generaltranslation.com/en-US/docs/next/api/components/branch

Demonstrates the fundamental syntax for conditional rendering using the Branch component.

```jsx
const status = 'active';
<Branch branch={status}
    active={<p>The user is active.</p>}
    inactive={<p>The user is inactive.</p>}
/>
```

--------------------------------

### withGTConfig(nextConfig, options)

Source: https://generaltranslation.com/en-US/docs/next/api/config/with-gt-config

Configures the gt-next library by wrapping the Next.js configuration object.

```APIDOC
## withGTConfig(nextConfig, options)

### Description
Wraps a Next.js `NextConfig` object to enable translation functionality and configure GT service settings.

### Parameters
#### Required Parameters
- **nextConfig** (NextConfig) - Required - The existing Next.js configuration object.

#### Optional Parameters
- **defaultLocale** (string) - Optional - The default locale for the application. Defaults to the first locale in the list or 'en'.
- **locales** (string[]) - Optional - An exclusive list of supported locales for the application.
- **description** (string) - Optional - A natural language description of the site to aid translation.

### Usage Example
```js
import { withGTConfig } from 'gt-next/config';

const nextConfig = {
    // your existing next.config.js
}

export default withGTConfig(nextConfig, {
  defaultLocale: 'en',
  locales: ['en', 'fr', 'es']
});
```
```

--------------------------------

### tx(content, options?)

Source: https://generaltranslation.com/en-US/docs/next/api/strings/tx

Translates a string at runtime on the server.

```APIDOC
## tx(content, options?)

### Description
Translates a string at runtime. This function is intended for server-side use only and performs translations live.

### Parameters
- **content** (string) - Required - The string that needs to be translated.
- **options** (RuntimeTranslationOptions) - Optional - Translation options to customize the behavior (e.g., $context, $locale, or variables).

### Returns
- **Promise<string>** - A promise that resolves to the translated string, or the original content if no translation is needed.

### Example
```javascript
import { tx } from 'gt-next/server';

// Basic usage
const greeting = await tx("Hello, world!");

// With context and locale
const informalGreeting = await tx("Hello, world!", { 
  $context: 'Translate informally', 
  $locale: 'fr' 
});

// With variables
const price = await tx("The cost is {price, number, ::currency/USD}", {
  price: 29.99,
});
```
```

--------------------------------

### Configure ESLint for gt-next

Source: https://generaltranslation.com/en-US/docs/next-lint

Add the plugin and rules to your eslint.config.mjs file.

```javascript
import gtNext from "@generaltranslation/gt-next-lint";

export default [
  {
    plugins: { 'gt-next': gtNext },
    rules: {
      'gt-next/no-dynamic-jsx': 'warn',
      'gt-next/no-dynamic-string': 'warn',
    },
  },
];
```

--------------------------------

### Basic usage of useRegion

Source: https://generaltranslation.com/en-US/docs/next/api/helpers/use-region

Demonstrates how to retrieve and display the current region in a client-side component.

```jsx
'use client';
import { useRegion } from 'gt-next';

export default function RegionDisplay() {
  const region = useRegion(); // [!code highlight]
  return <p>Current region: {region ?? 'Not set'}</p>;
}
```

--------------------------------

### Basic useTranslations usage

Source: https://generaltranslation.com/en-US/docs/next/api/dictionary/use-translations

Initialize the translation function and retrieve a string by its key.

```jsx
const t = useTranslations(); // Get the translation function
t('greeting.hello'); // pass the id to get a translation
```

--------------------------------

### Basic usage of GTProvider

Source: https://generaltranslation.com/en-US/docs/next/api/components/gtprovider

Wrap the root layout with GTProvider to enable translation context throughout the application.

```jsx
import { GTProvider } from 'gt-next';

export default function RootLayout({ children }) {
    return (
        <html lang="en">
            <body>
                <GTProvider> // [!code highlight]
                    {children}
                </GTProvider> // [!code highlight]
            </body>
        </html>
    );
}
```

--------------------------------

### Creating a dynamic content factory

Source: https://generaltranslation.com/en-US/docs/next/guides/strings

Centralize translation logic in utility files to be consumed by components.

```jsx
// utils/productData.js
export function getProductMessages(gt) {
  return {
    categories: [
      { id: 'electronics', name: gt('Electronics') },
      { id: 'clothing', name: gt('Clothing') },
      { id: 'books', name: gt('Books') }
    ],
    statusMessages: {
      available: gt('In stock and ready to ship'),
      backordered: gt('Currently backordered - ships in 2-3 weeks'),  
      discontinued: gt('This item has been discontinued')
    },
    errors: {
      notFound: gt('Product not found'),
      outOfStock: gt('Sorry, this item is currently out of stock')
    }
  };
}

// components/ProductCard.jsx
import { useGT } from 'gt-next';
import { getProductMessages } from '../utils/productData';

function ProductCard({ product }) {
  const gt = useGT();
  const messages = getProductMessages(gt);
  
  return (
    <div>
      <h3>{product.name}</h3>
      <p>{messages.statusMessages[product.status]}</p>
      <span>{messages.categories.find(c => c.id === product.categoryId)?.name}</span>
    </div>
  );
}
```

--------------------------------

### Define translation configuration

Source: https://generaltranslation.com/en-US/docs/next

Create a gt.config.json file in the project root to specify the default locale, supported languages, and output directory for generated translation files.

```json
{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"],
  "files": {
    "gt": {
      "output": "public/_gt/[locale].json"
    }
  }
}
```

--------------------------------

### Troubleshoot import paths

Source: https://generaltranslation.com/en-US/docs/next/guides/local-tx

Verify that the import path in your load function matches the actual directory structure.

```ts
// ❌ Wrong path
const t = await import(`../translations/${locale}.json`);

// ✅ Correct path for public/_gt
const t = await import(`../public/_gt/${locale}.json`);
```

--------------------------------

### Configure the SWC plugin in next.config.js

Source: https://generaltranslation.com/en-US/docs/next/concepts/compiler

Wrap your Next.js configuration with withGTConfig to enable and customize the SWC plugin options.

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

export default withGTConfig(nextConfig, {
  locales: ['en', 'es'],
  swcPluginOptions: {
    logLevel: 'silent',     // Control warning output
    compileTimeHash: false, // Enable hash generation
  },
});
```

--------------------------------

### Run the GT translate command

Source: https://generaltranslation.com/en-US/docs/next/api/config/load-translations

Command to save translations into the project file tree when using local translations.

```bash
npx gt translate
```

--------------------------------

### Configure RTL support in RootLayout

Source: https://generaltranslation.com/en-US/docs/next/guides/rtl

Use useLocale and useLocaleDirection hooks to dynamically set the lang and dir attributes on the HTML element.

```tsx
// app/[locale]/layout.tsx
import { useLocale, useLocaleDirection, GTProvider } from 'gt-next';

export default function RootLayout({ children }) {
  const locale = useLocale(); // e.g. "ar" for Arabic
  const dir = useLocaleDirection(); // e.g. "rtl" for right-to-left

  return (
    <html lang={locale} dir={dir}>
      <body> 
        <GTProvider>
          {children}
        </GTProvider>
      </body>
    </html>
  );
}
```

--------------------------------

### Configure Next.js with withGTConfig

Source: https://generaltranslation.com/en-US/docs/next

Wrap the existing Next.js configuration with the withGTConfig plugin to enable internationalization.

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

const nextConfig = {};

export default withGTConfig(nextConfig);
```

--------------------------------

### Define render settings configuration

Source: https://generaltranslation.com/en-US/docs/next/api/config/with-gt-config

Configuration object defining the rendering method and timeout duration for runtime translations.

```javascript
type: {
    method: {
        description: 'The method used to render the page.',
        type: '"skeleton" | "replace" | "default"',
        optional: false,
        default: "default"
    },
    timeout: {
        description: 'The time in milliseconds before the method times out.',
        type: 'number',
        optional: true,
        default: 8000,
    },
  }
```

--------------------------------

### Implement loadDictionary for manual migration

Source: https://generaltranslation.com/en-US/docs/next/guides/dictionaries

Use this function when migrating existing translation files from other libraries.

```ts
export default async function loadDictionary(locale: string) {
  const translations = await import(`../public/locales/${locale}.json`);
  return translations.default;
}
```

--------------------------------

### Configure Next.js with withGTConfig

Source: https://generaltranslation.com/en-US/docs/next/api/config/with-gt-config

Wrap the Next.js configuration object with withGTConfig in next.config.mjs to enable translation functionality.

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

const nextConfig = {
    // your existing next.config.js
}

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

--------------------------------

### Configure middleware for SSG

Source: https://generaltranslation.com/en-US/docs/next/guides/ssg

Set up the middleware to handle dynamic requests by exporting the middleware created by the GT SDK.

```ts
// proxy.ts (Next.js 16+) or middleware.ts (Next.js 15 and below)
import { createNextMiddleware } from 'gt-next/middleware';

export default createNextMiddleware();

export const config = {
  matcher: ['/((?!api|static|.*\..*|_next).*)'],
};
```

--------------------------------

### Implement Middleware for gt-next

Source: https://generaltranslation.com/en-US/docs/next/guides/cache-components

Set up the Next.js middleware to handle routing and locale detection.

```ts
import { createNextMiddleware } from 'gt-next/middleware';

export default createNextMiddleware();

export const config = {
// Match all paths except API routes, static files, and Next.js internals
matcher: ['/((?!api|static|.*\..*|_next).*)']
};
```

--------------------------------

### Configure Root Layout in Next.js

Source: https://generaltranslation.com/en-US/docs/next/tutorials/examples/currency-converter/setup

Defines the global layout, including Geist font variables and application metadata.

```jsx
import type { Metadata } from "next";
import { Geist, Geist_Mono } from "next/font/google";
import "./globals.css";

const geistSans = Geist({
  variable: "--font-geist-sans",
  subsets: ["latin"],
});

const geistMono = Geist_Mono({
  variable: "--font-geist-mono",
  subsets: ["latin"],
});

export const metadata: Metadata = {
  title: "Currency Converter",
  description: "A simple currency converter",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body
        className={`${geistSans.variable} ${geistMono.variable} antialiased`}
      >
        {children}
      </body>
    </html>
  );
}
```

--------------------------------

### Troubleshoot missing translations

Source: https://generaltranslation.com/en-US/docs/next/guides/local-tx

Ensure the translation generation command precedes the build command.

```bash
# ❌ Build without translations
<...YOUR_BUILD_COMMAND...>

# ✅ Generate translations first
npx gt translate && <...YOUR_BUILD_COMMAND...>
```

--------------------------------

### Customizing DateTime formatting

Source: https://generaltranslation.com/en-US/docs/next/api/components/datetime

Applies custom date and time styles and time zones using the options prop.

```jsx
import { DateTime } from 'gt-next';

export default function EventDate(event) {
    return (
        <DateTime options={{
            dateStyle: 'full', // [!code highlight]
            timeStyle: 'long', // [!code highlight]
            timeZone: 'Australia/Sydney', // [!code highlight]
        }}>
            {event.date}
        </DateTime>.
    );
}
```

--------------------------------

### Handle mixed static and dynamic content

Source: https://generaltranslation.com/en-US/docs/next/guides/dynamic-content

Combine T, Tx, and Var components to manage complex layouts containing both static templates and dynamic user content.

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

async function ProductReview({ review }) {
  return (
    <div>
      {/* Static content with variables */}
      <T>
        <p><Var>{review.author}</Var> rated this <Var>{review.rating}</Var> stars</p>
      </T>
      
      {/* Dynamic user content */}
      <Tx>{review.content}</Tx>
    </div>
  );
}
```

--------------------------------

### Translate with options

Source: https://generaltranslation.com/en-US/docs/next/api/strings/tx

Customizes translation behavior by providing a context string.

```javascript
import { tx } from 'gt-next/server';

export default async function TranslateWithOptions() {
    return await tx("Hello, world!", {
      $context: 'Translate informally' // [!code highlight]
    });
}
```

--------------------------------

### Migrate dictionary usage with useTranslations

Source: https://generaltranslation.com/en-US/docs/next/guides/migration

Demonstrates replacing react-i18next with gt-next while maintaining dictionary-based translation calls.

```tsx
import { useTranslation } from 'react-i18next'
export default function MyComponent() {
  const { t } = useTranslation()
  return <div>{t('hello.description')}</div>
}
```

```tsx
import { useTranslations } from 'gt-next'
export default function MyComponent() {
  const t = useTranslations()
  return <div>{t('hello.description')}</div>
}
```

--------------------------------

### Translate greeting with getGT

Source: https://generaltranslation.com/en-US/docs/next/api/strings/get-gt

Demonstrates basic usage within a server component to translate static strings.

```javascript
import { getGT } from 'gt-next/server';

export default async function TranslateGreeting() {
  const gt = await getGT();

  return (
    <p>
      {gt('Hello, Alice!')}
    </p>
  );
}
```

--------------------------------

### Client-side usage with 'use client'

Source: https://generaltranslation.com/en-US/docs/next/api/strings/use-messages

Import from gt-next when working within a 'use client' directive.

```jsx
'use client';
import { msg, useMessages } from 'gt-next';

const encodedGreeting = msg('Hello, Alice!');

export default function TranslateGreeting() {
  const m = useMessages();

  return <p>{m(encodedGreeting)}</p>;
}
```

--------------------------------

### Basic getTranslations usage

Source: https://generaltranslation.com/en-US/docs/next/api/dictionary/get-translations

Initialize the translation function and retrieve a translation by its key.

```jsx
const d = await getTranslations(); // Get the translation function
d('greeting.hello'); // pass the id to get a translation
```

--------------------------------

### Basic getGT usage

Source: https://generaltranslation.com/en-US/docs/next/api/strings/get-gt

Initializes the translation function and wraps content for build-time translation.

```jsx
const gt = await getGT();

<p>{  gt('This text will be translated')  }</p>;
```

--------------------------------

### Configure Forms with Shared Strings

Source: https://generaltranslation.com/en-US/docs/next/guides/shared-strings

Organize form placeholders, actions, and validation messages in a central configuration file for consistent localization.

```tsx
// config/forms.ts
import { msg } from 'gt-next';

export const formMessages = {
  placeholders: {
    email: msg('Enter your email address'),
    password: msg('Enter your password'),
    message: msg('Type your message here...')
  },
  actions: {
    send: msg('Send Message'),
    save: msg('Save Changes'),
    cancel: msg('Cancel')
  },
  validation: {
    required: msg('This field is required'),
    email: msg('Please enter a valid email address'),
    minLength: msg('Must be at least {min} characters', { min: 8 }),
    maxLength: msg('Cannot exceed {max} characters', { max: 100 })
  },
  success: {
    saved: msg('Changes saved successfully'),
    sent: msg('Message sent successfully'),
    updated: msg('Profile updated')
  },
  errors: {
    network: msg('Network error - please try again'),
    server: msg('Server error - please contact support'),
    timeout: msg('Request timed out - please try again')
  }
};
```

```tsx
// components/ContactForm.tsx
import { useMessages } from 'gt-next';
import { formMessages } from '../config/forms';

function ContactForm() {
  const m = useMessages();
  const [errors, setErrors] = useState({});
  
  return (
    <form>
      <input 
        type="email"
        placeholder={m(formMessages.placeholders.email)}
        required
      />
      {errors.email && <span>{m(formMessages.validation.email)}</span>}
      
      <button type="submit">
        {m(formMessages.actions.send)}
      </button>
    </form>
  );
}
```

--------------------------------

### Retrieve user locale in server components

Source: https://generaltranslation.com/en-US/docs/next/api/helpers/get-locale

Demonstrates how to import and await the getLocale function within an asynchronous server component.

```javascript
import { getLocale } from 'gt-next/server';

export default async function GetUserLocale() {
  const locale = await getLocale(); // [!code highlight]
  return <p>User locale: {locale}</p>;
}
```

--------------------------------

### Render Settings Configuration

Source: https://generaltranslation.com/en-US/docs/next/api/config/with-gt-config

Configuration options for controlling translation rendering behavior during runtime.

```APIDOC
## Render Settings Configuration

### Description
Controls the behavior of translations while they are loading at runtime. These settings apply to non-cached translations.

### Configuration Options
- **method** (string) - Required - The method used to render the page. Options: `skeleton`, `replace`, `default`. Default: `default`.
- **timeout** (number) - Optional - The time in milliseconds before the method times out. Default: `8000`.

### Render Methods
- `skeleton`: Renders a fragment.
- `replace`: Renders content in the default language while waiting.
- `default`: Behaves like `replace` for same-language locales and `skeleton` for different-language locales.
```

--------------------------------

### Basic usage of Tx component

Source: https://generaltranslation.com/en-US/docs/next/api/components/tx

Translates static children content at runtime.

```jsx
import { Tx } from 'gt-next/server';

export default function Greeting() {
    return (
        {/* [!code highlight] */}
        <Tx>
            Hello, world!
        </Tx> // [!code highlight]
    );
}
```

--------------------------------

### Translate dynamic content at runtime

Source: https://generaltranslation.com/en-US/docs/next/tutorials/translating-strings

Use the tx function for strings that change at runtime. This function is server-side only and should be used sparingly due to potential performance delays.

```jsx
import { tx } from 'gt-next/server';

export default async function MyComponent({ username }) {
  const translation = await tx(`Hello, ${username}. How is your day?`); // [!code highlight]
  return (
    <div>
      <h1>{translation}</h1> // [!code highlight]
    </div>
  );
}
```

--------------------------------

### Use useGT in client components

Source: https://generaltranslation.com/en-US/docs/next/api/strings/use-gt

Required import pattern when using the 'use client' directive.

```jsx
'use client';
import { useGT } from 'gt-next';

export default function TranslateGreeting() {
  const gt = useGT();

  return <p>{gt('Hello, Alice!')}</p>;
}
```

--------------------------------

### Configure Next.js for Cache Components

Source: https://generaltranslation.com/en-US/docs/next/guides/cache-components

Enable cache components in next.config.js and specify paths for custom locale and region resolution functions.

```js
const nextConfig = {
  cacheComponents: true,
};

export default withGTConfig(nextConfig, {
  // Point to your custom request functions
  getLocalePath: './getLocale.ts',
  getRegionPath: './getRegion.ts',
});
```

--------------------------------

### Specify project locales

Source: https://generaltranslation.com/en-US/docs/next/api/config/gt-config-json

Sets the default fallback locale and the list of supported secondary locales.

```json
{
  "defaultLocale": "en", // Primary locale is English
  "locales": ["fr", "es"] // Secondary locales are French and Spanish
}
```

--------------------------------

### Apply custom currency formatting

Source: https://generaltranslation.com/en-US/docs/next/api/components/currency

Use the options prop to pass Intl.NumberFormatOptions for fine-grained control over decimal places and symbol display.

```jsx
import { Currency } from 'gt-next';

export default function PriceDisplay(item) {
  return (
    <Currency
      currency="GBP"
      options={{ // [!code highlight]
        currencyDisplay: 'narrowSymbol', // [!code highlight]
        minimumFractionDigits: 2, // [!code highlight]
        maximumFractionDigits: 2, // [!code highlight]
      }} // [!code highlight]
    >
      {item.price}
    </Currency>
  );
}
```

--------------------------------

### Basic tx usage

Source: https://generaltranslation.com/en-US/docs/next/api/strings/tx

Translates a string at runtime using the tx function.

```jsx
await tx('Hello, world!'); // returns 'Hola, mundo!'
```

--------------------------------

### Translate plain strings with tx

Source: https://generaltranslation.com/en-US/docs/next/guides/dynamic-content

Use the asynchronous tx function to translate plain strings on the server before rendering.

```jsx
import { tx } from 'gt-next/server';

async function NotificationBanner({ message }) {
  const translatedMessage = await tx(message);
  
  return (
    <div className="banner">
      {translatedMessage}
    </div>
  );
}
```

--------------------------------

### Encoding and Decoding Shared Strings

Source: https://generaltranslation.com/en-US/docs/next/guides/shared-strings

Demonstrates the basic workflow of encoding a string with metadata and decoding it for translation.

```tsx
// msg() encodes the string with metadata
const encoded = msg('Hello, world!');
console.log(encoded); // "Hello, world!:eyIkX2hhc2giOiJkMjA3MDliZGExNjNlZmM2In0="

// useMessages() decodes and translates
const m = useMessages();
const translated = m(encoded); // "Hello, world!" in user's language
```

--------------------------------

### Identify DYNAMIC_SERVER_USAGE error

Source: https://generaltranslation.com/en-US/docs/next/guides/ssg

This error appears in production logs when locale or region detection files are missing or misconfigured.

```text
⨯ [Error: An error occurred in the Server Components render. The specific message is omitted in production builds to avoid leaking sensitive details. A digest property is included on this error instance which may provide additional details about the nature of the error.] {
  digest: 'DYNAMIC_SERVER_USAGE'
}
```

--------------------------------

### Configure Navigation with Shared Strings

Source: https://generaltranslation.com/en-US/docs/next/guides/shared-strings

Define navigation items and footer links using the msg function to ensure all labels are translatable.

```tsx
// config/navigation.ts
import { msg } from 'gt-next';

export const mainNav = [
  {
    label: msg('Home'),
    href: '/',
    icon: 'home'
  },
  {
    label: msg('Products'),
    href: '/products', 
    icon: 'package'
  },
  {
    label: msg('About Us'),
    href: '/about',
    icon: 'info'
  }
];

export const footerLinks = [
  {
    title: msg('Company'),
    links: [
      { label: msg('About'), href: '/about' },
      { label: msg('Careers'), href: '/careers' },
      { label: msg('Contact'), href: '/contact' }
    ]
  },
  {
    title: msg('Support'), 
    links: [
      { label: msg('Help Center'), href: '/help' },
      { label: msg('Documentation'), href: '/docs' },
      { label: msg('API Reference'), href: '/api' }
    ]
  }
];
```

```tsx
// components/Navigation.tsx
import { useMessages } from 'gt-next';
import { mainNav } from '../config/navigation';

function Navigation() {
  const m = useMessages();
  
  return (
    <nav>
      {mainNav.map((item) => (
        <a key={item.href} href={item.href}>
          <Icon name={item.icon} />
          {m(item.label)}
        </a>
      ))}
    </nav>
  );
}
```

--------------------------------

### Configure withGTConfig in next.config.mjs

Source: https://generaltranslation.com/en-US/docs/next/api/config/with-gt-config

Wraps the Next.js configuration with withGTConfig to enable translation features and custom render settings.

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

const nextConfig = {
  // Your other Next.js configurations
};

export default withGTConfig(nextConfig, {
  renderSettings: {
    method: 'skeleton',
    timeout: 10000,
  },
});
```

--------------------------------

### Wrap the application with GTProvider

Source: https://generaltranslation.com/en-US/docs/next

The GTProvider must wrap the root layout to provide translation context to the entire application.

```tsx
import { GTProvider } from 'gt-next';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <GTProvider>
          {children}
        </GTProvider>
      </body>
    </html>
  );
}
```

--------------------------------

### Configure custom paths for locale and region files

Source: https://generaltranslation.com/en-US/docs/next/guides/ssg

Specify custom locations for getLocale.ts and getRegion.ts in your next.config.js file.

```js
// next.config.js
export default withGTConfig(nextConfig, {
  getLocalePath: './src/i18n/getLocale.ts',
  getRegionPath: './src/i18n/getRegion.ts',
});
```

--------------------------------

### Static vs Dynamic content usage

Source: https://generaltranslation.com/en-US/docs/next/guides/t

T is strictly for static content. Use Variable components to handle dynamic data within T.

```jsx
// ✅ Static content works
<T>
  <button>Click here</button>
  <h1>Welcome to our site</h1>
</T>

// ❌ Dynamic content breaks
<T>
  <p>Hello {username}</p>
  <p>Today is {new Date()}</p>
</T>

// ✅ Use Variable components for dynamic content
<T>
  <p>Hello <Var>{username}</Var></p>
</T>
```

--------------------------------

### Handling Dynamic Content in Translations

Source: https://generaltranslation.com/en-US/docs/next/guides/strings

Strings must be defined at build time. Use a lookup object for dynamic selection instead of passing variables directly to the translation function.

```jsx
// ❌ Dynamic content won't work
function MyComponent() {
  const [userMessage, setUserMessage] = useState('');
  const gt = useGT();
  
  return <p>{gt(userMessage)}</p>; // This will fail
}

// ✅ Use predefined strings
function MyComponent() {
  const [messageType, setMessageType] = useState('welcome');
  const gt = useGT();
  
  const messages = {
    welcome: gt('Welcome to our app!'),
    goodbye: gt('Thanks for visiting!')
  };
  
  return <p>{messages[messageType]}</p>;
}
```

--------------------------------

### Using variables for localized formatting

Source: https://generaltranslation.com/en-US/docs/next/guides/t

Integrate Var, Num, DateTime, and Currency components within T for dynamic values.

```jsx
// Combining static text with dynamic values
<T>
  <p>Welcome back, <Var>{user.name}</Var>!</p>
  <p>You have <Num>{user.friends.length}</Num> friends online</p>
  <p>Your birthday is <DateTime>{user.birthday}</DateTime></p>
  <p>Your balance is <Currency>{user.balance}</Currency></p>
</T>
```

--------------------------------

### Define dictionary with variables

Source: https://generaltranslation.com/en-US/docs/next/api/dictionary/get-translations

Define a translation string containing a variable placeholder.

```jsx
// [!code word:userName]
const dictionary = {
  greeting: "Hello, {userName}!", // [!code highlight]
};
export default dictionary;
```

--------------------------------

### Translate greeting

Source: https://generaltranslation.com/en-US/docs/next/api/strings/tx

Basic implementation of the tx function within an asynchronous server component.

```javascript
import { tx } from 'gt-next/server';

export default async function translateGreeting() {
    return await tx("Hello, world!"); // [!code highlight]
}
```

--------------------------------

### Define nested dictionary prefixes

Source: https://generaltranslation.com/en-US/docs/next/api/dictionary/get-translations

Structure the dictionary with nested objects to create key prefixes.

```jsx
const dictionary = {
  prefix1: { // [!code highlight]
    prefix2: { // [!code highlight]
      greeting: "Hello, Bob",
    }
  }
};
export default dictionary;
```

--------------------------------

### Optimize bundle size

Source: https://generaltranslation.com/en-US/docs/next/guides/local-tx

Implement conditional loading to reduce bundle size by only importing active locale files.

```ts
// Load translations only when needed
export default async function loadTranslations(locale: string) {
  // Only load if locale is active
  if (locale === getCurrentLocale()) {
    const translations = await import(`../public/_gt/${locale}.json`);
    return translations.default;
  }
  return {};
}
```

--------------------------------

### Modify Root Layout for Localization

Source: https://generaltranslation.com/en-US/docs/next/tutorials/examples/next-speedrun

Integrates GTProvider and dynamic locale detection into the Next.js root layout.

```javascript
import { GTProvider } from "gt-next"; // [!code highlight]
import { getLocale } from "gt-next/server"; // [!code highlight]
...
export default async function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  const locale = await getLocale(); // [!code highlight]
  return (
    <html lang={locale}> // [!code highlight]
      <GTProvider>
        <body
          className={`${geistSans.variable} ${geistMono.variable} antialiased`}
        >
        {children}
        </body>
      </GTProvider>
    </html>
  );
}
```
Tokens:
Raw