Overview

Static Site Generation (SSG) pre-renders pages at build time, creating static HTML files that can be served directly without server-side processing. When combined with internationalization, SSG generates pre-rendered versions for each locale.

Setup

Setup Requirements

To enable SSG with GT, you need:

1. App Router with middleware routing - see middleware guide
2. Custom getLocale function - for locale detection during static rendering
3. Disable getRegion - region detection is not supported during static rendering
4. generateStaticParams function - for generating static parameters for each locale

Step 1: Configure Middleware

Set up middleware for dynamic requests (see middleware guide):

// 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).*)",
  ],
}

Step 2: Define Locale and Region Detection

Create a getLocale and getRegion function for locale and region detection during static rendering:

Next.js 15.5+

// getLocale.ts
import { locale } from "next/root-params";

export default async function getLocale() {
  return await locale();
}

Next.js 15.1-15.4

// getLocale.ts  
import { unstable_rootParams } from "next/server";

export default async function getLocale() {
  return (await unstable_rootParams())?.locale;
}

Step 3: Disable getRegion

Since region detection is not supported during static rendering, you need to overwrite the getRegion function to return a fixed region.

// getRegion.ts
export default async function getRegion() {
  return undefined;
}

Step 4: Configure generateStaticParams

Make sure you have generateStaticParams configured for your locales.

import { getLocales } from 'gt-next/server';

export async function generateStaticParams() {
  return getLocales().map((locale) => ({ locale }));
}

export default async function Page() {
  ...
}

Additional Configuration

If you do not want getLocale.ts and getRegion.ts in your root directory, you can specify a custom directory in your next.config.js file.

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

Common Issues

Next.js version compatibility

For versions earlier than Next.js 15.1, there is no way to access URL path parameters during static generation. You will need to upgrade to Next.js 15.1 or later to use SSG with gt-next.

Pages Not Generating Statically

If your pages aren't being statically generated, ensure that:

• Your getLocale and getRegion functions are properly configured

Layout/Page outside of the [locale] directory

If you have a layout.tsx or page.tsx file outside of the [locale] directory, it will prevent static generation. You will likely see the following error:

The export locale was not found in module [next]/root-params.js [app-rsc] (ecmascript).
All exports of the module are statically known (It doesn't have dynamic exports). So it's known statically that the requested export doesn't exist.

All layout.tsx files must be inside the [locale] directory. For more information, see this related Next.js issue.

Further Reading

• Check out the middleware guide required for locale routing
• Check out the release notes for migrating from legacy SSG pattern