Retour

Vous vous y prenez mal avec l’i18n dans Next.js

Team avatarTeam
Ernest McCarter avatarErnest McCarter
guideinternationalizationnextjsi18ngt-nextapp-routertutorial

L’internationalisation en JavaScript a fini par adopter une convention bancale : extraire chaque chaîne de caractères visible par l’utilisateur dans un fichier JSON, lui attribuer une clé, puis référencer cette clé dans vos composants. t('home.hero.title') au lieu du texte lui-même. Votre UI se trouve à un endroit, votre contenu à un autre.

Ça fonctionne. Des milliers d’applications sont livrées comme ça. Mais ce n’est pas une très bonne expérience développeur.

Lire t('checkout.summary.total') dans une revue de code ne vous apprend rien — vous devez ouvrir un fichier JSON pour voir ce qui a changé. Il faut inventer les clés, les organiser en espaces de noms et les garder synchronisées. Les traductions obsolètes s’accumulent parce que personne ne sait quelles clés sont encore utilisées. Le problème est suffisamment répandu que des catégories entières d’outils existent uniquement pour le gérer : des extensions d’IDE qui suggèrent automatiquement des clés, des générateurs de types qui les valident, des linters qui signalent celles qui ne sont plus utilisées. Ces outils résolvent un problème créé par un paradigme mal conçu.

Le composant <T>

Le contenu ne doit pas être dissocié de l’endroit où il est utilisé. Un composant qui affiche un titre, un paragraphe et un bouton doit être l’unique source de vérité pour le texte de ces éléments — pas un intermédiaire qui renvoie vers des chaînes de caractères stockées ailleurs. Lorsque votre code et vos traductions forment deux systèmes parallèles, ils finissent par diverger. Inévitablement.

Et si la bibliothèque fonctionnait à l’inverse — en s’adaptant à votre code au lieu de vous demander de le restructurer ? Voici à quoi devrait ressembler l’i18n.

import { T } from 'gt-next';

function Hero() {
  return (
    <T>
      <h1>Ship your product worldwide</h1>
      <p>Reach every market without rewriting your app.</p>
    </T>
  );
}

Entourez votre JSX avec <T>. Le texte anglais reste exactement là où vous l’avez écrit. Quand un utilisateur consulte la page en espagnol ou en japonais, le contenu à l’intérieur de <T> est traduit — structure, mise en forme, tout compris.

Aucune clé. Aucun fichier JSON. Aucun renvoi croisé. Votre code est la source de vérité.

Configuration

La syntaxe ci-dessus provient de gt-next, une bibliothèque d’i18n open source pour le routeur d’application de Next.js. Pour commencer, une seule commande suffit :

npx gt@latest init

L’assistant de configuration installe les dépendances, intègre withGTConfig à votre configuration Next.js, ajoute GTProvider à votre layout racine, crée un gt.config.json avec vos paramètres régionaux, configure les clés API de développement pour le rechargement à chaud des traductions et configure le stockage des traductions sur le CDN — le tout de manière interactive.

Une fois cela fait, entourez le contenu de <T>, lancez votre serveur de développement et utilisez le composant <LocaleSelector> pour passer d’une langue à l’autre :

import { LocaleSelector } from 'gt-next';

function Header() {
  return (
    <header>
      <nav>{/* ... */}</nav>
      <LocaleSelector />
    </header>
  );
}

Les traductions sont effectuées on-demand en développement, ce qui vous permet de voir immédiatement votre application dans n’importe quelle langue.

Déploiement

En production, les traductions sont générées à l’avance.

  1. Récupérez une clé API de production sur dash.generaltranslation.com. Les clés de production commencent par gtx-api- (contrairement aux clés gtx-dev- utilisées en local).

  2. Ajoutez l’étape translate à votre build :

{
  "scripts": {
    "build": "npx gt translate --publish && next build"
  }
}

La commande translate analyse votre base de code pour repérer toutes les utilisations de <T>, génère les traductions et les publie sur un CDN. Au moment de la compilation de votre application, chaque paramètre régional est prêt.

Prochaines étapes