Next.js

Use @better-translate/nextjs when you want locale-prefixed URLs, server-side translations, and locale-aware navigation in App Router.

If you also need client-side hooks, add @better-translate/react on top of this setup.

1. Install the packages

npm install @better-translate/core @better-translate/nextjs

2. Create the translator

Create src/lib/i18n/config.ts:

import { configureTranslations } from "@better-translate/core";

const en = {
  home: {
    title: "Hello from Next.js",
  },
} as const;

const es = {
  home: {
    title: "Hola desde Next.js",
  },
} as const;

export const translator = await configureTranslations({
  availableLocales: ["en", "es"] as const,
  defaultLocale: "en",
  fallbackLocale: "en",
  messages: { en, es },
});

3. Add the routing file

Create src/lib/i18n/routing.ts:

import {
  defineRouting,
  SUPPORTED_NEXTJS_LOCALE_ROUTE_SYNTAXES,
} from "@better-translate/nextjs";

export const routing = defineRouting({
  defaultLocale: "en",
  locales: ["en", "es"] as const,
  routeTemplate: "/[lang]",
});

console.log(SUPPORTED_NEXTJS_LOCALE_ROUTE_SYNTAXES);

4. Add the request and server helpers

Better Translate restricts the locale param name to the shared supported list from core. Valid examples include [locale], [lang], [language], [intl], [i18n], [l10n], and [localization].

Create src/lib/i18n/request.ts:

import { getRequestConfig } from "@better-translate/nextjs/server";

import { translator } from "./config";

export const requestConfig = getRequestConfig(async () => ({
  translator,
}));

Create src/lib/i18n/server.ts:

import { createServerHelpers } from "@better-translate/nextjs/server";

import { requestConfig } from "./request";

export const { getTranslations } = createServerHelpers(requestConfig);

5. Add locale-aware navigation

Create src/lib/i18n/navigation.ts:

"use client";

import Link from "next/link";
import { useParams, usePathname, useRouter } from "next/navigation";

import { createNavigationFunctions } from "@better-translate/nextjs/navigation";

import { routing } from "./routing";

export const {
  Link: I18nLink,
  usePathname: useI18nPathname,
  useRouter: useI18nRouter,
} = createNavigationFunctions({
  Link,
  routing,
  useParams,
  usePathname,
  useRouter,
});

6. Add the proxy

Create src/proxy.ts:

import { createProxy, getProxyMatcher } from "@better-translate/nextjs/proxy";

import { routing } from "./lib/i18n/routing";

export const proxy = createProxy(routing);

export const config = {
  matcher: getProxyMatcher(routing),
};

7. Render a translated page

Create src/app/[lang]/page.tsx:

import { setRequestLocale } from "@better-translate/nextjs/server";

import { getTranslations } from "../../lib/i18n/server";

export default async function HomePage({
  params,
}: {
  params: Promise<{ lang: string }>;
}) {
  const { lang } = await params;

  setRequestLocale(lang);

  const t = await getTranslations();

  return <h1>{t("home.title")}</h1>;
}

8. Add links that keep the locale

Create src/components/language-links.tsx:

"use client";

import { I18nLink } from "../lib/i18n/navigation";

export function LanguageLinks() {
  return (
    <nav>
      <I18nLink href="/" locale="en">
        English
      </I18nLink>
      {" | "}
      <I18nLink href="/" locale="es">
        Espanol
      </I18nLink>
    </nav>
  );
}

When to add the React adapter

Add @better-translate/react only when client components need useTranslations() or a provider.

Generate locale files automatically

Instead of writing every translation by hand, use the CLI to extract strings and generate locale files: CLI guide

Examples

• nextjs-example
• nextjs-nested-locale-example