Překlad aplikace využívající Next.js App Router

Zpřístupněte každou stránku s předponou jazyka v URL, přesměrujte cesty bez předpony a vykreslujte přeložené serverové i klientské komponenty pomocí @lingo.dev/react-next.

V App Routeru má každý jazyk vlastní předponu URL, a to včetně zdrojového jazyka: návštěvníci tedy přicházejí na /en/pricing a /de/pricing. @lingo.dev/react-next zjistí jazyk ze segmentu trasy app/[locale], na serveru načte katalog daného jazyka a poskytne serverovým i klientským komponentám stejné texty. V tomto návodu přidáte do anglické aplikace němčinu a francouzštinu.

Použijte Next.js 16 nebo novější s Reactem 19; vstupní body zjišťují jazyk prostřednictvím next/root-params. Nainstalujte balíčky:

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

Definujte jazyky #

Vytvořte i18n.ts vedle app/ (src/i18n.ts, pokud aplikace používá 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);

V .lingo/config.json uveďte seznam jazyků a zdrojový jazyk nastavte jako defaultLocale. exclude určuje první segmenty cest, ke kterým se předpona nepřidává, například obslužné rutiny tras pod app/api/. Nepředávejte slugs: segment URL každého jazyka musí odpovídat jeho značce zapsané malými písmeny (/pt-br pro pt-BR), protože getLingo() odvozuje jazyk pouze z tohoto segmentu. Při použití vlastního slugu poskytovatel vyvolá chybu, ve které daný slug uvede. Tento soubor importují proxy i serverové a klientské komponenty, proto do něj nepřidávejte žádné další importy.

Přesměrujte cesty bez předpony #

Vytvořte proxy.ts vedle 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) zpracovává dva druhy požadavků:

PožadavekOdpověď
První segment označující jazyk jinak než jeho slugem, například /DE/about, /de-AT nebo /de_DE301 na kanonickou adresu.
Lokalizovaná cesta bez předpony jazyka, například /about307 na jazyk zvolený podle Accept-Language, s Cache-Control: private, no-store a Vary: Accept-Language.
Cokoli jinéhoundefined.

Přesměrování zachovávají řetězec dotazu i basePath aplikace. Next.js načítá matcher při sestavení, proto jej zapisujte jako literál a udržujte jeho api v souladu s exclude. Pokud už aplikace proxy má, zavolejte nejprve lingoProxy. Pokud vrátí undefined, pokračujte vlastní logikou. middleware.ts je tentýž soubor pod původním názvem; přejmenujte jej na proxy.ts a jeho funkci na proxy.

Přesuňte trasy pod segment jazyka #

Přesuňte kořenový layout a všechny stránky o jednu složku níže, do app/[locale]/. app/[locale]/layout.tsx se stane kořenovým layoutem a app/layout.tsx už nebude existovat. Obslužné rutiny tras pod app/api/, globals.css, ikony, robots.ts a sitemap.ts zůstanou na svém místě. Z next.config odstraňte případný klíč i18n; App Router jej nečte.

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 vrací pro každý jazyk jedno { locale }, takže se při sestavení každá stránka předvykreslí jednou pro každý jazyk. LingoAppProvider vrátí pro jazyk, který není v seznamu, chybu 404. Nepřidávejte export const dynamicParams = false: Next.js jej při zapnutém cacheComponents odmítne.

Přeložte serverové a klientské komponenty #

Serverové komponenty, stránky, layouty a generateMetadata volají await getLingo() z @lingo.dev/react-next/app/server. Klientské komponenty volají useLingo() z @lingo.dev/react; jazyk a katalog jim poskytuje LingoAppProvider. V žádném z těchto případů není nutné jazyk předávat z nadřazených komponent.

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>;
}

Serverová komponenta může od své nadřazené serverové komponenty přijmout l jako vlastnost, ale l nikdy nepředávejte klientské komponentě: funkce nelze přenášet ze serveru na klienta. Volání getLingo() mimo app/[locale]/ vyvolá chybu, protože nenajde segment [locale].

