Localiser Markdoc avec Next.js

Gérez le routage, le chargement, la traduction et le rendu de documents Markdoc propres à chaque langue, avec des catalogues d’interface distincts, dans une application Next.js App Router.

Un article traduit doit rester cohérent avec la page qui l’entoure. Sur un site Next.js, la langue de la route peut déterminer à la fois le document Markdoc et le catalogue d’interface utilisé pour la navigation. Ce guide relie ces fichiers à une page App Router, puis les traduit avec la CLI.

Utilisez un projet Next.js App Router existant avec Markdoc. L’exemple lit des fichiers locaux côté serveur et ne dépend pas d’un adaptateur de localisation React.

Organiser les fichiers par langue #

Voici un exemple d’organisation qui regroupe les documents et les catalogues d’interface par langue :

text
src/content/
  en/
    pages/home.mdoc
    blog/welcome.mdoc
    ui.json
  es/
    pages/home.mdoc
    blog/welcome.mdoc
    ui.json
src/app/[lang]/

Conservez les slugs lorsqu’ils servent d’identifiants de contenu. Traduire un titre n’oblige pas à renommer home.mdoc. Si vous choisissez de localiser les slugs, maintenez une table de correspondance explicite pour la navigation et les liens vers les autres langues ; la traduction du corps du document ne crée pas cette correspondance.

Vérifiez que la langue de la route et le slug du document appartiennent à des ensembles connus avant de construire un chemin dans le système de fichiers. Définissez le comportement à adopter lorsqu’une traduction manque : renvoyer une réponse « introuvable » ou revenir explicitement à la langue source. L’exemple de page d’accueil ci-dessous utilise un nom de document fixe et renvoie une réponse « introuvable » si la langue n’est pas prise en charge ou si le fichier manque.

Sélectionner le gestionnaire Markdoc et les métadonnées visibles #

Installez et associez la CLI depuis la racine du projet :

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'src/content/en/pages/*.mdoc' --yes
lingo link

Conservez dans .lingo/config.json les identifiants générés pour l’organisation et le moteur de localisation, puis configurez la sélection complète des sources :

