Traduire une application Next.js avec App Router
Servez chaque page avec un préfixe de langue, redirigez les chemins sans préfixe et affichez des composants serveur et client traduits avec @lingo.dev/react-next.
Dans App Router, chaque langue possède son propre préfixe d’URL, y compris la langue source : les internautes consultent /en/pricing et /de/pricing. @lingo.dev/react-next lit la langue dans un segment de route app/[locale], charge le catalogue correspondant sur le serveur et fournit les mêmes messages aux composants serveur et client. Ce guide explique comment ajouter l’allemand et le français à une application en anglais.
Utilisez Next.js 16 ou une version ultérieure avec React 19 ; les points d’entrée lisent la langue via next/root-params. Installez les paquets :
npm install @lingo.dev/react@1.22.0 @lingo.dev/react-next@1.22.0 @lingo.dev/locale-router@0.3.0
npm install --save-dev @lingo.dev/cli@latestDéfinir les langues #
Créez i18n.ts à côté de app/ (src/i18n.ts si l’application utilise src/) :
import { createLocaleRouter } from "@lingo.dev/locale-router";
export const locales = createLocaleRouter(["en", "de", "fr"] as const, { defaultLocale: "en", exclude: ["api"] });
export const localePath = (pathname: string, locale: string) =>
locales.prefix(pathname, locales.toLocale(locale) ?? locales.defaultLocale);Listez les langues dans .lingo/config.json, avec la langue source comme defaultLocale. exclude désigne les premiers segments de chemin qui ne reçoivent aucun préfixe, comme les gestionnaires de route sous app/api/. Ne transmettez pas slugs : le segment d’URL de chaque langue doit correspondre à son identifiant en minuscules (/pt-br pour pt-BR), car getLingo() détermine la langue à partir de ce seul segment. Avec un slug personnalisé, le fournisseur lève une erreur qui mentionne ce slug. Le proxy et les composants serveur et client importent tous ce fichier ; n’y ajoutez donc aucun autre import.
Rediriger les chemins sans préfixe #
Créez proxy.ts à côté de app/ :
import { lingoProxy } from "@lingo.dev/react-next/app/proxy";
import { locales } from "./i18n";
export const proxy = lingoProxy(locales);
export const config = { matcher: ["/", "/((?!api|_next|.*\\..*).*)"] };lingoProxy(locales) gère deux types de requêtes :
| Requête | Réponse |
|---|---|
Un premier segment qui désigne une langue autrement que par son slug, comme /DE/about, /de-AT ou /de_DE | 301 vers l’adresse canonique. |
Un chemin localisé sans préfixe de langue, comme /about | 307 vers la langue négociée à partir de Accept-Language, avec Cache-Control: private, no-store et Vary: Accept-Language. |
| Tout autre cas | undefined. |
Les redirections conservent la chaîne de requête et le basePath de l’application. Next.js lit le filtre de correspondance lors de la compilation : conservez donc une valeur littérale et veillez à ce que son api reste cohérent avec exclude. Si l’application possède déjà un proxy, appelez d’abord lingoProxy, puis poursuivez avec votre propre logique lorsque cet appel renvoie undefined. middleware.ts est le même fichier sous son ancien nom ; renommez-le en proxy.ts et sa fonction en proxy.
Déplacer les routes sous le préfixe de langue #
Déplacez la mise en page racine et toutes les pages dans app/[locale]/, un niveau de dossier plus bas. app/[locale]/layout.tsx devient la mise en page racine, et app/layout.tsx n’existe plus. Les gestionnaires de route sous app/api/, globals.css, les icônes, robots.ts et sitemap.ts restent à leur emplacement. Supprimez toute clé i18n de next.config ; App Router ne la lit pas.
// app/[locale]/layout.tsx
import type { ReactNode } from "react";
import { getLingo, LingoAppProvider, lingoStaticParams } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";
import "../globals.css";
export function generateStaticParams() {
return lingoStaticParams(locales);
}
export default async function RootLayout({ children }: { children: ReactNode }) {
const l = await getLingo();
return (
<html lang={l.locale} dir={l.direction}>
<body>
<LingoAppProvider locales={locales}>{children}</LingoAppProvider>
</body>
</html>
);
}lingoStaticParams renvoie un { locale } par langue ; la compilation effectue donc un prérendu de chaque page une fois par langue. LingoAppProvider renvoie une erreur 404 pour toute langue absente de la liste. N’ajoutez pas export const dynamicParams = false : Next.js le rejette lorsque cacheComponents est activé.
Traduire les composants serveur et client #
Les composants serveur, les pages, les mises en page et generateMetadata appellent await getLingo() depuis @lingo.dev/react-next/app/server. Les composants client appellent useLingo() depuis @lingo.dev/react ; LingoAppProvider leur fournit la langue et le catalogue correspondants. Dans les deux cas, il n’est pas nécessaire de transmettre la langue.
// app/[locale]/page.tsx
import { getLingo } from "@lingo.dev/react-next/app/server";
export default async function Home() {
const l = await getLingo();
return <h1>{l.text("Welcome", { context: "Heading of the start page" })}</h1>;
}Un composant serveur peut recevoir l comme propriété de son composant parent serveur, mais ne transmettez jamais l à un composant client : les fonctions ne peuvent pas passer du serveur au client. Un appel à getLingo() en dehors de app/[locale]/ lève une erreur, car il ne trouve aucun segment [locale].
Ajouter des métadonnées #
import { getLingo, lingoMetadata } from "@lingo.dev/react-next/app/server";
import { locales } from "@/i18n";
export async function generateMetadata() {
const l = await getLingo();
return {
title: l.text("Pricing", { context: "Title of the pricing page" }),
...(await lingoMetadata({ locales, pathname: "/pricing", origin: "https://example.com" })),
};
}lingoMetadata({ locales, pathname, origin, ogLocale? }) renvoie alternates.canonical, alternates.languages pour chaque langue ainsi que x-default, puis openGraph.url et openGraph.locale. Transmettez le chemin de la page sans préfixe de langue, chaîne de requête ni fragment ; une route dynamique le construit à partir de ses paramètres. Remplacez l’origine de l’exemple par celle de votre site. Politique des URL par langue explique lingoHead, qui construit les valeurs, ainsi que la surcharge ogLocale.
Créer des liens et changer de langue #
Ajoutez un préfixe à chaque lien interne avec localePath("/pricing", l.locale) depuis i18n.ts. l.locale est une simple chaîne de caractères ; localePath restreint donc son type à l’une des langues du routeur avant que locales.prefix n’ajoute le préfixe. Un lien sans préfixe passe par le proxy, qui redirige vers la langue du navigateur plutôt que vers celle de la page. Il en va de même pour redirect(), router.push() et les actions de formulaire qui désignent un chemin.
"use client";
import Link from "next/link";
import { useLocaleSwitch } from "@lingo.dev/react-next/app/client";
import { locales } from "@/i18n";
export function LocaleSwitcher() {
const options = useLocaleSwitch(locales);
return (
<nav aria-label="Language">
{options.map((option) => (
<Link key={option.locale} href={option.href} hrefLang={option.locale} aria-current={option.current ? "page" : undefined}>
{option.label}
</Link>
))}
</nav>
);
}useLocaleSwitch(locales) renvoie un { locale, label, href, current } par langue : la page actuelle dans cette langue, le nom de la langue dans cette même langue et une indication précisant s’il s’agit de la langue actuelle. La chaîne de requête est ajoutée après l’hydratation ; une page qui affiche le sélecteur reste donc statique. Suivre un lien déclenche un nouveau rendu de la mise en page, qui charge le catalogue de la nouvelle langue.
Extraire et charger les catalogues #
Le serveur lit locales/<locale>.jsonc dans le dossier depuis lequel next s’exécute, à l’aide de fs ; conservez donc i18n.messagesPath à sa valeur par défaut, locales. Il écarte les entrées orphelines et relit le fichier à chaque requête ; next dev sert donc le catalogue modifié dès la requête suivante. Un fichier manquant donne un catalogue vide, avec un avertissement en développement ; un fichier mal formé ou une valeur qui n’est pas une chaîne de caractères provoque une erreur qui mentionne le fichier. En production, la langue source n’envoie aucun catalogue au navigateur, car son texte sert de valeur de repli.
Lorsque app/ se trouve à la racine du projet sans dossier src/, définissez "i18n": { "src": "." } dans .lingo/config.json pour que l’extraction analyse app/ et components/. L’extraction ignore node_modules et les dossiers dont le nom commence par un point, comme .next. Pour une nouvelle configuration :
npx lingo init --source en --targets de,fr --files 'locales/en.jsonc' --yes
npx lingo extract --src .
npx lingo login
npx lingo link
npx lingo push --backfill-missing --waitDéfinissez i18n.src après init, qui réécrit la section i18n. Dans un monorepo, .lingo/config.json se trouve à la racine du dépôt et ses chemins sont relatifs à cette racine ; messagesPath correspond donc au dossier de l’application suivi de locales, comme apps/web/locales. Consultez la table i18n des applications nommées dans Configuration de la CLI. Le serveur continue de lire locales/ dans le dossier propre à l’application.
Après next build et next start, ouvrez / et vérifiez la redirection vers une langue, puis ouvrez /de et vérifiez le texte allemand dans le HTML.
Environnement d’exécution #
Les pages prérendues fonctionnent chez n’importe quel hébergeur. Une page rendue à la demande lit son catalogue sur le disque ; elle nécessite donc l’environnement d’exécution Node.js. Cloudflare Workers et l’environnement d’exécution Edge ne peuvent pas le lire.
Exports #
| Point d’entrée | Exports |
|---|---|
@lingo.dev/react-next/app/server | getLingo(), LingoAppProvider, lingoMetadata(options), lingoStaticParams(locales). |
@lingo.dev/react-next/app/client | useLocaleSwitch(locales) et le type LocaleOption. |
@lingo.dev/react-next/app/proxy | lingoProxy(locales). |
Les agents de programmation peuvent suivre lingo agent-guide react-next-app une fois le paquet installé, et lingo agent-guide react-next-migrate pour migrer depuis next-intl. Consultez Configurer avec un agent de programmation.