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

Alors que le monde devient de plus en plus globalisé, il est de plus en plus important pour les développeurs web de créer des applications qui peuvent répondre aux besoins des utilisateurs de différents pays et cultures. L'un des moyens clés d'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 allons explorer comment ajouter l'internationalisation à votre application React Next.js, avec le rendu côté serveur. TL;DR: Voir l'exemple complet ici.

Ce guide s'applique aux applications Next.js utilisant le App Router.
Si vous utilisez le Pages Router, consultez plutôt ce guide.

Étape 1 : Installer une bibliothèque i18n

Pour mettre en œuvre l'internationalisation dans votre application Next.js, nous allons d'abord choisir une bibliothèque i18n. Il existe plusieurs bibliothèques populaires, y compris next-intl. Dans cet exemple, cependant, nous allons utiliser TacoTranslate.

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

Installons-le en utilisant npm dans votre terminal :

npm install tacotranslate

Étape 2 : Créez un compte gratuit TacoTranslate

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 vous oblige pas à ajouter une carte de crédit.

Dans l'interface utilisateur de l'application TacoTranslate, créez un projet et accédez à son onglet 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 est ce que nous appelons public et la clé read/write est secret. Par exemple, vous pourriez les ajouter à un fichier .env à la racine de votre projet.

TACOTRANSLATE_PUBLIC_API_KEY=123456
TACOTRANSLATE_SECRET_API_KEY=789010

Assurez-vous de ne jamais divulguer la clé API secrète read/write aux environnements de production côté client.

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

• TACOTRANSLATE_DEFAULT_LOCALE: Le code de langue par défaut. Dans cet exemple, nous allons le définir 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

Pour intégrer TacoTranslate à votre application, vous devrez créer un client en utilisant les clés API mentionnées précédemment. Par exemple, créez un fichier nommé /utilities/tacotranslate.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.

Créer le client dans un fichier séparé facilite sa réutilisation ultérieure. getLocales est simplement une fonction utilitaire avec quelques gestions d'erreurs intégrées. Maintenant, créez un fichier nommé /components/tacotranslate.tsx, où nous allons mettre en œuvre le fournisseur TacoTranslate.

'use client';

import React, {type ReactNode} from 'react';
import ImportedTacoTranslate, {
	type TranslationContextProperties,
} from 'tacotranslate/react';
import tacoTranslate from '@/utilities/tacotranslate';

export default function TacoTranslate({
	locale,
	origin,
	localizations,
	children,
}: TranslationContextProperties & {
	readonly children: ReactNode;
}) {
	return (
		<ImportedTacoTranslate
			client={tacoTranslate}
			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 à l'emploi, créez un fichier nommé /app/[locale]/layout.tsx, la mise en page racine de notre application. Notez que ce chemin contient un dossier utilisant Dynamic Routes, où [locale] est le paramètre dynamique.

import React, {type ReactNode} from 'react';
import {isRightToLeftLocaleCode} from 'tacotranslate';
import './global.css';
import tacoTranslate from '@/utilities/tacotranslate';
import TacoTranslate from '@/components/tacotranslate';
import {customGenerateMetadata} from '@/utilities/generate-metadata';

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

type RootLayoutParameters = {
	readonly params: {locale: string};
	readonly children: ReactNode;
};

export default async function RootLayout({
	params: {locale},
	children,
}: RootLayoutParameters) {
	const origins = [process.env.TACOTRANSLATE_ORIGIN];
	const direction = isRightToLeftLocaleCode(locale) ? 'rtl' : 'ltr';
	const localizations = await tacoTranslate.getLocalizations({locale, origins});

	return (
		<html lang={locale} dir={direction}>
			<body>
				<TacoTranslate
					locale={locale}
					origin={origin}
					localizations={localizations}
				>
					<div id="content">{children}</div>
				</TacoTranslate>
			</body>
		</html>
	);
}

La première chose à noter ici est que nous utilisons notre Dynamic Route paramètre [locale] pour récupérer les traductions pour cette langue. De plus, generateStaticParams s'assure que tous les codes de locale 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 garder 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 flash de contenu non traduit au début. De plus, nous pouvons ignorer les requêtes réseau côté client, car nous avons déjà les traductions dont nous avons besoin pour la page que l'utilisateur consulte.

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

const tacoTranslate = require('./utilities/tacotranslate');

module.exports = async () => {
	const locales = await tacoTranslate.getLocales();
	const isProduction =
		process.env.TACOTRANSLATE_ENV === 'production' ||
		process.env.VERCEL_ENV === 'production' ||
		(!(process.env.TACOTRANSLATE_ENV || process.env.VERCEL_ENV) &&
			process.env.NODE_ENV === 'production');

	const [projectLocale] = locales;

	return {
		env: {
			TACOTRANSLATE_ORIGIN: process.env.TACOTRANSLATE_ORIGIN,
			TACOTRANSLATE_API_KEY: isProduction
				? process.env.TACOTRANSLATE_PUBLIC_API_KEY
				: process.env.TACOTRANSLATE_SECRET_API_KEY,
			TACOTRANSLATE_PROJECT_LOCALE: projectLocale,
			TACOTRANSLATE_PROJECT_LOCALES: JSON.stringify(locales),
			TACOTRANSLATE_IS_PRODUCTION: String(isProduction),
		},
	};
};

Il y a quelques points à noter ici. Tout d'abord, nous récupérons toutes les langues que vous avez activées pour votre projet de traduction. La première chaîne dans ce tableau de réponses sera le code de locale d'origine que vous avez défini pour le projet lors de sa création.

Maintenant pour la partie cruciale : Décider si nous sommes ou non dans un environnement de production. Modifiez la vérification isProduction pour l’adapter à votre configuration. Si nous sommes dans un environnement local, de test ou de staging, nous devrions utiliser la clé API secrète read/write pour nous assurer que les nouvelles chaînes sont envoyées pour traduction. Si nous sommes dans un environnement de production, nous devrions utiliser la clé publique [[[read]].

Pour s'assurer 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 '@/utilities/tacotranslate';

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 Middleware de Next.js.

Sur le client, vous pouvez modifier le locale cookie 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 faire cela !

Étape 5 : Déployez et testez !

Nous avons terminé ! Votre application React sera maintenant traduite automatiquement lorsque vous ajouterez des chaînes à un Translate composant. Notez que seulement les environnements avec 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 clé API comme celle-ci, en ajoutant de nouvelles chaînes avant de passer en production. Cela empêchera quiconque de voler votre clé API secrète et pourrait éviter l'enflure de votre projet de traduction en ajoutant de nouvelles chaînes non liées.

Assurez-vous de consulter l'exemple complet sur notre profil GitHub. Là, vous trouverez également un exemple de comment faire cela en utilisant le Pages Router! Si vous rencontrez des problèmes, n'hésitez pas à nous contacter, et nous serons plus qu'heureux de vous aider.

TacoTranslate vous permet de localiser automatiquement vos applications React rapidement vers et depuis n'importe quelle langue. Commencez aujourd'hui!