Lokalizace Markdoc v Next.js
Směrujte, načítejte, překládejte a vykreslujte dokumenty Markdoc pro jednotlivé jazyky spolu se samostatnými katalogy textů rozhraní v aplikaci Next.js s App Routerem.
Přeložený článek musí jazykově ladit s okolní stránkou. Na webu v Next.js může jazyk trasy určovat jak dokument Markdoc, tak samostatný katalog textů pro navigaci. V tomto průvodci tyto soubory propojíte se stránkou v App Routeru a poté je přeložíte pomocí CLI.
Použijte stávající projekt Next.js s App Routerem a Markdoc. Příklad čte lokální soubory na serveru a nevyžaduje lokalizační adaptér pro React.
Zvolte uspořádání souborů podle jazyka #
V ukázkovém projektu můžete dokumenty a katalogy textů rozhraní ukládat společně podle jazyka:
src/content/
en/
pages/home.mdoc
blog/welcome.mdoc
ui.json
es/
pages/home.mdoc
blog/welcome.mdoc
ui.json
src/app/[lang]/Pokud slugy slouží jako identifikátory obsahu, ponechte je beze změny. Překlad nadpisu nevyžaduje přejmenování home.mdoc. Pokud slugy záměrně lokalizujete, udržujte explicitní mapování pro navigaci a odkazy na jiné jazykové verze; samotný překlad těla dokumentu toto mapování nevytvoří.
Před sestavením cesty v souborovém systému ověřte, že jazyk trasy i slug dokumentu patří mezi známé hodnoty. Rozhodněte, jak řešit chybějící překlady: odpovědí „nenalezeno“, nebo výslovným použitím zdrojového jazyka jako náhrady. Níže uvedený příklad domovské stránky používá pevně daný název dokumentu a při nepodporovaném jazyce nebo chybějícím souboru vrací odpověď „nenalezeno“.
Vyberte obslužný modul pro Markdoc a zobrazovaná metadata #
V kořenovém adresáři projektu nainstalujte a propojte CLI:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'src/content/en/pages/*.mdoc' --yes
lingo linkV .lingo/config.json ponechte vygenerovaná ID organizace a lokalizačního engine a poté nakonfigurujte celý výběr zdrojů:
{
"orgId": "org_...",
"engineId": "eng_...",
"sourceLocale": "en",
"targetLocales": ["es"],
"files": [
{
"pattern": "src/content/en/pages/*.mdoc",
"format": "markdoc",
"translateFrontmatterFields": ["title", "description"]
},
{
"pattern": "src/content/en/blog/*.mdoc",
"format": "markdoc",
"translateFrontmatterFields": ["title", "description"]
},
{ "pattern": "src/content/en/ui.json" }
]
}.mdoc vybere Markdoc automaticky; výslovné uvedení formátu ale jasně ukazuje váš záměr. Pokud stávající projekt ukládá syntaxi Markdoc do .md, nastavte format: "markdoc" explicitně. Jinak detekce podle přípony zvolí běžný Markdown. Tento rozdíl je důležitý pro vlastní tagy a vybrané atributy komponent.
Pečlivě vyberte zobrazovaná pole frontmatteru. Údaje o datu, autory, stabilní ID a metadata směrování ponechte beze změny, pokud vaše pravidla pro obsah nevyžadují konkrétní transformaci. Vlastnosti komponent označujte jako přeložitelné pouze tehdy, když obsahují text určený čtenářům. Chování obslužného modulu popisuje část Markdoc a názvy voleb pro soubory najdete v části Konfigurace CLI; volby API pro dokumenty používají jiné schéma.
Pro každý jazyk použijte jeden katalog textů rozhraní. Další uspořádání pro generátory webů najdete v části Statický obsah.
Vykreslete domovskou stránku ve zdrojovém jazyce přes příslušnou jazykovou trasu #
V src/content/en/pages/home.mdoc uveďte název a popis ve frontmatteru ve formátu YAML a za ně vložte tělo článku. Do src/content/en/ui.json přidejte {"home": "Home"} jako popisek navigace. Nainstalujte @markdoc/markdoc a yaml, pokud ještě nejsou mezi závislostmi projektu.
Tato minimální implementace src/app/[lang]/page.tsx načítá zdrojovou i cílovou domovskou stránku stejným postupem. Používá parametry trasy založené na Promise z aktuálního App Routeru:
import { readFile } from "node:fs/promises";
import path from "node:path";
import React from "react";
import Markdoc from "@markdoc/markdoc";
import { parse as parseYaml } from "yaml";
import { notFound } from "next/navigation";
export const runtime = "nodejs";
export default async function Page({
params,
}: {
params: Promise<{ lang: string }>;
}) {
const { lang } = await params;
if (lang !== "en" && lang !== "es") notFound();
const root = path.join(process.cwd(), "src/content", lang);
let rawDocument: string;
let rawUi: string;
try {
[rawDocument, rawUi] = await Promise.all([
readFile(path.join(root, "pages/home.mdoc"), "utf8"),
readFile(path.join(root, "ui.json"), "utf8"),
]);
} catch (error) {
if ((error as NodeJS.ErrnoException).code === "ENOENT") notFound();
throw error;
}
const ast = Markdoc.parse(rawDocument);
const errors = Markdoc.validate(ast);
if (errors.some(({ error }) => ["error", "critical"].includes(error.level))) {
throw new Error("Invalid Markdoc document");
}
const metadata = parseYaml(ast.attributes.frontmatter ?? "");
const ui = JSON.parse(rawUi);
if (typeof metadata?.title !== "string" || typeof ui.home !== "string") {
throw new Error("Missing homepage title or navigation label");
}
const tree = Markdoc.transform(ast);
return (
<main lang={lang}>
<nav><a href={`/${lang}`}>{ui.home}</a></nav>
<h1>{metadata.title}</h1>
{Markdoc.renderers.react(tree, React)}
</main>
);
}Nejprve otevřete /en. Tento příklad používá standardní uzly Markdoc. U webu s vlastními tagy předejte jeho skutečnou konfiguraci do Markdoc.validate i Markdoc.transform a poté předejte pojmenované komponenty React do Markdoc.renderers.react. Potřebné proměnné předávejte explicitně. Obslužný modul překladu zachovává anotace, ale neposkytuje schéma tagů webu.
Stejný načítací modul s validací použijte i pro generování metadat a další trasy. U dynamických slugů dokumentů nejprve vyhledejte známou položku v seznamu obsahu a teprve potom čtěte soubor na dané cestě. Modul využívající souborový systém Node vyžaduje, aby soubory s obsahem byly součástí nasazovaného artefaktu; ověřte, že je produkční sestavení zahrnuje. Nasazení do prostředí Edge bez přístupu k souborovému systému vyžaduje jiný způsob čtení z úložiště.
Slaďte vyjednávání jazyka s navigací #
U tras bez jazyka použijte explicitně nastavenou preferenci aplikace nebo vyjednejte podporovaný jazyk z Accept-Language. Zpracujte váhy kvality a regionální značky a poté přesměrujte na odpovídající trasu [lang] se zachováním zbytku cesty.
Nepřesměrovávejte trasy, které už obsahují podporovaný jazyk, požadavky API, interní prostředky Next.js ani statické soubory. Příliš široké pravidlo pro shodu může vytvářet smyčky nebo přesměrovávat požadavky na obrázky na trasy dokumentů. Použijte výjimky podporované rozhraním API pro zachytávání směrování ve vaší nainstalované verzi Next.js. Starší projekty používají middleware; novější verze mohou používat konvenci přejmenovanou na proxy. Chování i testy přizpůsobte nainstalované verzi, místo abyste starý název souboru přebírali jako univerzální řešení.
Interní odkazy i odkazy na jiné jazykové verze sestavujte ze známých mapování tras. Než cílovou stránku nabídnete v přepínači jazyků, ověřte, že existuje. Zkontrolujte také fragmenty odkazující na nadpisy, protože z přeložených nadpisů se mohou generovat jiná ID.
Generujte jen trasy s dostupnými dokumenty #
Pro statické generování sestavte seznam podporovaných dvojic jazyka a slugu podle skutečně dostupného obsahu. Zahrňte je do procesu generateStaticParams v projektu a zkontrolujte vygenerované trasy. Při dynamickém načítání provádějte stejnou kontrolu dostupného obsahu při zpracování požadavku a chybějící soubory řešte zvoleným způsobem. Negenerujte všechny cílové trasy jen ze seznamu jazyků s předpokladem, že jejich překlady existují.
Chybějící cílové soubory přeložte pomocí lingo push --backfill-missing --wait. Po dokončení ověřte, že existují src/content/es/pages/home.mdoc a src/content/es/ui.json, a poté stejným načítacím modulem otevřete /es. Zkontrolujte přeložený název, popis, tělo, odkazy, ohraničené bloky kódu a strukturu vlastních tagů. Příklady kódu a atributy ovlivňující chování by si měly zachovat původní význam a hodnoty.
Pokud potřebujete chránit ruční opravy cílových souborů před přepsáním odlišných verzí, odešlete úlohu bez --wait a před stažením zkontrolujte lingo pull --dry-run; přímý zpětný zápis s čekáním tento kontrolní krok nenabízí. Postupujte podle části Zachování zkontrolovaných překladů.
Než nastavíte pravidelné překlady, ověřte stránku #
Otevřete trasu cílového jazyka přímo a poté na ni přejděte přes web. Ověřte, že nadpis, okolní prvky rozhraní, metadata i přepínač jazyků používají požadovaný jazyk. Zkontrolujte vlastní komponentu a příklad kódu a vyzkoušejte interní odkaz i fragment odkazující na nadpis. S přeloženými soubory spusťte stávající sestavení Next.js a validaci Markdoc v projektu.
Uchovávejte zdroje, přijaté cílové překlady, konfiguraci a Lockfile pro CLI společně. Při pozdějších změnách zdrojů použijte běžné workflow lingo push --wait. Jakmile stránka funguje, zvolte spravovaný překlad přes GitHub nebo postup pro spouštěcí prostředí se zpětným zápisem, který lze zkontrolovat. Součástí tohoto cyklu musí zůstat validace načítacího modulu obsahu a sestavení Next.js; lingo check nezaručuje úplnost dokumentů ani správné vykreslení vlastních tagů.