Topics

Een meertalige blog gebouwd met EmDash: hoe je de kosten van vertaal-API's laag houdt, ook bij SSR

  • column

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:

  1. Japanse artikelen schrijven en publiceren in het beheerscherm van EmDash
  2. 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
  3. Het vertaalde resultaat opslaan als een nieuw Engelstalig artikel in de EmDash-database
    • Geef de ID van het oorspronkelijke Japanse artikel op via translationOf om het te koppelen als de Engelse versie binnen dezelfde artikelgroep
    • Het wordt opgeslagen als concept, zodat je het kunt controleren voordat je het publiceert

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.json zo 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?

Over de auteur

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

Bekijk de artikelen van deze medewerker

Ons grootste pluspunt is een betrouwbaar team en een snelle reactie

Bij Liberogic wordt er door onze ervaren medewerkers proactief aan projecten gewerkt, waardoor klanten ons hoog waarderen.
We zorgen ervoor dat er zorgvuldig een projectmanager en een director worden toegewezen, zodat het gehele project soepel verloopt. We voorkomen onnodige kostenstijging door middel van volledige inzet en verdelen de middelen op een manier die past bij de taak. Ook staan we bekend om ons snelle inzicht in de werkzaamheden en het snel opstellen en indienen van offertes.

* Liberogic zet zich niet in voor SES-achtige detacheringsopdrachten op locatie bij klanten. Houd hier alstublieft rekening mee.

U kunt vrijwel alle belangrijke tools voor projectmanagement en chat gebruiken, waaronder Slack, Teams, Redmine, Backlog, Asana, Jira, Notion, Google Workspace, Zoom, Webex en meer.

Neem gerust contact op met uw vragen over het web.

Casestudies