Markdoc mit Next.js lokalisieren
Sprachspezifische Markdoc-Dokumente zusammen mit separaten UI-Katalogen in einer Next.js-Anwendung mit App Router routen, laden, übersetzen und rendern.
Ein übersetzter Artikel muss zur Seite passen, in die er eingebettet ist. Auf einer Next.js-Website kann die Sprache der Route sowohl das Markdoc-Dokument als auch einen separaten UI-Katalog für die Navigation bestimmen. Diese Anleitung zeigt, wie du die Dateien in eine App-Router-Seite einbindest und anschließend mit der CLI übersetzt.
Verwende ein bestehendes Next.js-Projekt mit App Router und Markdoc. Das Beispiel liest lokale Dateien auf dem Server und benötigt keinen React-Lokalisierungsadapter.
Wähle eine sprachspezifische Dateistruktur #
In einem Beispielprojekt lassen sich Dokumente und UI-Kataloge nach Sprache gruppieren:
src/content/
en/
pages/home.mdoc
blog/welcome.mdoc
ui.json
es/
pages/home.mdoc
blog/welcome.mdoc
ui.json
src/app/[lang]/Behalte Slugs bei, wenn sie als Inhaltskennungen dienen. Eine übersetzte Überschrift erfordert keine Umbenennung von home.mdoc. Wenn du Slugs bewusst lokalisierst, pflege eine explizite Zuordnung für die Navigation und Links zu anderen Sprachversionen. Die Übersetzung des Artikeltexts erstellt diese Zuordnung nicht.
Stelle vor dem Erstellen eines Dateisystempfads sicher, dass die Sprache der Route und der Dokument-Slug zu den bekannten Werten gehören. Lege fest, wie fehlende Übersetzungen behandelt werden: mit einer Nicht-gefunden-Antwort oder einem expliziten Rückgriff auf die Quellsprache. Das folgende Startseitenbeispiel verwendet einen festen Dokumentnamen und gibt bei nicht unterstützten Sprachen oder fehlenden Dateien eine Nicht-gefunden-Antwort zurück.
Wähle den Markdoc-Handler und die sichtbaren Metadaten aus #
Installiere und verknüpfe die CLI vom Projektstammverzeichnis aus:
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'src/content/en/pages/*.mdoc' --yes
lingo linkBehalte die generierten IDs der Organisation und der Lokalisierungs-Engine in .lingo/config.json bei und konfiguriere anschließend die vollständige Auswahl der Quelldateien:
{
"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 wählt Markdoc automatisch aus; die explizite Formatangabe macht diese Wahl deutlich. Wenn ein bestehendes Projekt Markdoc-Syntax in .md speichert, setze format: "markdoc" explizit. Andernfalls wird anhand der Dateiendung gewöhnliches Markdown ausgewählt. Dieser Unterschied ist für benutzerdefinierte Tags und ausgewählte Komponentenattribute wichtig.
Wähle die sichtbaren Frontmatter-Felder gezielt aus. Lass Datumsangaben, Angaben zur Autorschaft, stabile IDs und Routing-Metadaten unverändert, sofern deine Inhaltsrichtlinie keine bestimmte Umwandlung verlangt. Deklariere Komponenten-Props nur dann als übersetzbar, wenn sie Text für die Leserschaft enthalten. Unter Markdoc findest du Informationen zum Verhalten des Handlers und unter CLI-Konfiguration die Namen der Dateioptionen; die Optionen der Dokument-API verwenden ein anderes Schema.
Verwende einen UI-Katalog pro Sprache. Informationen zu anderen Dateistrukturen für Website-Generatoren findest du unter Statische Inhalte.
Rendere die Startseite in der Quellsprache über ihre Sprachroute #
Gib src/content/en/pages/home.mdoc im YAML-Frontmatter einen Titel und eine Beschreibung und füge danach den Artikeltext ein. Ergänze in src/content/en/ui.json den Eintrag {"home": "Home"} für die Navigationsbeschriftung. Installiere @markdoc/markdoc und yaml, falls sie noch nicht zu den Abhängigkeiten des Projekts gehören.
Dieses minimale src/app/[lang]/page.tsx liest die Startseite in Quell- und Zielsprache über denselben Ladepfad. Es verwendet die Promise-basierten Routenparameter des aktuellen App Routers:
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>
);
}Öffne zuerst /en. Dieses Beispiel verwendet Standard-Markdoc-Knoten. Bei einer Website mit benutzerdefinierten Tags übergib deren tatsächliche Konfiguration sowohl an Markdoc.validate als auch an Markdoc.transform und stelle anschließend Markdoc.renderers.react die benannten React-Komponenten bereit. Übergib erforderliche Variablen explizit. Der Übersetzungshandler behält Annotationen bei, stellt aber nicht das Tag-Schema der Website bereit.
Nutze denselben validierten Loader auch für die Metadatengenerierung und weitere Routen. Ermittle bei dynamischen Dokument-Slugs zunächst den zugehörigen Eintrag im bekannten Inhaltsbestand, bevor du einen Pfad liest. Ein Node-Dateisystem-Loader setzt voraus, dass die Inhaltsdateien im Deployment-Artefakt enthalten sind; stelle sicher, dass sie im Produktions-Build mitgeliefert werden. Ein Edge-Deployment ohne Dateisystemzugriff benötigt eine andere Methode zum Lesen der gespeicherten Inhalte.
Stimme Sprachaushandlung und Navigation aufeinander ab #
Verwende für Routen ohne Sprache die explizite Präferenz der Anwendung oder handle anhand von Accept-Language eine unterstützte Sprache aus. Werte Qualitätsgewichtungen und regionale Sprachkennungen aus und leite dann zur entsprechenden [lang]-Route weiter. Behalte dabei den restlichen Pfad bei.
Leite weder Routen um, die bereits eine unterstützte Sprache enthalten, noch API-Anfragen, interne Next.js-Ressourcen oder statische Dateien. Ein zu breit gefasster Matcher kann Schleifen erzeugen oder Bildanfragen auf Dokumentrouten umleiten. Wende die Ausschlüsse an, die deine installierte Next.js-API zum Abfangen von Routing-Anfragen unterstützt. Ältere Projekte verwenden Middleware; neuere Versionen nutzen möglicherweise die umbenannte Proxy-Konvention. Stimme Verhalten und Tests auf die installierte Version ab, statt einen alten Dateinamen als allgemeingültige Lösung zu übernehmen.
Erstelle interne Links und Links zu anderen Sprachversionen anhand bekannter Routenzuordnungen. Stelle sicher, dass jedes Ziel vorhanden ist, bevor du es in einer Sprachauswahl anbietest. Kontrolliere auch Überschriftenanker, da übersetzte Überschriften zu anderen generierten IDs führen können.
Generiere nur Routen, deren Dokumente verfügbar sind #
Ermittle für die statische Generierung die unterstützten Kombinationen aus Sprache und Slug anhand des tatsächlichen Inhaltsbestands. Nimm sie in den generateStaticParams-Ablauf des Projekts auf und sieh dir die generierten Routen an. Gleiche beim dynamischen Laden die Anfrage ebenfalls mit diesem Bestand ab und behandle fehlende Dateien gezielt. Generiere nicht einfach jede Zielroute aus der Sprachliste in der Annahme, dass die zugehörige Übersetzung vorhanden ist.
Übersetze fehlende Zieldateien mit lingo push --backfill-missing --wait. Stelle nach Abschluss sicher, dass src/content/es/pages/home.mdoc und src/content/es/ui.json vorhanden sind, und öffne dann /es über denselben Loader. Sieh dir den übersetzten Titel, die Beschreibung, den Artikeltext, die Links, die Codeblöcke und die Struktur der benutzerdefinierten Tags an. Codebeispiele und verhaltenssteuernde Attribute sollten ihre ursprüngliche Bedeutung und ihre Werte beibehalten.
Wenn lokale Korrekturen an Zieldateien gegen abweichende Änderungen abgesichert werden müssen, reiche den Auftrag ohne --wait ein und sieh dir vor dem Abruf lingo pull --dry-run an. Beim direkten Zurückschreiben mit Warten fehlt diese Schranke. Folge der Anleitung Übersetzungen nach der Prüfung bewahren.
Validiere eine Seite, bevor du Übersetzungen regelmäßig ausführst #
Öffne eine Route in der Zielsprache direkt und navigiere anschließend über die Website dorthin. Stelle sicher, dass Überschrift, Bedienelemente, Metadaten und Sprachauswahl die vorgesehene Sprache verwenden. Kontrolliere eine benutzerdefinierte Komponente und ein Codebeispiel und folge einem internen Link sowie einem Überschriftenanker. Führe den bestehenden Next.js-Build und die Markdoc-Validierung des Projekts für die übersetzten Dateien aus.
Halte Quelldateien, akzeptierte Zieldateien, Konfiguration und CLI-Lockfile zusammen. Nutze bei späteren Änderungen an den Quelldateien den normalen lingo push --wait-Workflow. Sobald die Seite funktioniert, wähle die verwaltete GitHub-Übersetzung oder eine Runner-Anleitung mit einer Möglichkeit zur Prüfung vor dem Zurückschreiben. Behalte die Validierung des Inhalts-Loaders und den Next.js-Build in diesem Zyklus bei; lingo check stellt weder die Vollständigkeit der Dokumente noch das korrekte Rendern benutzerdefinierter Tags sicher.