Nuestro blog, Yurulog, recientemente tuvo una versión en inglés que lanzamos discretamente. En este artículo explico lo que hay detrás, en especial cómo resolvimos el problema de que la multilingüidad en un sitio con SSR pueda disparar el coste de la API.
Contexto: usamos EmDash como CMS
Este blog funciona con EmDash, un CMS basado en Astro. Escribimos los artículos en el panel de administración y el frontend se renderiza en el servidor (SSR) con Astro.
Su manejo es similar al de WordPress, y se dice que es su "sucesor espiritual".
EmDash incluye de serie un sistema de "contenido multilingüe" que permite guardar artículos, páginas, menús y taxonomías (categorías y etiquetas) como registros separados por idioma. Basta con indicar en el campo translationOf que "este artículo en inglés es la traducción de este artículo en japonés" para que se trate como una versión en otro idioma del mismo contenido.
Migré de microCMS a EmDash + Cloudflare
Con la multilingüidad, si se usa SSG resulta sencillo
En general, cuando se automatiza la traducción multilingüe mediante una API, con SSG (generación de sitios estáticos) la cuestión es sencilla.
- Llamar a la API de traducción una sola vez durante la compilación
- Almacenar los resultados en caché como archivos estáticos
- Después, solo hay que servir ese HTML
Por eso, aunque aumente el número de artículos, el coste de la API solo se genera en cada compilación. La frecuencia también es fácil de controlar y la caché es sencilla.
Pero Yurulog usa SSR. Entonces, ¿llamamos a la API en cada solicitud?
Aquí está el problema. Por especificación, todas las páginas del CMS de EmDash se renderizan con SSR (output: "server"). En lugar de generar las páginas con un build estático, el sistema obtiene el contenido más reciente del API o la base de datos del CMS en cada solicitud y lo renderiza.
Entonces, ¿qué pasaría con una implementación ingenua en la que, al mostrar una página en inglés, se le pide a Gemini que traduzca el contenido sobre la marcha?
- Se genera un cargo por la API de traducción en cada solicitud
- La latencia también aumenta (hay que esperar la respuesta del LLM)
- El mismo artículo podría devolver traducciones ligeramente distintas cada vez (falta de reproducibilidad)
Esto es totalmente inviable. Adoptar "llamar a la API cada vez" solo porque es SSR arruina tanto los costes como la UX.
Solución: mover la traducción del "momento de la solicitud" al "momento de crear el contenido"
La respuesta es sencilla: no realizar la traducción en el momento de la solicitud.
En concreto, lo montamos como un pipeline de este tipo.
- Redactar y publicar el artículo en japonés desde el panel de administración de EmDash
- Ejecutar una sola vez el script de traducción (
scripts/translate.mjs)- Obtener desde la API de EmDash el Portable Text (texto enriquecido estructurado) del artículo en japonés
- Extraer solo las partes de texto que deben traducirse y enviarlas a la API de Gemini (
gemini-3.6-flash) - Los bloques de imágenes, tarjetas de productos de Amazon y similares se mantienen sin traducir y pasan tal cual
- Guardar el resultado de la traducción en la base de datos de EmDash como un nuevo artículo en inglés
- Specify the original Japanese article ID in
translationOfto link it as the English version within the same article group. - It is saved as a draft, so it can be reviewed before publishing.
- Specify the original Japanese article ID in
In other words, the translation is not something "generated on the spot," but is treated as the content in another language that has been saved in the CMS.
With this approach, the SSR request handling itself is no different from regular article display. The saved English content in the database is simply retrieved using the standard locale-aware query in EmDash (getEmDashEntry(..., { locale: "en" })). Communication with the Gemini API occurs only once, when the article is translated, and never during page viewing.
The structure works like this
When translation runs | API cost per request | |
|---|---|---|
SSG + on-demand translation | Build time | Zero (static file delivery) |
SSR + traducción en cada solicitud (ejemplo negativo) | Por cada solicitud | Se produce por artículo × número de accesos 😱 |
SSR + traducciones precalculadas guardadas en la BD (el método de esta vez) | Al crear el contenido (una vez) | Cero |
La idea clave fue que, si llevamos al mundo de SSR el concepto de SSG de "almacenar en caché por lotes durante la compilación", la alternativa es "persistir el contenido traducido en la base de datos". Aunque se use SSR, el contenido en sí no tiene que generarse dinámicamente de forma continua: si se realiza por adelantado el proceso pesado de la traducción, la entrega en sí resulta tan ligera como una página de CMS normal.
Cuando la base de datos local y la de producción eran distintas, y tuve que preguntarme muchas veces "¿dónde se fue?"
En esta implementación, lo que más desgaste me causó, aunque parezca un detalle, fue esto. EmDash tiene una base de datos separada para el entorno de desarrollo local y otra para el entorno de producción. Es algo obvio, pero provocó que en varias ocasiones me encontrara con que "¡la función que estaba funcionando hace un momento ha desaparecido!".
Los síntomas eran más o menos estos
- La navegación del encabezado (nav) se vacía de repente
- La lista de Categories del footer desaparece
- Los widgets de la barra lateral de las páginas de artículos desaparecen
- Los elementos de menú y los widgets locales que había creado vuelven a su estado anterior
Además, todo ocurría justo cuando "hasta hace un momento funcionaba", así que al principio busqué la causa sospechando que yo mismo había roto algo.
Causa 1: El proceso que trae la base de datos de producción al entorno local (pull.sh)
Durante el desarrollo, ejecuté varias veces un script que importaba completa la base de datos de producción al entorno local, con la idea de poder ver también localmente los datos más recientes de producción. Al hacerlo, la base de datos local se sobrescribe por completo con el estado de producción (es decir, con artículos en inglés que seguían en borrador o con una estructura de menús previa a su publicación).
Por eso, cuando intentaba revisar localmente funciones que aún no estaban publicadas en producción, justo después de hacer pull el contenido volvía al estado de producción, y los cambios que había avanzado solo en local dejaban de verse temporalmente.
Causa 2: El proceso de "seed" que se ejecuta cada vez que vuelvo a entrar al panel de administración local
La otra causa era que el mecanismo de inicio de sesión de desarrollo (un acceso de bypass para volver a iniciar sesión en el panel de administración local) también volvía a leer, cada vez, seed.json (el archivo de definición de datos iniciales).
Este era el problema:
- Elementos de menú y widgets → se sobrescriben para que coincidan exactamente con el contenido del seed (es decir, lo que se añadió manualmente en local se pierde).
- Taxonomías como categorías y etiquetas → se omiten si ya existen, así que no se eliminan.
Es decir, el comportamiento variaba según el tipo de elemento. Por eso se producía el fenómeno aparentemente incomprensible de que las categorías permanecían, mientras que solo los menús y los widgets se borraban cada vez.
La solución aplicada
Eliminar esta doble estructura (sobrescritura por pull y sobrescritura por seed) resultó difícil, así que como solución práctica:
- Vaciamos por completo el contenido de demostración (elementos de menú, widgets, categorías, etc.) de
seed.json - Cada vez que volvemos a entrar al entorno local, recreamos los menús y widgets necesarios a través de la API
Con esta forma de trabajo hemos sobrellevado el problema. No es una solución definitiva, sino una medida paliativa, pero al menos ya evitamos el incidente de que se sobrescriba todo con datos de demostración no deseados.
Conclusión
- EmDash es un CMS multilingüe que, desde su diseño original, permite gestionar contenido por configuración regional (locale).
- Con SSG basta con "traducir durante la compilación y guardar en caché", pero con SSR "traducir en cada solicitud" se convierte en un infierno de costos.
- La solución consiste en realizar la traducción una sola vez al crear el contenido, en lugar de en el momento de la solicitud, y guardar el resultado en la base de datos como contenido normal del CMS.
- El motor de traducción utilizado fue la API de Gemini (
gemini-3.6-flash). - Sin embargo, al hacer multilingüe un CMS, no basta con organizar el flujo de traducción: también hay que tener presente que el hecho de que la base de datos local y la de producción estén separadas genera una nueva trampa.
- En particular, el tipo de desarrollo que "adelanta en local un estado que todavía no existe en producción" tiende a verse afectado por los efectos secundarios de los mecanismos de sincronización del entorno (pull, seeds, caché, etc.).
La lección de esta experiencia es que, si se define de antemano el momento en que se realiza la traducción y el momento en que la sincronización del entorno sobrescribe, cuándo y qué, estos dos aspectos de diseño, es posible implementar soporte multilingüe con SSR sin verse afectado por los costos operativos ni por los incidentes.
¿Qué tal si consideran hacer su sitio multilingüe también?
Me dedico principalmente al maquetado y al desarrollo frontend con JavaScript, React y Next.js. Me alegra mucho cuando los sitios en los que participo se publican con éxito. Mi afición es tocar la guitarra. Me gustan los gatos y las batatas asadas 🐱🍠
Hirocchi
Ingeniero/a de frontend / Se unió en 2022