Traduire une application Next.js Pages

Chargez les messages traduits d'une page, affichez-les via l'enveloppe Pages et ajoutez un sélecteur de langue ainsi que des liens vers les versions alternatives.

Une route Next.js Pages détermine déjà la langue de chaque requête. @lingo.dev/react-next utilise cette langue pour fournir les messages React et garder les données de la page et les textes traduits au même endroit. Ce guide affiche une page À propos en anglais et en français, tout en préservant la sélection de la route lorsque le JSONC traduit a perdu ses métadonnées.

Utilisez une application Pages existante avec React 19. Le paquet déclare Next.js 13+ et React 18/19 comme dépendances homologues, mais le fournisseur utilisé à l'exécution emploie actuellement la syntaxe abrégée de contexte de React 19. Il exporte /pages, /pages/client et /pages/server, sans export à la racine ni point d'entrée App Router.

Configurer les langues et l'enveloppe de l'application #

sh
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@latest

Ajoutez la configuration i18n à votre next.config.mjs existant, sans modifier les autres paramètres :

js
export default {
  i18n: { locales: ["en", "fr"], defaultLocale: "en" },
};

Dans pages/_app.tsx, enveloppez l'application :

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

L'enveloppe lit pageProps.__lingoMessages, détermine la langue active de Next et fournit LingoProvider. Les paramètres i18n de Next définissent les règles de construction des URL ; le chemin de la langue anglaise par défaut ne comporte généralement pas de préfixe.

Écrire la page et charger ses messages #

Ajoutez d'abord la fonction loadMatchedMessages présentée dans Chargement des catalogues sous le nom lib/catalog.ts. Elle valide le JSONC contenant des valeurs de type chaîne et associe les valeurs cibles aux clés sources actives.

Créez ensuite pages/about.tsx :

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

Ce prédicat conserve les entrées propres à la page ainsi que les messages des composants partagés. Il retire des métadonnées sources les extensions et les anciens suffixes de numéros de ligne. Si la page se trouve dans src/pages/about.tsx, adaptez à la fois le chemin d'importation et la comparaison de route.

Le chargeur personnalisé échoue volontairement lorsqu'un fichier requis est absent ou mal formé. Ainsi, la compilation ne peut pas remplacer silencieusement le catalogue français attendu par une version de repli en anglais. Les clés cibles manquantes restent absentes et utilisent le mécanisme de repli habituel à l'exécution.

Extraire, traduire et ouvrir les deux routes #

Exécutez npx lingo extract --src pages --source-locale en depuis la racine du projet. Pour configurer un nouveau projet Lingo.dev, exécutez :

sh
npx lingo init --source en --targets fr --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link
npx lingo push --backfill-missing --wait

Si le projet est déjà configuré, conservez sa liaison et ses autres options de fichiers. Après l'extraction, effectuez les mises à jour habituelles pour les langues cibles existantes, récupérez-les et vérifiez-les, puis ajoutez fr et effectuez un remplissage rétroactif sans modifier cette révision source. Chargement des catalogues détaille les étapes de configuration, et Ajouter une langue explique l'ordre à respecter. Si les composants partagés se trouvent en dehors de pages, lancez l'extraction depuis un répertoire contenant tous les appels de messages, ou regroupez-les dans une arborescence src commune et utilisez --src src.

Après avoir récupéré locales/fr.jsonc, exécutez la commande habituelle de développement ou de compilation de Next. Ouvrez /about et /fr/about. La première route utilise la source anglaise ; la seconde utilise la cible française pour la même clé de titre. Vérifiez le texte effectivement affiché en français ainsi que le repli vers la source pour une entrée volontairement manquante.

Chargement intégré des propriétés statiques #

Lorsque chaque fichier de langue conserve les métadonnées @src et @orphan correctes, la fonction utilitaire côté serveur peut remplacer le getStaticProps personnalisé ci-dessus :

ts
import { withLingoProps } from "@lingo.dev/react-next/pages/server";

export const getStaticProps = withLingoProps({ route: "pages/about" });

withLingoProps({ route, handler? }) lit des chemins locales/<locale>.jsonc fixes, relatifs au répertoire de travail. Il exclut les entrées orphelines et celles des autres pages, et considère comme partagées les sources qui ne sont pas des pages ainsi que les entrées sans @src. La traduction générale du JSONC conserve les marqueurs @orphan mais supprime les commentaires @src ; pour ce type de sortie, utilisez donc la méthode d'association par clés sources présentée ci-dessus. La fonction utilitaire ne restaure pas les métadonnées.

Si un fichier est manquant, le chargeur renvoie {} avec un avertissement en mode développement ; si un fichier existant est invalide, il peut lever une exception. Un gestionnaire asynchrone facultatif ajoute des propriétés ou renvoie un résultat de redirection ou de page introuvable. En cas de réussite, les résultats conservent les champs tels que revalidate et ajoutent __lingoMessages. Ses types publics utilisent le contexte et les résultats des propriétés statiques ; ne partez pas du principe que n'importe quel gestionnaire de requêtes côté serveur respecte le même contrat. La redéfinition des chemins de catalogues via la CLI ne modifie pas non plus le répertoire fixe de ce chargeur.

Étendre les chemins statiques dynamiques #

Pour une route dynamique, la fonction utilitaire côté serveur décline chaque entrée de paramètres dans toutes les langues configurées dans Next :

ts
import { withLingoPaths } from "@lingo.dev/react-next/pages/server";

export const getStaticPaths = withLingoPaths(async () => [{ params: { slug: "refund-policy" } }], {
  fallback: "blocking",
});

Le repli par défaut est "blocking" ; false et true sont également pris en charge. Cette extension ne traduit pas les slugs et ne garantit pas que chaque catalogue contient les messages de la route.

Changer de langue et ajouter des liens vers les versions alternatives #

Affichez un sélecteur sous l'enveloppe de l'application :

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

Remplacez l'origine de l'exemple par l'origine absolue du site en production. LingoHead génère des liens vers les versions alternatives pour les langues configurées et x-default, sans préfixe pour la langue par défaut. Il ne génère ni métadonnées canoniques ni métadonnées Open Graph. Vérifiez les URL obtenues selon vos règles de routage et de gestion des paramètres de requête.

La fonction de rappel du sélecteur écrit NEXT_LOCALE pour une durée d'un an à / avec SameSite=Lax, puis navigue avec le routeur de Next en utilisant le asPath actuel. Fournissez les langues configurées, comme ci-dessus ; la fonction ne vérifie pas les valeurs arbitraires par rapport à la liste des langues prises en charge.

Définir les attributs initiaux du document #

Définissez les attributs initiaux dans pages/_document.tsx, en conservant les personnalisations existantes du document :

tsx
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 définit le sens d'écriture après chaque changement de langue et génère un script RTL intégré pour le rendu initial, mais ne définit pas lang. L'effet _app ci-dessus met à jour lang pendant la navigation ; le document personnalisé fournit les deux attributs initiaux. Une politique de sécurité du contenu stricte peut bloquer le script intégré de l'enveloppe, qui ne propose aucune option de nonce. Le document personnalisé fournit le sens d'écriture initial sans dépendre de ce script. Vérifiez également la politique de scripts de l'application pendant la navigation.

Enfin, vérifiez l'hydratation avec le même catalogue et des valeurs temporelles explicites. Assurez-vous qu'un changement de langue met à jour les messages et les attributs du document en même temps.