← Blog

Comment traduire une application Next.js (App Router) dans plusieurs langues avec i18next

Guide pas à pas : traduisez votre application Next.js de l'espagnol vers l'anglais, le japonais, le portugais et le français avec npm run translate et i18next. Avec la sortie réelle.

· 3 min de lecture

Presque tous les projets Next.js avec i18n finissent de la même façon : un translation.json en espagnol et un après-midi à le copier dans ChatGPT, coller la réponse et vérifier qu'aucune clé n'a été modifiée. Puis quelqu'un ajoute un texte et on recommence.

Dans ce guide, nous traduisons une application Next.js (App Router) de l'espagnol vers l'anglais, le japonais, le portugais et le français avec une seule commande, npm run translate, en utilisant i18next et le paquet translate-projects-nextjs. Tout ce que vous voyez ci-dessous (fichiers et terminal) est la sortie réelle d'une exécution.

De quoi avez-vous besoin

  • Node.js 20 ou supérieur, Next.js 14+ et React 18+.
  • Un compte Translate Projects gratuit avec un projet et son jeton API (Premiers pas).
  • La clé API de votre fournisseur d'IA : Claude, OpenAI, DeepSeek ou Gemini. Il n'y a ni forfait ni carte bancaire : vous payez uniquement votre fournisseur, selon votre utilisation.

1. Installe le paquet

npm i translate-projects-nextjs

i18next et react-i18next sont installés avec le paquet.

2. Rédigez vos textes dans la langue de base

Chaque fichier JSON situé dans src/locales/<langue de base>/ est un namespace i18next, et l'imbrication est conservée. Voici le fichier de l'application d'exemple :

// src/locales/es/translation.json
{
  "nav": {
    "inicio": "Inicio",
    "precios": "Precios"
  },
  "hero": {
    "titulo": "Organiza tus tareas sin perder el ritmo",
    "subtitulo": "Planifica tu semana, comparte proyectos con tu equipo y recibe recordatorios a tiempo.",
    "boton": "Empieza gratis"
  },
  "login": {
    "email": "Correo electrónico",
    "password": "Contraseña",
    "entrar": "Iniciar sesión",
    "olvido": "¿Olvidaste tu contraseña?"
  }
}

3. Configurez les langues

Créez translate.config.mjs à la racine du projet. Le jeton est lu depuis la variable d'environnement TRANSLATE_PROJECTS_API_KEY :

export default {
  sourceLang: 'es',
  targetLangs: ['en', 'ja', 'pt-BR', 'fr'],
  apiKey: process.env.TRANSLATE_PROJECTS_API_KEY,
};

Ajoutez ensuite le script dans package.json :

{
  "scripts": {
    "translate": "translate-projects-nextjs translate"
  }
}

4. Traduis

export TRANSLATE_PROJECTS_API_KEY=tu_token
npm run translate

Sortie réelle de l'exécution (sans les horodatages) :

✅ Success: Total languages to translate: 4
ℹ️  Info: 🔄 Syncing (9) - src/locales/es/translation.json...
✅ Success: Translation completed: EN 📄 -> 📁 `src/locales/en/translation.json`
✅ Success: Translation completed: JA 📄 -> 📁 `src/locales/ja/translation.json`
✅ Success: Translation completed: PT-BR 📄 -> 📁 `src/locales/pt-BR/translation.json`
✅ Success: Translation completed: FR 📄 -> 📁 `src/locales/fr/translation.json`
✅ Success: Translation completed successfully.

Neuf textes dans quatre langues ont pris environ 14 secondes. Voici l'anglais, avec les mêmes clés :

// src/locales/en/translation.json
{
  "nav": {
    "inicio": "Home",
    "precios": "Pricing"
  },
  "hero": {
    "titulo": "Organize your tasks without losing momentum",
    "subtitulo": "Plan your week, share projects with your team and get reminders on time.",
    "boton": "Start for free"
  },
  "login": {
    "email": "Email",
    "password": "Password",
    "entrar": "Sign in",
    "olvido": "Forgot your password?"
  }
}

Et le japonais :

// src/locales/ja/translation.json
{
  "nav": {
    "inicio": "ホーム",
    "precios": "料金"
  },
  "hero": {
    "titulo": "ペースを崩さずタスクを整理しよう",
    "subtitulo": "週間計画を立て、チームとプロジェクトを共有し、期限に合わせてリマインダーを受け取れます。",
    "boton": "無料で始める"
  },
  "login": {
    "email": "メールアドレス",
    "password": "パスワード",
    "entrar": "ログイン",
    "olvido": "パスワードをお忘れですか？"
  }
}

La commande ne lit pas .env toute seule : exportez la variable dans le terminal ou en CI, ou chargez-la avec node --env-file=.env.local node_modules/.bin/translate-projects-nextjs translate.

5. Utilisez les traductions dans Next.js

Le paquet fournit aussi la partie application : un middleware qui redirige vers /<langue>/... et enregistre le cookie NEXT_LOCALE, un provider i18next, un Link localisé et des hooks avec autocomplétion des clés.

// middleware.ts
import { NextRequest } from 'next/server';
import { langMiddleware } from 'translate-projects-nextjs/middleware';

export function middleware(request: NextRequest) {
  return langMiddleware({
    request,
    defaultLocale: 'es',
    locales: ['es', 'en', 'ja', 'pt-BR', 'fr'],
  });
}
// app/[locale]/title.tsx
'use client';
import { useTypedTranslation } from 'translate-projects-nextjs/hooks';
import type es from '@/locales/es/translation.json';

export function Title() {
  const { t } = useTypedTranslation<typeof es>();
  return <h1>{t('hero.titulo')}</h1>; // las claves se autocompletan
}

Le provider (TranslationsProvider) se place dans app/[locale]/layout.tsx ; le code complet se trouve dans le guide Next.js. useTranslation et <Trans> de react-i18next fonctionnent aussi.

Comment éviter de traduire deux fois

  • Seuls les fichiers modifiés sont envoyés : une exécution sans changement ne fait qu'une seule requête.
  • Il existe un réseau partagé de traductions : si un texte a déjà été traduit dans cette langue auparavant, il arrive instantanément sans consommer votre clé d'IA.
  • Si vous supprimez un fichier généré, il est réécrit depuis le cache sans nouvelle requête.
  • Si l'API échoue, les traductions existantes sont conservées, la commande se termine avec le code 1 et ce qui manque sera retenté lors de la prochaine exécution.

Erreurs courantes

  • Jeton invalide (401) : vérifiez TRANSLATE_PROJECTS_API_KEY.
  • Missing required configuration fields: apiKey: la variable n'est pas définie dans le terminal où vous exécutez la commande.
  • Clé d'IA manquante (MISSING_API_KEY) : configurez le fournisseur, le modèle et la clé dans le projet.
  • translate.config.mjs introuvable : exécutez la commande à la racine du projet.

Il existe aussi des paquets pour React, Astro, Docusaurus (npm) et Django (PyPI). Créez votre projet gratuitement sur translateprojects.dev et traduisez votre application dès aujourd'hui.