Přidejte 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? }) vrací alternates.canonical, alternates.languages pro každý jazyk spolu s x-default a dále openGraph.url a openGraph.locale. Předejte cestu stránky bez předpony jazyka, řetězce dotazu a fragmentu; u dynamické trasy ji sestavte z jejích parametrů. Ukázkový origin nahraďte originem svého webu. V části Pravidla URL pro jazyky najdete vysvětlení lingoHead, které tyto hodnoty sestavuje, i možnosti přepsání pomocí ogLocale.

Ke každému internímu odkazu přidejte předponu pomocí localePath("/pricing", l.locale) z i18n.ts. l.locale je běžný řetězec, proto jej localePath nejprve zúží na jeden z jazyků routeru a teprve poté locales.prefix přidá předponu. Odkaz bez předpony zpracuje proxy, která přesměruje na jazyk prohlížeče, nikoli na jazyk stránky. Totéž platí pro redirect(), router.push() a akce formulářů, které odkazují na cestu.

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) vrací pro každý jazyk jedno { locale, label, href, current }: aktuální stránku v daném jazyce, název jazyka v jeho vlastním znění a informaci, zda jde o aktuální jazyk. Řetězec dotazu se přidává až po hydrataci, takže stránka, která vykresluje přepínač, zůstává statická. Přechod přes odkaz znovu vykreslí layout, který načte katalog nového jazyka.

Extrahujte a načtěte katalogy #

Server pomocí fs načítá locales/<locale>.jsonc ze složky, ze které se spouští next, proto ponechte i18n.messagesPath na výchozí hodnotě locales. Vynechává osiřelé položky a při každém požadavku čte soubor znovu, takže next dev poskytne upravený katalog hned při následujícím požadavku. Pokud soubor chybí, výsledkem je prázdný katalog a ve vývojovém prostředí se zobrazí upozornění. Chybný formát souboru nebo hodnota, která není řetězcem, vyvolá chybu s názvem souboru. V produkčním prostředí se pro zdrojový jazyk do prohlížeče žádný katalog neposílá, protože jeho text slouží jako záložní varianta.

Pokud je app/ v kořenové složce projektu a projekt nemá složku src/, nastavte v .lingo/config.json hodnotu "i18n": { "src": "." }, aby extrakce procházela app/ a components/. Extrakce přeskakuje node_modules a složky začínající tečkou, například .next. Pro novou konfiguraci:

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

Nastavte i18n.src až po init, které přepisuje sekci i18n. V monorepu je .lingo/config.json v kořenové složce repozitáře a cesty se odvozují od ní, takže messagesPath tvoří cesta ke složce aplikace doplněná o locales, například apps/web/locales; viz mapa pojmenovaných aplikací i18n v části Konfigurace CLI. Server přitom stále načítá locales/ ze složky samotné aplikace.

Po next build a next start otevřete / a ověřte, že dojde k přesměrování na cestu s předponou jazyka. Poté otevřete /de a zkontrolujte německý text v HTML.

Běhové prostředí #

Předvykreslené stránky fungují na libovolném hostingu. Stránka vykreslovaná na vyžádání načítá katalog z disku, a proto potřebuje běhové prostředí Node.js; Cloudflare Workers ani běhové prostředí Edge jej načíst nemohou.

Exporty #

Vstupní bodExporty
@lingo.dev/react-next/app/servergetLingo(), LingoAppProvider, lingoMetadata(options), lingoStaticParams(locales).
@lingo.dev/react-next/app/clientuseLocaleSwitch(locales) a typ LocaleOption.
@lingo.dev/react-next/app/proxylingoProxy(locales).

Po instalaci balíčku mohou programovací agenti postupovat podle lingo agent-guide react-next-app a při migraci z next-intl podle lingo agent-guide react-next-migrate. Viz Nastavení pomocí programovacího agenta.