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:
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@latestDefinujte jazyky #
Vytvořte i18n.ts vedle app/ (src/i18n.ts, pokud aplikace používá src/):
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/:
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žadavek | Odpověď |
|---|---|
První segment označující jazyk jinak než jeho slugem, například /DE/about, /de-AT nebo /de_DE | 301 na kanonickou adresu. |
Lokalizovaná cesta bez předpony jazyka, například /about | 307 na jazyk zvolený podle Accept-Language, s Cache-Control: private, no-store a Vary: Accept-Language. |
| Cokoli jiného | undefined. |
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.
// 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.
// 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 #
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.
Přidejte odkazy a přepínání jazyků #
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.
"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:
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 --waitNastavte 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í bod | Exporty |
|---|---|
@lingo.dev/react-next/app/server | getLingo(), LingoAppProvider, lingoMetadata(options), lingoStaticParams(locales). |
@lingo.dev/react-next/app/client | useLocaleSwitch(locales) a typ LocaleOption. |
@lingo.dev/react-next/app/proxy | lingoProxy(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.