Présentation
Présentation du SDK Next.js de General Translation
Introduction
Le SDK Next.js de General Translation est une bibliothèque open source d’internationalisation (i18n) pour les applications Next.js.
Il propose un ensemble complet d’outils pour internationaliser votre application Next.js de façon simple et maintenable, avec une parité fonctionnelle par rapport aux autres bibliothèques i18n populaires. Reposant sur le React SDK, il offre en plus des fonctionnalités spécifiques à Next.js.
Le SDK peut être utilisé de manière autonome, sans la plateforme General Translation, et se comporte comme les autres bibliothèques i18n.
Il s’intègre toutefois à notre plateforme pour des fonctionnalités avancées :
- Rechargement à chaud des traductions en développement
- Traductions automatiques par IA
- Synchronisation des traductions avec la plateforme General Translation
- Intégration native avec notre CDN de traduction (Content Delivery Network)
- Traduction à la demande des composants React en production (côté serveur)
Concepts
Il existe 6 concepts clés à connaître sur le SDK.
Initialisation avec withGTConfig
Le composant <GTProvider>
Le composant <T>
Le hook useGT
La fonction msg pour les chaînes partagées
(Optionnel) Le hook useTranslations
Initialisation avec withGTConfig
La fonction withGTConfig initialise le SDK dans votre application Next.js.
Ajoutez-la à votre fichier next.config.[js|ts] pour configurer le SDK :
import { withGTConfig } from 'gt-next/config';
const nextConfig = {
// Vos options next.config.ts
};
export default withGTConfig(nextConfig, {
// Votre configuration GT
});Consultez la Référence de l’API withGTConfig pour en savoir plus.
Le composant <GTProvider>
Le composant <GTProvider> fournit le contexte de traduction à votre application, notamment la langue en cours et les traductions associées.
import { GTProvider } from 'gt-next';
export default function RootLayout({ children }) {
return (
<html>
<body>
<GTProvider>
{children}
</GTProvider>
</body>
</html>
);
}Important : Le provider doit envelopper l’ensemble de votre application et être placé aussi haut que possible dans l’arborescence des composants, par exemple dans le layout racine.
Le provider n’est requis que pour les fonctionnalités côté client. Les applications exclusivement côté serveur n’en ont pas besoin, mais il peut tout de même être inclus.
Consultez la Référence de l’API de GTProvider pour plus d’informations.
Le composant <T>
Le composant <T> est la méthode recommandée pour traduire le contenu de votre application.
C’est un composant React qui peut encapsuler n’importe quel élément JSX et qui rendra automatiquement le contenu de l’élément dans une langue prise en charge.
Exemples
<T>
<div>Bonjour le monde !</div>
</T><T>
<div>
<h1> Voici une image </h1>
<img src="https://example.com/image.png" alt="Exemple" />
</div>
</T><T>
Le formatage peut être effectué facilement avec le composant `<T>`.
<Num>{1000}</Num>
<DateTime>{new Date()}</DateTime>
<Currency currency="USD">{1000}</Currency>
</T>Le composant <T> fonctionne avec des composants variables comme <Num>, <DateTime> et <Currency> pour le formatage dynamique du contenu.
Consultez le guide du composant <T> pour découvrir les différentes façons d’utiliser le composant <T>.
Le hook useGT
Le hook useGT est un hook React qui s’utilise de façon similaire au composant <T>, avec quelques compromis.
Ce hook retourne une fonction permettant de traduire des chaînes.
const t = useGT();
t('Bonjour le monde !');Par rapport au composant <T>, le hook useGT offre davantage de flexibilité dans votre codebase.
Par exemple, si vous avez une structure de données complexe avec des chaînes imbriquées, il serait plus difficile d’utiliser un composant <T>.
const t = useGT();
const data = {
title: t('Bonjour le monde !'),
description: t('Ceci est une description'),
};Consultez le guide des chaînes pour en savoir plus sur le hook useGT.
La fonction msg
La fonction msg sert à marquer pour traduction les chaînes utilisées dans plusieurs composants ou stockées dans des objets de configuration.
Elle est particulièrement utile pour le contenu partagé, comme les libellés de navigation, les messages de formulaire ou tout texte apparaissant à plusieurs endroits dans votre application.
// Marquer les chaînes pour la traduction
import { msg } from 'gt-next';
const navItems = [
{ label: msg('Accueil'), href: '/' },
{ label: msg('À propos'), href: '/about' },
{ label: msg('Contact'), href: '/contact' }
];// Décoder et utiliser les chaînes marquées
import { useMessages } from 'gt-next';
function Navigation() {
const m = useMessages();
return (
<nav>
{navItems.map(item => (
<a key={item.href} href={item.href}>
{m(item.label)}
</a>
))}
</nav>
);
}La fonction msg encode des chaînes avec des métadonnées de traduction, et useMessages (ou getMessages pour les composants serveur) les décode.
Consultez le guide chaînes partagées pour en savoir plus sur la fonction msg.
Le hook useTranslations
Le hook useTranslations est un hook React qui retourne une fonction permettant de récupérer les traductions associées à une clé donnée.
const dictionary = {
hello: {
world: 'Bonjour le monde !',
},
};const translate = useTranslations();
translate('bonjour.monde');Ce comportement est similaire à d’autres bibliothèques de traduction, comme react-i18next et next-intl.
Nous déconseillons d’utiliser le hook useTranslations dans votre application. Un recours fréquent à useTranslations rendra votre codebase plus difficile à maintenir
et entraînera une dette technique importante.
Nous recommandons plutôt d’utiliser le composant <T> ou le hook useGT.
Si vous migrez depuis une autre bibliothèque i18n, le hook useTranslations est un remplacement plug-and-play et peut être utile pour migrer votre codebase de manière progressive.
Consultez le guide dictionaries pour en savoir plus sur le hook useTranslations.
Consultez la Référence de l’API useTranslations pour plus d’informations.
Prochaines étapes
- Découvrez comment configurer votre projet Next.js avec le SDK : Démarrage rapide
- Découvrez comment traduire du contenu JSX avec le composant
<T>: Guide de traduction JSX - Découvrez comment traduire des chaînes avec le hook
useGT: Guide de traduction des chaînes - Découvrez les chaînes partagées avec la fonction
msg: Guide des chaînes partagées
Que pensez-vous de ce guide ?