Comment implémenter l'internationalisation dans une application Next.js utilisant le App Router

À mesure que le monde se mondalise, il devient de plus en plus important pour les développeurs web de créer des applications capables de s’adapter aux utilisateurs de différents pays et cultures. L’un des moyens clés pour y parvenir est l’internationalisation (i18n), qui vous permet d’adapter votre application à différentes langues, devises et formats de date.

Dans cet article, nous explorerons comment ajouter l’internationalisation à votre application React Next.js, avec rendu côté serveur. TL;DR: Voir l’exemple complet ici.

Ce guide est destiné aux applications Next.js qui utilisent le App Router.
Si vous utilisez le Pages Router, consultez plutôt ce guide.

Étape 1 : Installer une bibliothèque i18n

Pour implémenter l'internationalisation dans votre application Next.js, nous allons d'abord choisir une bibliothèque i18n. Il existe plusieurs bibliothèques populaires, notamment next-intl. Dans cet exemple, cependant, nous utiliserons TacoTranslate.

TacoTranslate traduit automatiquement vos chaînes dans n'importe quelle langue en utilisant une intelligence artificielle de pointe, et vous libère de la gestion fastidieuse des fichiers JSON.

Installons-le avec npm dans votre terminal :

npm install tacotranslate

Étape 2 : Créez un compte TacoTranslate gratuit

Maintenant que vous avez installé le module, il est temps de créer votre compte TacoTranslate, un projet de traduction, et les clés API associées. Créez un compte ici. C’est gratuit, et ne nécessite pas d’ajouter une carte de crédit.

Dans l'interface utilisateur de l'application TacoTranslate, créez un projet, puis accédez à son onglet des clés API. Créez une clé read et une clé read/write. Nous les enregistrerons en tant que variables d'environnement. La clé read correspond à ce que nous appelons public et la clé read/write est secret. Par exemple, vous pouvez les ajouter dans un fichier .env à la racine de votre projet.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Veillez à ne jamais divulguer la clé API secrète read/write dans les environnements de production côté client.

Nous allons également ajouter deux autres variables d'environnement : TACOTRANSLATE_DEFAULT_LOCALE et TACOTRANSLATE_ORIGIN.

• TACOTRANSLATE_DEFAULT_LOCALE : Le code de la locale par défaut utilisée en cas de repli. Dans cet exemple, nous le définirons sur en pour l’anglais.
• TACOTRANSLATE_ORIGIN : Le « dossier » où vos chaînes seront stockées, comme l’URL de votre site web. En savoir plus sur les origines ici.

TACOTRANSLATE_DEFAULT_LOCALE=en
TACOTRANSLATE_ORIGIN=your-website-url.com

Étape 3 : Configuration de TacoTranslate

To integrate TacoTranslate with your application, you’ll need to create a client using the API keys from earlier. For example, create a file named /tacotranslate-client.js.

const {default: createTacoTranslateClient} = require('tacotranslate');

const tacoTranslate = createTacoTranslateClient({
	apiKey:
		process.env.TACOTRANSLATE_SECRET_API_KEY ??
		process.env.TACOTRANSLATE_PUBLIC_API_KEY ??
		process.env.TACOTRANSLATE_API_KEY,
	projectLocale:
		process.env.TACOTRANSLATE_IS_PRODUCTION === 'true'
			? process.env.TACOTRANSLATE_PROJECT_LOCALE
			: undefined,
});

module.exports = tacoTranslate;

Nous définirons automatiquement TACOTRANSLATE_API_KEY et TACOTRANSLATE_PROJECT_LOCALE sous peu.

La création du client dans un fichier séparé permet de l’utiliser à nouveau facilement par la suite. getLocales s’agit simplement d’une fonction utilitaire avec une gestion intégrée des erreurs. Maintenant, créez un fichier nommé /app/[locale]/tacotranslate.tsx, dans lequel nous allons implémenter le fournisseur de TacoTranslate .

'use client';

import React, {type ReactNode} from 'react';
import {
	type TranslationContextProperties,
	TacoTranslate as ImportedTacoTranslate,
} from 'tacotranslate/react';
import tacoTranslateClient from '@/tacotranslate-client';

export default function TacoTranslate({
	locale,
	origin,
	localizations,
	children,
}: TranslationContextProperties & {
	readonly children: ReactNode;
}) {
	return (
		<ImportedTacoTranslate
			client={tacoTranslateClient}
			locale={locale}
			origin={origin}
			localizations={localizations}
		>
			{children}
		</ImportedTacoTranslate>
	);
}

Notez le 'use client'; indiquant qu'il s'agit d'un composant client.

Avec le fournisseur de contexte maintenant prêt, créez un fichier nommé /app/[locale]/layout.tsx, la mise en page racine de notre application. Notez que ce chemin comprend un dossier utilisant Dynamic Routes, où [locale] est le paramètre dynamique.

