Nous avons récemment ajouté discrètement une version anglaise de notre blog Yurulog. Cet article présente les coulisses de ce projet, en particulier la façon dont nous avons résolu la question suivante : comment éviter que le coût des API explose lorsqu'on rend un site multilingue en SSR ?
Prérequis : utiliser le CMS EmDash
Ce blog fonctionne avec EmDash, un CMS basé sur Astro. Les articles sont rédigés depuis l'interface d'administration, et le frontend est rendu côté serveur (SSR) avec Astro.
Son utilisation rappelle WordPress, et EmDash est d'ailleurs présenté comme le « successeur spirituel de WordPress ».
EmDash intègre nativement une fonctionnalité de « contenu multilingue » : les articles, pages, menus et taxonomies (catégories et étiquettes) peuvent être stockés sous forme d'enregistrements distincts pour chaque locale. Il suffit de renseigner le champ translationOf pour indiquer que cet article anglais est la traduction de tel article japonais ; le système le traite alors comme une version linguistique du même contenu.
Migration de microCMS vers EmDash + Cloudflare
Pour le multilingue, avec un SSG, c'est assez simple
En général, lorsqu'on automatise la traduction multilingue via une API, un SSG (générateur de sites statiques) simplifie nettement les choses.
- Appeler l'API de traduction une seule fois, au moment du build
- Mettre les résultats en cache sous forme de fichiers statiques
- Il ne reste ensuite qu'à servir ces fichiers HTML.
Ainsi, quel que soit le nombre d'articles, les coûts d'API ne sont engagés qu'à chaque build. La fréquence est facile à contrôler et la mise en cache reste simple.
Mais Yurulog fonctionne en SSR. Alors faut-il appeler l'API à chaque requête ?
Le problème est là. Par conception, les pages CMS d'EmDash sont toutes rendues en SSR (output: "server"). Il ne s'agit pas d'un système qui génère des pages figées à la compilation : à chaque requête, le contenu le plus récent est récupéré depuis l'API et la base de données du CMS, puis affiché.
Que se passe-t-il alors si l'on met en place l'implémentation naïve suivante : « lorsqu'une page anglaise est affichée, la faire traduire par Gemini à la volée » ?
- Chaque requête entraîne des frais de l'API de traduction
- La latence augmente également (il faut attendre la réponse du LLM)
- Pour un même article, la traduction obtenue peut varier légèrement d'une fois à l'autre (absence de reproductibilité)
C'est absolument une mauvaise approche. Même avec le SSR, adopter une logique qui « appelle l'API à chaque requête » ruine à la fois les coûts et l'expérience utilisateur.
Solution : déplacer la traduction du moment de la « requête » au moment de la « création du contenu ».
La réponse est simple : ne pas effectuer la traduction au moment de la requête.
Concrètement, nous avons mis en place le pipeline suivant.
- Rédaction et publication de l'article en japonais dans l'interface d'administration d'EmDash
- Exécution unique du script de traduction (
scripts/translate.mjs)- Récupération du Portable Text (texte enrichi structuré) de l'article japonais via l'API d'EmDash
- Extraction uniquement des parties textuelles à traduire, puis envoi à l'API Gemini (
gemini-3.6-flash) - Les blocs tels que les images et les cartes produits Amazon ne sont pas traduits et sont transmis tels quels
- Enregistrement du résultat de la traduction dans la base de données d'EmDash en tant que nouvel article en anglais
- Indiquez l'ID de l'article japonais d'origine dans
translationOfpour le lier à la version anglaise du même groupe d'articles. - Il est enregistré comme brouillon, vous pouvez donc le relire avant de le publier.
- Indiquez l'ID de l'article japonais d'origine dans
En d'autres termes, la traduction n'est pas « générée à la volée », mais traitée comme un autre contenu linguistique stocké dans le CMS.
Ainsi, le traitement des requêtes SSR reste identique à l'affichage habituel des articles. La requête localisée standard d'EmDash (getEmDashEntry(..., { locale: "en" })) récupère simplement le contenu anglais déjà enregistré en base de données. L'appel à l'API Gemini n'intervient qu'une seule fois, au moment de la traduction de l'article, et n'a jamais lieu lors de la consultation.
Voici le schéma global.
Moment de la traduction | Coût API par requête | |
|---|---|---|
SSG + traduction à la demande | Au moment du build | Aucun (diffusion de fichiers statiques) |
SSR + traduction à chaque requête (mauvais exemple) | À chaque requête | Articles × nombre d'accès : déclenché à chaque fois 😱 |
SSR + traductions préalables enregistrées en base de données (approche retenue) | Lors de la création du contenu (une seule fois) | Zéro |
L'idée du SSG consistant à « mettre en cache en lot au moment du build » peut être transposée au SSR en « conserver les contenus traduits de manière persistante en base de données ». Même avec le SSR, le contenu lui-même n'est pas généré dynamiquement en permanence : il suffit d'effectuer à l'avance le traitement lourd qu'est la traduction, et la diffusion devient aussi légère qu'une page CMS classique. C'est la découverte que j'ai faite avec ce projet.
Quand la base de données locale et celle de production diffèrent : les fois où « où est passé tout ça ? ! »
Pour cette implémentation, c'est ce qui m'a le plus usé, sans en avoir l'air. EmDash dispose d'une base de données distincte pour l'environnement de développement local et pour la production. C'est logique, mais cela a provoqué à plusieurs reprises le même scénario : une fonctionnalité qui existait encore quelques instants plus tôt semblait avoir disparu.
Les symptômes sont généralement les suivants :
- La navigation de l'en-tête se vide soudainement
- La liste des catégories du pied de page disparaît
- Les widgets de la barre latérale des pages d'articles disparaissent
- Les éléments de menu et les widgets locaux que j'avais configurés reviennent à leur état d'origine
De plus, tout cela se produisait juste après un moment où tout fonctionnait encore, si bien que j'ai d'abord cherché la cause en me demandant si je n'avais pas moi-même cassé quelque chose.
Cause n°1 : le script qui importe la base de données de production en local (pull.sh)
Pendant le développement, je lançais plusieurs fois un script important l'intégralité de la base de données de production en local, dans le but de consulter les dernières données de production également sur ma machine. Or, cette opération écrase entièrement la base locale avec l'état de production (par exemple, des articles en anglais encore au stade de brouillon, ou une structure de menus non encore publiée).
Ainsi, lorsque je tentais de vérifier en local une fonctionnalité pas encore publiée en production, les modifications que j'avais effectuées uniquement en local disparaissaient temporairement dès le rapatriement des données, la base revenant à l'état de production.
Cause n°2 : le script « seed » exécuté à chaque reconnexion à l'interface d'administration locale
La seconde cause était que le mécanisme de connexion de développement (contournement de connexion) permettant de se reconnecter à l'interface d'administration locale rechargeait aussi systématiquement seed.json (le fichier de définition des données initiales) à chaque fois.
C'est là que ça devient gênant :
- Les éléments de menu et les widgets sont « écrasés à l'identique » par le contenu du seed (ce qui signifie que tout ajout effectué manuellement en local est supprimé).
- En revanche, les taxonomies telles que les catégories et les étiquettes ne sont pas supprimées, car les éléments déjà existants sont ignorés.
Le comportement variait donc selon le type d'élément. C'est pourquoi on observait le phénomène déroutant où les catégories restaient en place, alors que seuls les menus et les widgets disparaissaient à chaque fois.
Solution appliquée
Supprimer cette double logique d'écrasement (pull et seed) s'étant révélé difficile, nous avons adopté une solution pragmatique :
- vider entièrement le contenu factice de démonstration (éléments de menu, widgets, catégories, etc.) de
seed.json - et recréer les menus et widgets nécessaires via l'API à chaque nouvelle configuration de l'environnement local
. Il ne s'agit pas d'une correction de fond mais d'un moyen d'atténuer le problème ; au moins, les écrasements accidentels par des données de démonstration sont désormais évités.
Conclusion
- EmDash est à l'origine un CMS multilingue permettant de gérer un contenu distinct pour chaque locale.
- Avec le SSG, il suffit de traduire au moment du build puis de mettre en cache, alors qu'avec le SSR, une traduction à chaque requête peut vite devenir un gouffre financier.
- La solution consiste à n'exécuter la traduction qu'une seule fois, au moment de la création du contenu, et non à chaque requête, puis à enregistrer le résultat dans la base de données comme un contenu CMS ordinaire.
- Le moteur de traduction utilisé est l'API Gemini (
gemini-3.6-flash). - Toutefois, lors de la mise en place du multilingue dans un CMS, optimiser le flux de traduction ne suffit pas : le fait que les bases de données locale et de production soient séparées crée en soi de nouveaux pièges, à garder en tête.
- En particulier, les développements qui consistent à travailler localement sur un état qui n'existe pas encore en production sont facilement perturbés par les effets secondaires des mécanismes de synchronisation de l'environnement (pull, seed, cache, etc.).
La leçon retenue : si l'on maîtrise à l'avance ces deux éléments de conception, à savoir quand la traduction a lieu et quand et quoi la synchronisation de l'environnement écrase, il est possible de proposer du multilingue avec SSR sans subir les coûts d'exploitation ni les incidents.
Et si vous passiez votre site au multilingue ?
Je travaille sur le développement frontend, principalement en balisage, avec JavaScript, React et Next.js. Je suis ravi lorsque les sites auxquels j'ai contribué sont mis en ligne avec succès ! Passionné de guitare, j'aime aussi les chats et les patates douces grillées 🐱🍠
Hiratchi
Ingénieur frontend / Entré en 2022