Comment configurer Better i18n avec Next.js ?

Le package `@better-i18n/next` s'intègre au App Router de Next.js et ajoute la récupération de messages via CDN avec support ISR. Configurez-le en quelques étapes.

8 min de lectureIntermédiaire

Le package @better-i18n/next s'intègre au App Router de Next.js et utilise next-intl en arrière-plan. Il ajoute la récupération de messages via CDN avec support ISR.

Installation

bun add @better-i18n/next next-intl

Étape 1 : Créer la configuration i18n

Créez src/i18n.ts :

import { createI18n } from '@better-i18n/next';

export const i18n = createI18n({
  project: 'acme/dashboard',
  defaultLocale: 'en',
  localePrefix: 'as-needed', // 'always' | 'as-needed' | 'never'
  manifestRevalidateSeconds: 3600, // ISR : revalider la liste des locales toutes les heures
  messagesRevalidateSeconds: 30,   // ISR : revalider les messages toutes les 30s
});

Options de préfixe de locale

Option	URL de la locale par défaut	URL des autres locales
`as-needed`	`/about`	`/tr/about`
`always`	`/en/about`	`/tr/about`
`never`	`/about`	`/about` (locale depuis cookie/en-tête)

Étape 2 : Configurer la config de requête

Créez src/i18n/request.ts :

import { i18n } from '@/i18n';

export default i18n.requestConfig;

Cela indique à next-intl comment charger les messages pour chaque requête. En arrière-plan, il récupère depuis le CDN Better i18n avec mise en cache ISR.

Étape 3 : Ajouter le middleware

Créez src/middleware.ts :

import { i18n } from '@/i18n';

export default i18n.betterMiddleware();

export const config = {
  matcher: ['/((?!api|_next|.*\\..*).*)'],
};

Le middleware :

Détecte la locale préférée de l'utilisateur depuis l'en-tête Accept-Language
Redirige vers le préfixe de locale approprié
Définit l'en-tête x-better-locale pour utilisation en aval

Étape 4 : Ajouter le provider

Dans votre layout racine (src/app/[locale]/layout.tsx) :

import { NextIntlClientProvider } from 'next-intl';
import { getMessages } from 'next-intl/server';

export default async function LocaleLayout({
  children,
  params: { locale },
}) {
  const messages = await getMessages();

  return (
    <html lang={locale}>
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}

Étape 5 : Utiliser les traductions

import { useTranslations } from 'next-intl';

export function WelcomeBanner() {
  const t = useTranslations('common');

  return (
    <div>
      <h1>{t('welcome_title')}</h1>
      <p>{t('welcome_description')}</p>
    </div>
  );
}

Variables d'environnement

# .env.local
BETTER_I18N_PROJECT=acme/dashboard

La clé publique est intégrée dans le SDK — aucune clé API n'est nécessaire pour l'accès CDN en lecture seule.

Comment fonctionne la mise en cache ISR

Le SDK crée deux instances createI18nCore internes :

Manifest core — récupère les locales disponibles, revalide toutes les manifestRevalidateSeconds (défaut : 3600s)
Messages core — récupère les traductions, revalide toutes les messagesRevalidateSeconds (défaut : 30s)

Cela signifie qu'après avoir publié de nouvelles traductions, votre application Next.js les récupère en ~30 secondes sans reconstruction.

Prochaines étapes

Cet article vous a-t-il été utile ?

Comment configurer le CLI et scanner mon projet ?