Next.js

Le paquet translate-projects-nextjs comporte deux parties : une commande qui traduit vos fichiers JSON et des utilitaires pour les utiliser dans Next.js (App Router) : middleware de langue, provider i18next, Link et hooks avec saisie semi-automatique.

Prérequis

• Node.js 20 ou supérieur.
• Next.js 14 ou supérieur et React 18 ou supérieur. Ce sont des dépendances peer : le paquet utilise celles de votre projet.
• Un projet et un token API de Translate Projects. Consulte Premiers pas.

1. Installe le paquet

Terminal

npm i translate-projects-nextjs

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

2. Écris tes textes

Placez les textes de la langue de base dans src/locales/<langue de base>/. Chaque fichier JSON (y compris dans les sous-dossiers) est un namespace i18next et l'imbrication est conservée :

src/locales/es/translation.json

{
  "home": {
    "title": "Bienvenido"
  }
}

3. Configure la traduction

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

translate.config.mjs

export default {
  sourceLang: 'es', // Langue de base : la langue par défaut du projet
  targetLangs: ['en', 'pt-BR', 'fr'], // Langues à générer
  apiKey: process.env.TRANSLATE_PROJECTS_API_KEY,
  // outputDir: './src/locales', // Valeur par défaut
  // scanner: true, // Facultatif : extrait t('...') et <Trans> de ./src
};

Ajoute le script dans package.json :

package.json

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

4. Traduis

Terminal

export TRANSLATE_PROJECTS_API_KEY=tu_token
npm run translate

La commande ne lit pas les fichiers .env par elle-même : exportez la variable dans le terminal ou dans la CI, ou chargez-la vous-même, par exemple avec node --env-file=.env.local node_modules/.bin/translate-projects-nextjs translate. Elle se termine avec le code 0 si toutes les langues ont été traduites et avec 1 en cas d'erreur.

Fichiers générés

src/locales/
├── es/translation.json   ← votre langue de base
├── en/translation.json   ← généré
├── pt-BR/translation.json
└── fr/translation.json

Commitez les fichiers générés : l'application les importe au moment de la compilation. Ne les modifiez pas à la main, ils sont écrasés à la prochaine exécution. Avec le scanner activé, <langue de base>/translation.json est aussi écrasé avec les textes trouvés dans le code.

5. Utilisez les traductions dans Next.js

Middleware

Redirige vers /<langue>/... et enregistre la langue dans le cookie NEXT_LOCALE. Les routes /_next, /api, /locales et /favicon.ico sont toujours ignorées.

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', 'pt-BR', 'fr'],
    ignorePaths: ['/images'], // Facultatif
  });
}

Provider

app/[locale]/layout.tsx

import { TranslationsProvider } from 'translate-projects-nextjs/provider';
import es from '@/locales/es/translation.json';
import en from '@/locales/en/translation.json';

export default async function Layout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise<{ locale: string }>;
}) {
  const { locale } = await params;

  return (
    <html lang={locale}>
      <body>
        <TranslationsProvider
          lng={locale as any}
          initialLocale={locale as any}
          i18nConfig={{
            fallbackLng: ['es'],
            supportedLngs: ['es', 'en'],
            resources: {
              es: { translation: es },
              en: { translation: en },
            },
          }}
        >
          {children}
        </TranslationsProvider>
      </body>
    </html>
  );
}

Textes avec saisie semi-automatique

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('home.title')}</h1>; // Les clés sont complétées automatiquement
}

useTranslation et <Trans> de react-i18next fonctionnent aussi.

Navigation

app/[locale]/nav.tsx

'use client';
import { Link } from 'translate-projects-nextjs/link';
import { useLocalizedRouter } from 'translate-projects-nextjs/hooks';

export function Nav() {
  const router = useLocalizedRouter();
  return (
    <>
      <Link href="/about">About</Link> {/* -> /<locale>/about */}
      <button onClick={() => router.push('/', undefined, 'en')}>English</button>
    </>
  );
}

Cache et forçage

Les fichiers sans modification ne sont ni envoyés ni retraduits : une exécution sans modification ne fait qu'une seule requête. Si vous supprimez un fichier généré, il est réécrit à partir du cache sans nouvelle requête. Ce paquet n'a pas de --force : pour tout retraduire, supprimez ~/.config/translate-projects-core/cache.json (cela affecte tous les projets de l'équipe, chacun se synchronise une fois) puis relancez la commande. Plus de détails dans Cache et erreurs.

Erreurs courantes

Si l'API échoue ou renvoie un résultat partiel, les traductions existantes sont conservées, la commande se termine avec le code 1 et les textes manquants sont retentés lors de la prochaine exécution.

• Jeton invalide (401): vérifiez TRANSLATE_PROJECTS_API_KEY.
• Clé d'IA manquante (MISSING_API_KEY): configurez le fournisseur, le modèle et la clé dans le projet. En attendant, les textes non traduits ne sont pas écrits dans le fichier et i18next affiche le texte de fallbackLng.
• Missing required configuration fields: apiKey: la variable TRANSLATE_PROJECTS_API_KEY n'est pas définie dans le terminal où vous exécutez la commande.
• translate.config.mjs introuvable: la commande doit être exécutée à la racine du projet.
• Conflit de dépendances lors de l'installation: vérifiez que votre projet utilise Next.js 14 ou supérieur et React 18 ou supérieur.

Gratuit

🚀 Automatisez vos traductions gratuitement

Translate Projects est gratuit. Vous créez votre projet, connectez la clé de votre fournisseur d'IA et ne lui payez que ce que vous dépensez.

• Sans forfaits ni carte de crédit: Toutes les fonctionnalités sont disponibles dès le premier jour.
• Utilisez votre propre IA: Claude, OpenAI, DeepSeek ou Gemini. Votre clé est stockée chiffrée.
• Réseau de traductions partagé: Si un texte a déjà été traduit, vous le recevez instantanément sans dépenser votre clé.
• Panneau d'administration: Vérifiez et modifiez toutes vos traductions depuis un seul endroit.

Créer un compte gratuitement →

Support

Nous sommes là pour vous aider

Si vous avez des questions, besoin d'aide ou souhaitez contribuer, n'hésitez pas à me contacter. Je suis à votre disposition pour vous soutenir dans tout ce dont vous avez besoin.

• Site web: neiderruiz.com
• GitHub: @neiderruiz
• Twitter: @neiderruiz
• YouTube: Neider Ruiz

Soutenez le projet

Si ce projet vous a été utile, je vous invite à m'offrir un café. Votre soutien m'aide à continuer de m'améliorer et à créer du contenu de valeur. Merci d'être là ! ☕