Translate a Next.js App Router application

Serve every page under a locale prefix, redirect bare paths, and render translated server and client components with @lingo.dev/react-next.

In the App Router, every locale has its own URL prefix, the source locale included: readers visit /en/pricing and /de/pricing. @lingo.dev/react-next reads the locale from an app/[locale] route segment, loads that locale's catalog on the server, and gives server and client components the same messages. This recipe adds German and French to an English application.

Use Next.js 16 or later with React 19; the entries read the locale through next/root-params. Install the packages:

sh
npm install @lingo.dev/react@1.22.0 @lingo.dev/react-next@1.22.0 @lingo.dev/locale-router@0.3.0
npm install --save-dev @lingo.dev/cli@latest

Define the locales #

Create i18n.ts next to app/ (src/i18n.ts when the application uses src/):

ts
import { createLocaleRouter } from "@lingo.dev/locale-router";

export const locales = createLocaleRouter(["en", "de", "fr"] as const, { defaultLocale: "en", exclude: ["api"] });

export const localePath = (pathname: string, locale: string) =>
  locales.prefix(pathname, locales.toLocale(locale) ?? locales.defaultLocale);

List the locales of .lingo/config.json, with the source locale as defaultLocale. exclude names first path segments that get no prefix, such as route handlers under app/api/. Do not pass slugs: each locale's URL segment must be its tag in lowercase (/pt-br for pt-BR), because getLingo() derives the locale from the segment alone. A custom slug makes the provider throw an error that names it. The proxy, server components and client components all import this file, so keep other imports out of it.

Redirect bare paths #

Create proxy.ts next to app/:

ts
import { lingoProxy } from "@lingo.dev/react-next/app/proxy";
import { locales } from "./i18n";

export const proxy = lingoProxy(locales);

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

lingoProxy(locales) answers two kinds of request:

RequestResponse
A first segment that names a locale by something other than its slug, such as /DE/about, /de-AT or /de_DE301 to the canonical address.
A localized path without a locale, such as /about307 to the locale negotiated from Accept-Language, with Cache-Control: private, no-store and Vary: Accept-Language.
Anything elseundefined.

Redirects keep the query string and the application's basePath. Next.js reads the matcher at build time, so keep it a literal and keep its api in step with exclude. When the application already has a proxy, call lingoProxy first and continue with your own logic when it returns undefined. A middleware.ts is the same file under its old name; rename it to proxy.ts and its function to proxy.

Move the routes under the locale #

Move the root layout and every page one folder down, into app/[locale]/. app/[locale]/layout.tsx becomes the root layout, and there is no app/layout.tsx afterwards. Route handlers under app/api/, globals.css, icons, robots.ts and sitemap.ts stay where they are. Remove any i18n key from next.config; the App Router does not read it.

tsx
// app/[locale]/layout.tsx
import type { ReactNode } from "react";
import { getLingo, LingoAppProvider, lingoStaticParams } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";
import "../globals.css";

export function generateStaticParams() {
  return lingoStaticParams(locales);
}

export default async function RootLayout({ children }: { children: ReactNode }) {
  const l = await getLingo();
  return (
    <html lang={l.locale} dir={l.direction}>
      <body>
        <LingoAppProvider locales={locales}>{children}</LingoAppProvider>
      </body>
    </html>
  );
}

lingoStaticParams returns one { locale } per locale, so the build prerenders every page once per locale. LingoAppProvider answers a locale outside the list with a 404. Do not add export const dynamicParams = false: Next.js rejects it when cacheComponents is on.

Translate server and client components #

Server components, pages, layouts and generateMetadata call await getLingo() from @lingo.dev/react-next/app/server. Client components call useLingo() from @lingo.dev/react; LingoAppProvider supplies their locale and catalog. Neither needs the locale passed down.

tsx
// app/[locale]/page.tsx
import { getLingo } from "@lingo.dev/react-next/app/server";

