Atelier du Tuning est disponible en français, anglais, espagnol et allemand. L'interface repose sur next-intl et quatre fichiers messages/*.json, qui comptent aujourd'hui 2 861 clés chacun. Pas 2 860 dans l'un et 2 861 dans l'autre : exactement le même arbre dans les quatre.
Cette règle de parité stricte est simple à énoncer et facile à casser. Une fonctionnalité ajoute six libellés en français, on pense à l'anglais, et l'allemand affiche le nom technique de la clé à l'écran. Voici l'outillage qui l'empêche, ce qu'il ne vérifie pas, et les pièges rencontrés qui n'avaient rien à voir avec des clés manquantes.
Un script, trois contrôles
Le premier contrôle aplatit chaque fichier en une liste de chemins (listings.detail.usageMeta.ROUTE…) et compare chaque langue au français, dans les deux sens :
const LOCALES = ['fr', 'en', 'es', 'de'];
function flatten(obj, prefix = '', out = new Set()) {
for (const [k, v] of Object.entries(obj)) {
const key = prefix ? `${prefix}.${k}` : k;
if (v && typeof v === 'object') flatten(v, key, out);
else out.add(key);
}
return out;
}
for (const loc of LOCALES.slice(1)) {
const missing = [...sets.fr].filter((k) => !sets[loc].has(k));
const extra = [...sets[loc]].filter((k) => !sets.fr.has(k));
// ...
}Les clés en trop comptent autant que les manquantes : une clé présente en allemand mais absente du français est presque toujours un renommage oublié.
Le deuxième contrôle lit le code source. Il repère chaque useTranslations('ns') ou getTranslations('ns'), associe la variable à son espace de noms, puis vérifie que chaque t('cle') statique existe bien dans fr.json. Le dernier passage a analysé 2 870 appels statiques. Les clés construites dynamiquement (t(`status.${statut}`)) ne peuvent pas être résolues ainsi : le script les liste à part, 255 aujourd'hui, pour une vérification manuelle.
Le troisième contrôle couvre justement le cas dynamique le plus fréquent : afficher un libellé par valeur d'une énumération Prisma. Un second script lit schema.prisma, extrait les membres de chaque enum, et vérifie que la famille de clés correspondante les couvre tous :
const checks = [
['listings.usage', prismaEnum('VehicleUsageTag')],
['favorites.status', prismaEnum('ListingStatus')],
['reports.reasons', prismaEnum('ReportReason')],
['admin.users.status', prismaEnum('AccountStatus')],
// ...
];Ce contrôle a trouvé de vrais défauts. Un statut ARCHIVED traduit dans les favoris n'existait plus dans le schéma, alors que PAUSED, REJECTED et DELETED n'avaient pas de libellé. Côté administration, BANNED était traduit à la place de DELETED. Plus tard, le libellé UNKNOWN_RISK manquait dans les quatre langues, et le script lui-même cherchait encore une enum renommée depuis. Aucun de ces trous n'aurait fait échouer la compilation.
Le gate, et ce qu'il ne fait pas
Les conventions du projet imposent de lancer l'audit avant chaque commit, au même titre que le typage et les tests. Toute clé ajoutée l'est dans les quatre fichiers au cours du même lot de travail. Une règle complémentaire s'y ajoute : on insère une clé par une modification ciblée, ancrée après une clé voisine unique, et on ne réécrit ni ne reformate jamais un fichier JSON entier. Une réécriture complète produit un diff illisible et masque les régressions.
Les limites sont réelles, et je préfère les écrire :
- Le gate n'est pas automatisé. Ce dépôt n'a pas de pipeline d'intégration continue ; l'audit est lancé à la main ou par l'agent qui code, avant le commit.
- Le script ne renvoie jamais de code d'erreur. Il affiche « PARITÉ KO » mais se termine toujours avec le code 0. On lit sa sortie ; on ne peut pas encore le brancher tel quel dans une CI.
- La parité est structurelle, pas linguistique. Une valeur laissée en français dans
de.jsonpasse le contrôle. Seule une relecture la repère.
Quand le compilateur peut faire le travail
Pour certains contenus, j'ai sorti le texte des fichiers de messages. Le journal des nouveautés vit dans un module TypeScript, où chaque entrée est typée ainsi :
export interface ChangelogEntry {
kind: ChangeKind;
/** Une phrase, au présent, du point de vue de l'utilisateur. */
text: Record<Locale, string>;
}Locale est dérivé de la configuration de routage (['fr', 'en', 'es', 'de']). Oublier l'espagnol sur une entrée est donc une erreur de compilation, sans script. C'est la garantie la plus forte, mais elle ne convient qu'à du contenu daté et figé, relu d'un bloc. Pour 2 861 libellés d'interface, le fichier JSON et son audit restent plus pratiques.
Les pièges qui n'étaient pas des clés
Les incidents les plus coûteux ne venaient pas de traductions manquantes, mais de la façon de résoudre la langue.
La langue lue dans un cookie rendait tout le site dynamique. Au départ, la configuration de requête de next-intl lisait la langue avec cookies(). Or un accès dynamique à cet endroit rend toutes les pages dynamiques et interdit le rendu statique. Pire, les pages véhicules qui déclaraient une revalidation ISR renvoyaient une erreur 500 DYNAMIC_SERVER_USAGE sur tout paramètre non pré-rendu. La correction a été une migration complète : toutes les routes sous un segment [locale], le middleware next-intl réactivé, et localePrefix: 'as-needed' pour que le français reste sans préfixe et que les URL existantes ne changent pas. La configuration de requête ne lit plus aucun cookie, avec un commentaire qui explique pourquoi.
Un hreflang ne pointe que vers du contenu traduit. La même migration a ajouté des canoniques par langue et des hreflang réciproques. Mais seulement sur les pages réellement traduites : les guides et pages légales, rédigés en français, gardent un canonique unique sans alternatives.
Deux usePathname ne renvoient pas la même chose. La barre de navigation mobile se masquait selon le chemin courant. Celui de next/navigation renvoie /fr/… au pré-rendu et /en/… à l'exécution : la barre clignotait et React signalait un écart d'hydratation. Celui de next-intl renvoie le chemin sans préfixe, identique partout.
Il reste une dette assumée : les messages d'erreur de l'API n'existent qu'en français et en anglais. L'interface est à parité ; le serveur ne l'est pas encore.
Ce que j'en retiens
- La parité se vérifie dans les deux sens. Une clé en trop signale un renommage oublié aussi sûrement qu'une clé manquante.
- Les clés dynamiques se recoupent avec les énumérations, pas avec le code : c'est là que se cachaient les vrais trous.
- Quand le typage peut porter la parité, il la porte mieux qu'un script. Un
Record<Locale, string>ne s'oublie pas. - La langue se résout dans l'URL, pas dans un cookie, sous peine de perdre le rendu statique sans le voir.
Vous avez une application à ouvrir à plusieurs langues sans perdre le contrôle des traductions ? Parlons de votre projet.