Static Site Generation
Pre-render internationalized pages at build time for optimal performance
Static Site Generation pre-renders pages at build time, creating static HTML files for each locale. This provides excellent performance and SEO benefits while ensuring all translation content is available immediately when users visit your site.
Requirements: SSG requires middleware routing and local translations to work properly with internationalization.
App Router
Setup Requirements
To enable SSG with GT, you need:
- App Router with middleware routing - see middleware guide
- Local translations - see local translations guide
- Client-side imports - use
gt-next/clientinstead ofgt-next
Step 1: GTProvider Configuration
Place GTProvider in your [locale] layout with the loadTranslations function:
// app/[locale]/layout.tsx
import { GTProvider } from 'gt-next/client';
import { loadTranslations } from '@/loadTranslations';
export default async function RootLayout({ children, params }) {
const { locale } = await params;
return (
<GTProvider loadTranslations={loadTranslations} locale={locale}>
{children}
</GTProvider>
);
}Step 2: Use Client Imports
Import all GT components and hooks from gt-next/client:
// ✅ Use client imports for SSG
import { useGT, T } from 'gt-next/client';
// ❌ These prevent SSG
import { getGT } from 'gt-next/server';
import { T } from 'gt-next';Step 3: Configure generateStaticParams
Make sure you have generateStaticParams configured for your locales.
Custom getLocale
For SSG, create a custom getLocale function that works with static generation:
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;
}Earlier Versions
Unfortunately, for earlier versions there is no way to access the URL path parameters with SSG. You will have to upgrade to Next.js 15.1 or later.
Common Issues
Pages Not Generating Statically
If your pages aren't being statically generated, check that all GT components and hooks import from gt-next/client:
// ❌ These prevent SSG
import { getGT } from 'gt-next/server';
import { getLocale } from 'gt-next/server';
import { getTranslations } from 'gt-next/server';
import { T } from 'gt-next';
// ✅ These work with SSG
import { useGT, T } from 'gt-next/client';Anything that reads headers or cookies will prevent static generation.
Next Steps
- Local Translation Storage - Required for SSG setup
- Middleware Guide - Required for locale routing
How is this guide?