json
{
  "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 sélectionne automatiquement Markdoc ; indiquer explicitement le format permet de clarifier ce choix. Si un projet existant stocke la syntaxe Markdoc dans .md, définissez explicitement format: "markdoc". Sinon, la détection par extension sélectionne le Markdown classique. Cette distinction compte pour les balises personnalisées et les attributs de composants sélectionnés.

Choisissez avec soin les champs visibles du frontmatter. Laissez les dates, les auteurs, les identifiants stables et les métadonnées de routage inchangés, sauf si votre politique de contenu exige une transformation précise. Ne déclarez des propriétés de composants comme traduisibles que si elles contiennent du texte destiné au lectorat. Consultez Markdoc pour connaître le comportement du gestionnaire et Configuration de la CLI pour les noms des options de fichiers ; les options de l’API de documents utilisent un schéma différent.

Utilisez un catalogue d’interface par langue. Pour d’autres organisations de fichiers de générateurs de sites, consultez Contenu statique.

Afficher la page d’accueil source via la route de sa langue #

Dans src/content/en/pages/home.mdoc, ajoutez un titre et une description dans le frontmatter YAML, puis le corps de l’article. Dans src/content/en/ui.json, ajoutez {"home": "Home"} pour le libellé de navigation. Installez @markdoc/markdoc et yaml si ces dépendances ne sont pas déjà présentes dans le projet.

Ce src/app/[lang]/page.tsx minimal lit les pages d’accueil source et cible avec la même logique de chargement. Il utilise les paramètres de route sous forme de promesses de la version actuelle d’App Router :

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

Ouvrez d’abord /en. Cet exemple utilise des nœuds Markdoc standard. Si votre site comporte des balises personnalisées, transmettez sa configuration réelle à Markdoc.validate et à Markdoc.transform, puis fournissez les composants React nommés à Markdoc.renderers.react. Transmettez explicitement les variables requises. Le gestionnaire de traduction préserve les annotations ; il ne fournit pas le schéma des balises du site.

Étendez ce même chargeur, avec ses contrôles de validation, à la génération des métadonnées et aux autres routes. Pour les slugs de documents dynamiques, identifiez une entrée connue de l’inventaire avant de lire un chemin. Un chargeur utilisant le système de fichiers de Node exige que les fichiers de contenu soient inclus dans l’artefact déployé ; vérifiez leur présence dans la compilation de production. Un déploiement Edge sans accès au système de fichiers nécessite un autre mécanisme de lecture du stockage.

Aligner la négociation de langue et la navigation #

Pour les routes sans langue, utilisez la préférence explicite de l’application ou négociez une langue prise en charge à partir de Accept-Language. Analysez les coefficients de qualité et les codes régionaux, puis redirigez vers la route [lang] correspondante en conservant le reste du chemin.

Ne redirigez pas les routes qui comportent déjà une langue prise en charge, les requêtes API, les ressources internes de Next.js ni les fichiers statiques. Une règle de correspondance trop large peut créer des boucles ou rediriger des requêtes d’images vers des routes de documents. Appliquez les exclusions prises en charge par l’API d’interception du routage de la version de Next.js installée. Les projets plus anciens utilisent un middleware ; les versions plus récentes peuvent utiliser cette convention sous son nouveau nom, proxy. Alignez le comportement et les tests sur la version installée, plutôt que de reprendre un ancien nom de fichier comme solution universelle.

Construisez les liens internes et les liens vers les autres langues à partir de correspondances de routes connues. Vérifiez que chaque cible existe avant de la proposer dans le sélecteur de langue. Vérifiez aussi les fragments de titres, car les titres traduits peuvent générer des identifiants différents.

Générer uniquement les routes dont les documents sont disponibles #

Pour la génération statique, énumérez les paires langue-slug prises en charge à partir de l’inventaire réel du contenu. Intégrez-les au processus generateStaticParams du projet et inspectez les routes générées. Pour le chargement dynamique, effectuez le même contrôle d’inventaire au moment de la requête et gérez explicitement les fichiers manquants. Ne générez pas toutes les routes cibles à partir de la liste des langues en supposant que chaque traduction existe.

Traduisez les fichiers cibles manquants avec lingo push --backfill-missing --wait. Une fois l’opération terminée, vérifiez que src/content/es/pages/home.mdoc et src/content/es/ui.json existent, puis ouvrez /es avec le même chargeur. Inspectez le titre, la description, le corps et les liens traduits, ainsi que les blocs de code et la structure des balises personnalisées. Les exemples de code et les attributs qui déterminent le comportement doivent conserver leur sens et leurs valeurs d’origine.

Si les corrections apportées localement aux fichiers cibles doivent être protégées contre les divergences, soumettez sans --wait et inspectez lingo pull --dry-run avant la récupération ; la réécriture directe après attente ne comporte pas ce contrôle. Suivez Préserver les traductions relues.

Vérifier une page avant de rendre la traduction récurrente #

Ouvrez directement une route dans la langue cible, puis accédez-y depuis le site. Vérifiez que le titre, les éléments d’interface, les métadonnées et le sélecteur de langue utilisent tous la langue prévue. Contrôlez un composant personnalisé et un exemple de code, puis suivez un lien interne et un fragment de titre. Exécutez la compilation Next.js existante du projet et la validation Markdoc sur les fichiers traduits.

Conservez ensemble les sources, les cibles acceptées, la configuration et le Lockfile de la CLI. Les modifications ultérieures des sources suivent le workflow lingo push --wait habituel. Une fois la page fonctionnelle, choisissez la traduction gérée via GitHub ou une recette d’exécution permettant la relecture des modifications avant leur réécriture. Maintenez la validation du chargeur de contenu et la compilation Next.js dans ce cycle ; lingo check ne garantit ni l’exhaustivité des documents ni le rendu correct des balises personnalisées.