export default async function Home() {
  const l = await getLingo();
  return <h1>{l.text("Welcome", { context: "Heading of the start page" })}</h1>;
}

A server component may receive l as a prop from its server parent, but never pass l to a client component: functions do not cross from the server to the client. getLingo() called outside app/[locale]/ throws, because it finds no [locale] segment.

Add metadata #

tsx
import { getLingo, lingoMetadata } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";

export async function generateMetadata() {
  const l = await getLingo();
  return {
    title: l.text("Pricing", { context: "Title of the pricing page" }),
    ...(await lingoMetadata({ locales, pathname: "/pricing", origin: "https://example.com" })),
  };
}

lingoMetadata({ locales, pathname, origin, ogLocale? }) returns alternates.canonical, alternates.languages with every locale plus x-default, and openGraph.url and openGraph.locale. Pass the page's path without the locale prefix, query or hash; a dynamic route builds it from its params. Replace the example origin with your site's origin. Locale URL policy explains lingoHead, which builds the values, and the ogLocale override.

Give every internal link its prefix with localePath("/pricing", l.locale) from i18n.ts. l.locale is a plain string, so localePath narrows it to one of the router's locales before locales.prefix adds the prefix. A link without one reaches the proxy, which redirects to the browser's language instead of the page's. The same applies to redirect(), router.push() and form actions that name a path.

tsx
"use client";

import Link from "next/link";
import { useLocaleSwitch } from "@lingo.dev/react-next/app/client";
import { locales } from "@/i18n";

export function LocaleSwitcher() {
  const options = useLocaleSwitch(locales);
  return (
    <nav aria-label="Language">
      {options.map((option) => (
        <Link key={option.locale} href={option.href} hrefLang={option.locale} aria-current={option.current ? "page" : undefined}>
          {option.label}
        </Link>
      ))}
    </nav>
  );
}

useLocaleSwitch(locales) returns one { locale, label, href, current } per locale: the current page in that locale, the language's name in itself, and whether it is the current one. The query string is added after hydration, so a page that renders the switcher stays static. Following a link re-renders the layout, which loads the new locale's catalog.

Extract and load the catalogs #

The server reads locales/<locale>.jsonc from the folder next runs from, using fs, so keep i18n.messagesPath at its default locales. It drops orphaned entries and reads the file again on each request, so next dev serves an edited catalog on the next request. A missing file gives an empty catalog, with a warning in development; a malformed file, or a value that is not a string, throws an error that names the file. In production the source locale sends no catalog to the browser, because its text is the fallback.

When app/ sits at the project root, without a src/ folder, set "i18n": { "src": "." } in .lingo/config.json so extraction scans app/ and components/. Extraction skips node_modules and dot folders such as .next. For a new configuration:

sh
npx lingo init --source en --targets de,fr --files 'locales/en.jsonc' --yes
npx lingo extract --src .
npx lingo login
npx lingo link
npx lingo push --backfill-missing --wait

Set i18n.src after init, which rewrites the i18n section. In a monorepo, .lingo/config.json sits at the repository root and its paths start there, so messagesPath is the app folder plus locales, such as apps/web/locales; see the i18n map of named apps in CLI configuration. The server still reads locales/ in the app's own folder.

After next build and next start, open / and check that it redirects to a locale, then open /de and check the German text in the HTML.

Runtime #

Prerendered pages work on any host. A page rendered on demand reads its catalog from disk, so it needs the Node.js runtime; Cloudflare Workers and the Edge runtime cannot read it.

Exports #

EntryExports
@lingo.dev/react-next/app/servergetLingo(), LingoAppProvider, lingoMetadata(options), lingoStaticParams(locales).
@lingo.dev/react-next/app/clientuseLocaleSwitch(locales) and the LocaleOption type.
@lingo.dev/react-next/app/proxylingoProxy(locales).

Coding agents can follow lingo agent-guide react-next-app once the package is installed, and lingo agent-guide react-next-migrate to move from next-intl. See Set up with a coding agent.