import React, {type ReactNode} from 'react';
import {type Locale, isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslateClient from '@/tacotranslate-client';
import TacoTranslate from './tacotranslate';

export async function generateStaticParams() {
	const locales = await tacoTranslateClient.getLocales();
	return locales.map((locale) => ({locale}));
}

type RootLayoutParameters = {
	readonly params: Promise<{locale: Locale}>;
	readonly children: ReactNode;
};

export default async function RootLayout({params, children}: RootLayoutParameters) {
	const {locale} = await params;
	const origin = process.env.TACOTRANSLATE_ORIGIN;
	const localizations = await tacoTranslateClient.getLocalizations({
		locale,
		origins: [origin /* , other origins to fetch */],
	});

	return (
		<html lang={locale} dir={isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr'}>
			<body>
				<TacoTranslate
					locale={locale}
					origin={origin}
					localizations={localizations}
				>
					{children}
				</TacoTranslate>
			</body>
		</html>
	);
}

La première chose à noter ici est que nous utilisons notre paramètre Dynamic Route [locale] pour récupérer les traductions de cette langue. De plus, generateStaticParams s'assure que tous les codes de langue que vous avez activés pour votre projet sont pré-rendus.

Maintenant, construisons notre première page ! Créez un fichier nommé /app/[locale]/page.tsx.

import React from 'react';
import {Translate} from 'tacotranslate/react';

export const revalidate = 60;
export default async function Page() {
	return (
		<Translate string="Hello, world!" />
	);
}

Notez la variable revalidate qui indique à Next.js de reconstruire la page après 60 secondes, et de maintenir vos traductions à jour.

Étape 4 : Mise en œuvre du rendu côté serveur

TacoTranslate prend en charge le rendu côté serveur. Cela améliore considérablement l'expérience utilisateur en affichant immédiatement le contenu traduit, au lieu d'un bref affichage de contenu non traduit. De plus, nous pouvons éviter les requêtes réseau côté client, car nous disposons déjà des traductions nécessaires pour la page que l'utilisateur consulte.

Pour configurer le rendu côté serveur, créez ou modifiez /next.config.js:

const withTacoTranslate = require('tacotranslate/next/config').default;
const tacoTranslateClient = require('./tacotranslate-client');

module.exports = async () => {
	const config = await withTacoTranslate(
		{},
		{
			client: tacoTranslateClient,
			isProduction:
				process.env.TACOTRANSLATE_ENV === 'production' ||
				process.env.VERCEL_ENV === 'production' ||
				(!(process.env.TACOTRANSLATE_ENV || process.env.VERCEL_ENV) &&
					process.env.NODE_ENV === 'production'),
		}
	);

	// NOTE: Remove i18n from config when using the app router
	return {...config, i18n: undefined};
};

Modifiez la vérification de l' isProduction en fonction de votre configuration. Si true, TacoTranslate affichera la clé API publique. Si nous sommes dans un environnement local, de test ou de test (isProduction is false), nous utiliserons la clé API secrète read/write pour nous assurer que les nouvelles chaînes sont envoyées pour traduction.

Pour garantir que le routage et la redirection fonctionnent comme prévu, nous devrons créer un fichier nommé /middleware.ts. En utilisant Middleware, nous pouvons rediriger les utilisateurs vers des pages présentées dans leur langue préférée.

import {type NextRequest} from 'next/server';
import {middleware as tacoTranslateMiddleware} from 'tacotranslate/next';
import tacoTranslate from '@/tacotranslate-client';

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

export async function middleware(request: NextRequest) {
	return tacoTranslateMiddleware(tacoTranslate, request);
}

Assurez-vous de configurer le matcher conformément à la documentation de Next.js Middleware.

Côté client, vous pouvez modifier le cookie locale pour changer la langue préférée de l’utilisateur. Veuillez consulter le code d’exemple complet pour des idées sur la façon de le faire !

Étape 5 : Déployer et tester !

Nous avons terminé ! Votre application React sera désormais traduite automatiquement lorsque vous ajouterez des chaînes dans un composant Translate. Notez que seuls les environnements disposant des permissions read/write sur la clé API pourront créer de nouvelles chaînes à traduire. Nous recommandons d'avoir un environnement de staging fermé et sécurisé où vous pouvez tester votre application de production avec une telle clé API, en ajoutant de nouvelles chaînes avant la mise en ligne. Cela empêchera quiconque de voler votre clé API secrète et de potentiellement gonfler votre projet de traduction en ajoutant de nouvelles chaînes non liées.

Assurez-vous de consulter l'exemple complet sur notre profil GitHub. Vous y trouverez également un exemple de la façon de faire cela en utilisant le Pages Router ! Si vous rencontrez des problèmes, n'hésitez pas à nous contacter, nous serons ravis de vous aider.

TacoTranslate vous permet de localiser automatiquement vos applications React rapidement dans toutes les langues et en provenance de celles-ci. Commencez dès aujourd'hui !