Přeložte aplikaci s Next.js Pages
Načtěte přeložené zprávy stránky, vykreslete je pomocí obalové komponenty Pages a přidejte přepínání jazyků a alternativní odkazy.
Trasa Next.js Pages už určuje jazyk příchozího požadavku. @lingo.dev/react-next podle něj poskytuje zprávy pro React, takže data stránky a přeložený text zůstávají pohromadě. Tento postup vykreslí stránku O nás v angličtině a francouzštině a zachová výběr trasy i v případě, že přeložený soubor JSONC přišel o metadata.
Použijte stávající aplikaci Pages s Reactem 19. Balíček deklaruje Next.js 13+ a React 18/19 jako partnerské závislosti, ale aktuální poskytovatel používaný za běhu využívá zkrácený zápis kontextu z Reactu 19. Exportuje /pages, /pages/client a /pages/server; nemá kořenový export ani vstupní bod pro App Router.
Nakonfigurujte jazyky a obalovou komponentu aplikace #
npm install @lingo.dev/react@1.17.1 @lingo.dev/react-next@1.17.1
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npm install --save-dev @lingo.dev/cli@latestDo stávajícího next.config.mjs přidejte i18n a ostatní nastavení ponechte beze změny:
export default {
i18n: { locales: ["en", "fr"], defaultLocale: "en" },
};V pages/_app.tsx obalte aplikaci:
import type { AppProps } from "next/app";
import { useRouter } from "next/router";
import { useEffect } from "react";
import { withLingoApp } from "@lingo.dev/react-next/pages/client";
function App({ Component, pageProps }: AppProps) {
const { locale, defaultLocale } = useRouter();
useEffect(() => {
document.documentElement.lang = locale ?? defaultLocale ?? "en";
}, [locale, defaultLocale]);
return <Component {...pageProps} />;
}
export default withLingoApp(App);Obalová komponenta čte pageProps.__lingoMessages, určuje aktivní jazyk v Next.js a poskytuje LingoProvider. Pravidla pro URL se řídí nastavením i18n přímo v Next.js; cesta pro výchozí angličtinu obvykle nemá předponu.
Vytvořte stránku a načtěte její zprávy #
Nejprve přidejte funkci loadMatchedMessages z návodu Načítání katalogu jako lib/catalog.ts. Ověřuje JSONC s řetězcovými hodnotami a přiřazuje cílové hodnoty k aktivním zdrojovým klíčům.
Poté vytvořte pages/about.tsx:
import { readFile } from "node:fs/promises";
import path from "node:path";
import type { GetStaticProps } from "next";
import { useLingo, type Messages } from "@lingo.dev/react";
import { loadMatchedMessages } from "../lib/catalog";
export const getStaticProps: GetStaticProps<{ __lingoMessages: Messages }> = async (ctx) => {
const locale = ctx.locale ?? ctx.defaultLocale ?? "en";
if (!["en", "fr"].includes(locale)) return { notFound: true };
const source = await readFile(path.join(process.cwd(), "locales/en.jsonc"), "utf8");
const target =
locale === "en" ? source : await readFile(path.join(process.cwd(), "locales", `${locale}.jsonc`), "utf8");
const messages = loadMatchedMessages(source, target, (entry) => {
const route = entry.metadata.src?.replace(/\.\w+(?::\d+)?$/, "");
return !route || route === "pages/about" || (!route.startsWith("pages/") && !route.startsWith("src/pages/"));
});
return { props: { __lingoMessages: messages } };
};
export default function About() {
const l = useLingo();
return <h1>{l.text("About us", { context: "About page heading" })}</h1>;
}Tento predikát zachovává položky samotné stránky i zprávy sdílených komponent. Ze zdrojových metadat odstraňuje přípony souborů a starší přípony s čísly řádků. Pokud se stránka nachází v src/pages/about.tsx, upravte podle toho cestu importu i porovnání trasy.
Vlastní načítací funkce záměrně selže, pokud potřebný soubor chybí nebo má nesprávný formát. Při sestavení tak nelze bez upozornění nahradit očekávaný francouzský katalog záložní angličtinou. Jednotlivé chybějící cílové klíče se nedoplňují a za běhu se pro ně použije běžný záložní mechanismus.
Extrahujte, přeložte a otevřete obě trasy #
Z kořenového adresáře projektu spusťte npx lingo extract --src pages --source-locale en. Pokud vytváříte novou konfiguraci projektu Lingo.dev, spusťte:
npx lingo init --source en --targets fr --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link
npx lingo push --backfill-missing --waitU již nakonfigurovaného projektu zachovejte jeho vazbu i ostatní nastavení souborů. Po extrakci proveďte obvyklé aktualizace pro stávající cílové jazyky, stáhněte je a zkontrolujte. Poté přidejte fr a doplňte chybějící překlady, aniž byste změnili danou revizi zdroje. Postup konfigurace najdete v návodu Načítání katalogu a potřebné pořadí kroků vysvětluje návod Přidání jazyka. Pokud jsou sdílené komponenty mimo pages, spusťte extrakci z adresáře, který obsahuje všechna volání zpráv, nebo je uspořádejte do společného stromu src a použijte --src src.
Po stažení locales/fr.jsonc spusťte obvyklý příkaz Next.js pro vývoj nebo sestavení. Otevřete /about a /fr/about. První trasa používá anglický zdroj, druhá francouzský překlad pro stejný klíč nadpisu. Zkontrolujte skutečné znění francouzského textu a ověřte, že se u záměrně chybějící položky použije zdrojový text jako záloha.
Vestavěné načítání statických props #
Pokud si soubor každého jazyka zachová správná metadata @src a @orphan, může serverová pomocná funkce nahradit výše uvedenou vlastní funkci getStaticProps:
import { withLingoProps } from "@lingo.dev/react-next/pages/server";
export const getStaticProps = withLingoProps({ route: "pages/about" });withLingoProps({ route, handler? }) čte z pevně daných cest locales/<locale>.jsonc relativních k pracovnímu adresáři. Odfiltruje osiřelé položky a položky jiných stránek. Zdroje, které nepatří ke stránkám, a položky bez @src považuje za sdílené. Obecný překlad JSONC zachovává značky @orphan, ale odstraňuje komentáře @src. Pro takový výstup proto použijte výše uvedený postup propojení pomocí zdrojových klíčů; pomocná funkce metadata neobnovuje.
Pokud soubor chybí, funkce vrátí {} a ve vývojovém režimu zobrazí varování; existující soubor s neplatným obsahem může vyvolat výjimku. Nepovinná asynchronní obslužná funkce přidává props nebo vrací výsledek přesměrování či nenalezené stránky. Úspěšné výsledky zachovávají pole, jako je revalidate, a přidávají __lingoMessages. Její veřejné typy pracují s kontextem a výsledky pro statické props; nepředpokládejte, že libovolné serverové obslužné funkce požadavků mají stejný kontrakt. Ani přepsání cest ke katalogům v CLI nemění pevně daný adresář této načítací funkce.
Rozšiřte dynamické statické cesty #
U dynamické trasy serverová pomocná funkce rozšíří každou položku parametrů na všechny jazyky nakonfigurované v Next.js:
import { withLingoPaths } from "@lingo.dev/react-next/pages/server";
export const getStaticPaths = withLingoPaths(async () => [{ params: { slug: "refund-policy" } }], {
fallback: "blocking",
});Výchozí záložní režim je "blocking"; podporovány jsou také false a true. Rozšíření nepřekládá slugy ani nezaručuje, že každý katalog obsahuje zprávy dané trasy.
Přepínejte jazyk a přidejte alternativní odkazy #
Vykreslete přepínač pod obalovou komponentou aplikace:
import { LingoHead, useLocaleSwitch } from "@lingo.dev/react-next/pages/client";
export function Languages() {
const switchLocale = useLocaleSwitch();
return (
<nav aria-label="Language">
<LingoHead baseUrl="https://example.com" />
<button onClick={() => switchLocale("en")}>English</button>
<button onClick={() => switchLocale("fr")}>Français</button>
</nav>
);
}Nahraďte ukázkový origin absolutním produkčním originem webu. LingoHead generuje alternativní odkazy pro nakonfigurované jazyky a x-default a vynechává předponu výchozího jazyka. Negeneruje kanonická metadata ani metadata Open Graph. Zkontrolujte výsledné URL s ohledem na pravidla pro trasy a parametry dotazu.
Zpětné volání přepínače zapíše NEXT_LOCALE s platností na jeden rok na / s SameSite=Lax a poté provede navigaci pomocí routeru Next.js s použitím aktuálního asPath. Předejte nakonfigurované jazyky jako výše; libovolný vstup se neověřuje vůči seznamu podporovaných jazyků.
Nastavte počáteční atributy dokumentu #
Nastavte počáteční atributy v pages/_document.tsx a zachovejte všechny stávající úpravy dokumentu:
import Document, { Html, Head, Main, NextScript } from "next/document";
import { createLingo } from "@lingo.dev/react";
export default class LocalizedDocument extends Document {
render() {
const locale = this.props.__NEXT_DATA__.locale ?? "en";
return (
<Html lang={locale} dir={createLingo(locale).direction}>
<Head />
<body>
<Main />
<NextScript />
</body>
</Html>
);
}
}withLingoApp nastavuje směr textu po změně jazyka a pro počáteční vykreslení generuje vložený skript RTL, ale nenastavuje lang. Výše uvedený efekt _app během navigace aktualizuje lang; vlastní dokument zajišťuje oba počáteční atributy. Přísné zásady zabezpečení obsahu mohou vložený skript obalové komponenty zablokovat a komponenta nenabízí možnost nastavit nonce. Vlastní dokument zajišťuje počáteční směr textu nezávisle na tomto skriptu. Zásady aplikace pro skripty zkontrolujte i během navigace.
Nakonec zkontrolujte hydrataci se stejným katalogem a explicitně zadanými časovými vstupy. Ověřte, že se při přepnutí jazyka mění zprávy i atributy dokumentu současně.