Présentation
Présentation du SDK Next.js de General Translation
Introduction
Le SDK Next.js de General Translation est une bibliothèque d’internationalisation (i18n) open source pour les applications Next.js.
Il fournit un ensemble complet d’outils pour internationaliser votre application Next.js de manière simple et facile à maintenir, avec une parité fonctionnelle par rapport aux autres bibliothèques i18n populaires. Construit sur le React SDK, il offre des fonctionnalités supplémentaires propres à Next.js.
Le SDK peut être utilisé de manière autonome, sans la plateforme General Translation, et se comporte de façon similaire aux 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 (réseau de diffusion de contenu)
- Traduction à la demande de composants React en production (côté serveur)
Concepts
Six concepts principaux sont à connaître concernant le SDK.
Initialisation avec withGTConfig
Le composant <GTProvider>
Le composant <T>
Le hook useGT
La fonction msg pour les chaînes partagées
(Facultatif) 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
});Voir la Référence de l’API withGTConfig pour plus d’informations.
Le composant <GTProvider>
Le composant <GTProvider> fournit le contexte de traduction à votre application, y compris la langue actuelle 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 votre layout racine.
Le provider n’est requis que pour les fonctionnalités côté client. Les applications uniquement 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 rendra automatiquement le contenu de l’élément dans une langue prise en charge.
Nous recommandons d’utiliser le composant <T> autant que possible, car il offre la plus grande flexibilité pour les traductions.
Contrairement aux chaînes de caractères, le composant <T> peut être utilisé pour traduire du contenu HTML, ce qui le rend bien plus puissant que les traductions basées sur des chaînes.
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 de variables comme <Num>, <DateTime> et <Currency> pour formater dynamiquement le contenu.
Consultez le guide du composant <T> pour découvrir les différentes manières d’utiliser le composant <T>.
Le hook useGT
Le hook useGT est un hook React qui peut s’utiliser de manière similaire au composant <T>, avec quelques compromis.
Ce hook renvoie une fonction qui peut être utilisée pour traduire des chaînes.
const t = useGT();
t('Bonjour, 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, monde !'),
description: t('Ceci est une description'),
};Consultez le guide strings pour en savoir plus sur le hook useGT.
La fonction msg
La fonction msg sert à marquer pour traduction des 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 de caractères 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 renvoie une fonction permettant de récupérer les traductions associées à une clé donnée.
const dictionary = {
hello: {
world: 'Bonjour, monde !',
},
};const translate = useTranslations();
translate('hello.world');Ce comportement est similaire à celui d’autres bibliothèques de traduction, comme react-i18next et next-intl.
Nous déconseillons d’utiliser le hook useTranslations dans votre application. Un usage fréquent de useTranslations rendra votre codebase plus difficile à maintenir
et générera 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 à l’identique et peut faciliter une migration progressive de votre codebase.
Consultez le guide dictionaries pour en savoir plus sur le hook useTranslations.
Consultez la Référence de l’API useTranslations pour en savoir plus.
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
Comment trouvez-vous ce guide ?