We hebben stiekem een Engelse versie van onze blog "Yuru Log" gemaakt. In dit artikel vertellen we wat erachter zit, en met name hoe we het probleem hebben opgelost: "Wordt een meertalige SSR-site niet onbetaalbaar door de API-kosten?"
Vooraf: we gebruiken EmDash als CMS
Deze blog draait op EmDash, een op Astro gebaseerd CMS. Je schrijft artikelen in het beheerpaneel en de frontend wordt via Astro met server-side rendering (SSR) opgebouwd.
De bediening voelt vergelijkbaar met WordPress; sommigen noemen EmDash zelfs de "geestelijke opvolger" van WordPress.
EmDash heeft standaard een ingebouwd systeem voor meertalige content. Artikelen, pagina's, menu's en taxonomieën (categorieën en tags) kunnen per locale als afzonderlijke records worden opgeslagen. Met het veld translationOf geef je aan dat een Engels artikel de vertaling is van een bepaald Japans artikel, en het wordt dan behandeld als een andere taalversie van hetzelfde artikel.
Van microCMS naar EmDash + Cloudflare: onze ervaring
Meertalig maken is met SSG eigenlijk eenvoudig
Over het algemeen geldt: als je meertalige vertalingen via een API automatisch wilt laten genereren, is het met SSG (statische sitegeneratie) eenvoudig.
- Eén keer per build de vertaal-API aanroepen
- Het resultaat als statisch bestand in de cache opslaan
- Daarna hoeft alleen nog die HTML te worden uitgeleverd
Hoeveel artikelen er ook bijkomen, er vallen API-kosten alleen per build. De frequentie is makkelijk te beheren en de cache is eenvoudig.
Maar Yurulog werkt met SSR. Moet ik dan bij elk verzoek de API aanroepen?
Dit is het probleem. De CMS-pagina's van EmDash worden volgens de specificatie volledig met SSR gerenderd (output: "server"). In plaats van pagina's vooraf uit te werken bij een statische build, haalt het systeem bij elk verzoek de nieuwste content op via de API en database van het CMS en rendert die.
Wat gebeurt er dan als je een eenvoudige implementatie maakt waarbij de Engelse pagina ter plekke door Gemini wordt vertaald wanneer die wordt weergegeven?
- Bij elk verzoek ontstaan er vertaal-API-kosten
- De latentie neemt toe (je moet wachten op het antwoord van het LLM)
- Hetzelfde artikel levert mogelijk elke keer een iets andere vertaling op (geen reproduceerbaarheid)
Dit is volledig ongeschikt. Alleen omdat het om SSR gaat, werkt het niet om bij elk verzoek "opnieuw een API aan te roepen" voor de vertaling: dat breekt zowel de kosten als de gebruikerservaring.
Oplossing: verplaats de vertaling van "op het moment van het verzoek" naar "bij het aanmaken van de content"
Het antwoord is eenvoudig: voer de vertaling niet uit op het moment van het verzoek.
Concreet hebben we het zo opgezet:
- Japanse artikelen schrijven en publiceren in het beheerscherm van EmDash
- Het vertaalscript (
scripts/translate.mjs) één keer uitvoeren- De Portable Text (gestructureerde rich text) van het Japanse artikel ophalen via de EmDash API
- Alleen de tekstdelen die vertaald moeten worden extraheren en naar de Gemini API (
gemini-3.6-flash) sturen - Afbeeldingen en blokken zoals Amazon-productkaarten worden niet vertaald maar ongewijzigd doorgegeven
- Het vertaalde resultaat opslaan als een nieuw Engelstalig artikel in de EmDash-database
- Geef de ID van het oorspronkelijke Japanse artikel op via
translationOfom het te koppelen als de Engelse versie binnen dezelfde artikelgroep - Het wordt opgeslagen als concept, zodat je het kunt controleren voordat je het publiceert
- Geef de ID van het oorspronkelijke Japanse artikel op via
Met andere woorden: de vertaling wordt niet ter plekke gegenereerd, maar behandeld als een in het CMS opgeslagen inhoudsversie in een andere taal.
Op deze manier verandert de SSR-verwerking van het verzoek zelf niet ten opzichte van het normale weergeven van artikelen. Via de reguliere locale-query van EmDash (getEmDashEntry(..., { locale: "en" })) wordt alleen de in de database opgeslagen Engelse inhoud opgehaald. Communicatie met de Gemini API vindt uitsluitend plaats eenmaal, tijdens het vertalen van het artikel, en nooit tijdens het bekijken van de pagina.
Zo ziet de opzet er dus uit
Moment waarop de vertaling plaatsvindt | API-kosten per verzoek | |
|---|---|---|
SSG + vertalen per verzoek | Tijdens de build | Nul (statische bestandslevering) |
SSR + on-the-fly vertaling (slecht voorbeeld) | Per verzoek | Per artikel × aantal bezoeken 😱 |
SSR + vooraf vertaald opgeslagen in de database (de huidige aanpak) | Bij het aanmaken van de content (eenmalig) | Nul |
Het inzicht was dit: als je bij SSG het idee van 'tijdens de build alles in één keer cachen' naar de SSR-wereld wilt brengen, dan is het equivalent het 'persistent opslaan van de vertaalde content in de database'. Ook bij SSR wordt de content zelf niet steeds opnieuw dynamisch gegenereerd; alleen de zware vertaalstap hoeft vooraf te gebeuren, waarna de levering net zo licht is als bij een gewone CMS-pagina.
Lokaal en productie hebben verschillende databases, en dat leidde er vaak toe dat ik dacht: "Waar is dat nou gebleven!?"
Dit was bij deze implementatie stiekem het meest frustrerende. EmDash heeft voor de lokale ontwikkelomgeving en de productieomgeving elk een eigen database. Logisch, maar het gevolg was dat functies die daarnet nog werkten ineens leken te verdwijnen, en dat overkwam me meerdere keren.
De symptomen waren meestal deze:
- De navigatie in de header wordt ineens leeg
- De lijst met Categories in de footer verdwijnt
- De sidebarwidgets op de artikelpagina verdwijnen
- De lokale menu-items en widgets die ik had ingesteld, zijn teruggezet naar de oorspronkelijke staat
En alles gebeurde telkens op een moment waarop het net nog werkte, dus ik vroeg me eerst af of ik zelf iets had kapotgemaakt en zocht naar de oorzaak.
Oorzaak 1: het script dat de productiedatabase lokaal ophaalt (pull.sh)
Tijdens de ontwikkeling draaide ik een aantal keren een script dat de volledige productiedatabase lokaal ophaalt, omdat ik de meest recente productiedata lokaal wilde zien. Daarbij wordt de lokale database volledig overschreven met de staat van productie, bijvoorbeeld engelstalige artikelen die nog concepten waren of een menustructuur die nog niet live stond.
Functies die nog niet live stonden en die ik lokaal had voorbereid, waren daardoor direct na het ophalen van de productiedata weer verdwenen. Het werk dat ik lokaal al had gedaan, was dus tijdelijk niet meer zichtbaar.
Oorzaak 2: de seed-stap die bij elke nieuwe inlog in het lokale beheer draait
De tweede oorzaak was dat de ontwikkelingsbypass waarmee ik me lokaal opnieuw aanmeld in het beheerpaneel, bij elke keer inloggen ook het seed.json-bestand (het bestand met de initiële datadefinitie) opnieuw inlas.
Dit is lastig, want
- Menu-items en widgets → worden "exact" overschreven met de inhoud uit de seed (= handmatig lokaal toegevoegde items verdwijnen)
- Taxonomieën zoals categorieën en tags → worden overgeslagen als ze al bestaan, dus die verdwijnen niet
Dit was een specificatie waarbij het gedrag per onderdeel verschilde. Daardoor deed zich het tot op het oog onverklaarbare verschijnsel voor dat de categorieën bleven staan, terwijl alleen de menu's en widgets telkens verdwenen.
De oplossing die ik heb toegepast
Het wegnemen van deze dubbele overschrijving (overschrijven via pull en via de seed) bleek lastig. Als praktisch compromis heb ik
seed.jsonzo aangepast dat alle demo-inhoud (menu-items, widgets, categorieën enz.) leeg is- en de benodigde menu's en widgets bij elke nieuwe start van de lokale omgeving opnieuw via de API aangemaakt
. Dit is een tijdelijke oplossing en geen definitieve fix, maar het voorkomt in elk geval dat er per ongeluk met ongewenste demogegevens wordt overschreven.
Conclusie
- EmDash is van oorsprong een meertalige CMS waarbij inhoud per locale kan worden beheerd
- Bij SSG volstaat het om bij de build te vertalen en het resultaat te cachen, maar bij SSR betekent elk 'vertalen op verzoek' hoge kosten.
- De oplossing is om de vertaling slechts één keer uit te voeren bij het maken van de content, en niet bij elk verzoek, en het resultaat op te slaan in de database als gewone CMS-content.
- De gebruikte vertaalengine is de Gemini API (
gemini-3.6-flash). - Bij het meertalig maken van een CMS is het echter niet voldoende alleen de vertaalworkflow goed in te richten; het feit dat de lokale en de productiedatabase gescheiden zijn, brengt op zich weer nieuwe valkuilen met zich mee, en daar moet je ook rekening mee houden.
- Vooral bij ontwikkeling waarbij je lokaal werkt aan iets dat nog niet in productie staat, kun je gemakkelijk last krijgen van de neveneffecten van synchronisatiemechanismen, zoals pull, seeding en caching.
De belangrijkste les is dat je, als je vooraf goed nadenkt over deze twee timingvragen, namelijk wanneer je vertaalt en wanneer en wat de synchronisatie van de omgevingen overschrijft, ook met SSR een meertalige site kunt bouwen zonder last te hebben van hoge operationele kosten en incidenten.
Wat denk je, zou meertalig maken ook iets voor jouw site zijn?
Ik ben voornamelijk bezig met markup en frontend-ontwikkeling met JavaScript, React en Next.js. Ik ben blij wanneer een site waar ik aan heb meegewerkt succesvol live gaat! Mijn hobby's zijn gitaar spelen. Ik hou van katten en geroosterde zoete aardappel 🐱🍠
ひらっち
Frontend-engineer / in dienst sinds 2022