Sobre esta serie

Esta serie cubre todo lo que necesitas para agregar múltiples idiomas a un blog, documentación o cualquier otro sitio orientado a contenido servido desde archivos Markdown - desde el primer cambio de configuración hasta una capa de caché en producción que mantiene los costos de la API de traducción muy por debajo de $30 incluso para un catálogo de 500 artículos, y una fracción de eso cada año posterior.

Los ejemplos a lo largo de la serie usan portugués y español como idiomas concretos, pero la arquitectura es idéntica para cualquier idioma: alemán, japonés, coreano, chino o cualquier otro que hable tu audiencia. La serie está escrita en el orden en que la implementarías, y cada artículo produce código funcional que puedes confirmar en tu repositorio.

Antes de entrar en la implementación, vale la pena dedicar un momento al panorama general de los enfoques de internacionalización, porque la arquitectura que elijas depende casi por completo de dónde vive tu contenido.

Dónde vive el contenido lo determina todo

Existen tres modelos de contenido comunes para blogs de desarrolladores y sitios de documentación, y cada uno lleva a una estrategia de i18n fundamentalmente diferente.

Contenido en un CMS

Herramientas como Contentful, Sanity o Prismic tienen internacionalización incorporada. Creas un tipo de contenido con soporte de idiomas, los autores escriben directamente en cada idioma dentro de la interfaz del CMS, y la API devuelve el idioma correcto al solicitarlo. Los flujos de trabajo de traducción, los estados de aprobación y las puertas de publicación son gestionados por el propio CMS.

Esta es la elección correcta cuando autores no técnicos administran contenido en múltiples idiomas y las herramientas de flujo de trabajo editorial son un requisito indispensable. El costo es que el CMS se convierte en una dependencia para cada renderizado de página, el contenido queda encerrado dentro de un sistema propietario, y la experiencia de desarrollo está dictada por la API del CMS en lugar de tus propias estructuras de datos.

Contenido en una base de datos

Los artículos almacenados en Postgres, MySQL o un almacén de documentos como MongoDB te dan control total sobre el esquema. Agregas una columna locale, consultas por ella y devuelves las filas traducidas.

Este modelo escala bien para grandes operaciones de contenido con equipos de traducción dedicados y mantiene todo en un lugar consultable. El costo es la complejidad de infraestructura: necesitas una base de datos en ejecución, un pool de conexiones y una capa de consulta, y cada carga de página accede a la base de datos a menos que agregues una capa de caché encima.

Contenido en archivos Markdown

Los artículos son archivos .md confirmados en el repositorio junto al código de la aplicación. No hay base de datos, no hay dependencia de API, no hay suscripción a un CMS. El contenido está versionado, es diferenciable y se despliega con un solo git push.

Este es el modelo natural para blogs escritos por desarrolladores y documentación técnica donde los autores se sienten cómodos en un editor de código y el contenido evoluciona junto con el código base. El costo es que las herramientas editoriales al estilo CMS no existen por defecto, pero para un blog de desarrolladores no las necesitas.

Esta serie se enfoca en archivos Markdown

Si tu contenido vive en un CMS, el CMS gestiona la internacionalización y esta serie no es el punto de partida correcto - consulta la documentación de tu CMS para la configuración de idiomas. Si tu contenido vive en una base de datos, el enfoque es similar en espíritu pero la implementación difiere - agregarías una columna locale y consultarías por ella en lugar de llamar a una API de traducción en tiempo de solicitud. Esta serie está específicamente diseñada para el tercer modelo: contenido en archivos Markdown, que es el más común para blogs y documentación escritos por desarrolladores.

Por qué esta serie se enfoca en Markdown

Los seis artículos de esta serie asumen que tu contenido vive en archivos Markdown dentro de src/posts/. Esta es una elección deliberada que habilita una arquitectura específica: la prosa se extrae del archivo Markdown canónico, se envía a la API de Claude para su traducción y se almacena en Upstash Redis.

El archivo .md original nunca se modifica. Permanece como la única fuente de verdad para bloques de código, estructura y metadatos en todos los idiomas. Los ejemplos usan portugués (pt) y español (es), pero agregar alemán (de), japonés (ja) o coreano (ko) requiere cambiar una línea en la configuración y una línea en el comparador de rutas.

Para proyectos centrados en Markdown, la traducción bajo demanda resuelve un problema que ni los enfoques de CMS ni los de base de datos enfrentan: una parte sustancial de cada artículo - a menudo del 40 al 60 por ciento - es código que nunca debe traducirse. El extractor de prosa descrito en el artículo 4 elimina cada bloque de código, ruta de archivo y referencia de código en línea antes de que la API de Claude vea el contenido. Solo la prosa legible por humanos cruza el límite de la API.

El resultado traducido se almacena en Upstash Redis. Las traducciones completas se almacenan permanentemente y solo se borran cuando cambia el artículo fuente. Las traducciones incompletas (donde el modelo omitió algunos segmentos) reciben un TTL de 2 horas para que se reintenten automáticamente en la próxima visita sin intervención manual. El primer visitante de una combinación de idioma y artículo paga el costo de traducción una vez; cada visitante posterior obtiene el resultado en caché al instante.

Qué cubre esta serie

Artículo 1 (este artículo) explica el modelo de superposición: qué es, por qué es mejor que la duplicación completa de archivos o la traducción en tiempo de ejecución del código fuente completo, y cómo diseñar la arquitectura para que agregar cualquier nuevo idioma más adelante requiera cambiar dos líneas de código.

Artículo 2 recorre cada cambio sin riesgo: configuración de idiomas con tipos TypeScript adecuados, detección de idioma en hooks.server.ts, el atributo HTML lang, el comparador de rutas (src/params/locale.ts) que evita que el grupo de idiomas secuestre rutas existentes, y el grupo de rutas (locale)/[lang=locale]/ que agrega rutas traducidas sin modificar ni una sola ruta en inglés existente.

Artículo 3 extiende el singleton del índice de contenido para exponer getContent(locale) - la función única que llama cada ruta traducida. También cubre +page.server.ts vs +page.ts y por qué se requiere @types/node, más el componente completo +page.svelte que renderiza artículos traducidos.

Artículo 4 cubre el extractor de prosa, el módulo de traducción de la API de Claude, el pipeline de renderizado marked v15 y Shiki, la configuración de la clave de API de Claude, y la implementación completa de +page.server.ts usando translateBatch para traducción por fragmentos con reintentos.

Artículo 5 agrega la caché de traducción Upstash Redis: configuración paso a paso en el Marketplace de Vercel, el módulo de caché con TTL condicional (permanente para traducciones completas, 2 horas para las incompletas), escrituras de HTML en segundo plano, y el desglose completo de costos por tamaño de catálogo.

Artículo 6 implementa las herramientas de desarrollo: la ruta de vista previa /dev/translations para probar traducciones antes de que llegue tráfico real, el script CLI pnpm translate para pre-traducir artículos individuales, el script de invalidación de caché al momento del despliegue, y el pipeline de traducción del catálogo con la API por lotes para traducir cientos de artículos de noche con un 50 por ciento de descuento.

Lee los seis en orden para tener el panorama completo, o salta al artículo que cubre la parte que estás listo para implementar.

La trampa de un archivo por idioma

La forma más natural de agregar un segundo idioma a un blog en Markdown es la más costosa. Duplicas cada archivo de artículo, agregas un prefijo de idioma a la ruta y traduces todo. Cien artículos en inglés se convierten en doscientos archivos con portugués, y trescientos con traducciones al español.

El repositorio triplica su tamaño, y cada vez que corriges un error tipográfico o actualizas un ejemplo de código en inglés, tienes que encontrar y corregir lo mismo en cada copia traducida. En seis meses, tus lectores en portugués están siguiendo código desactualizado que ya no funciona con la versión actual del framework. Esta es la trampa de un archivo por idioma, y casi todos los tutoriales de i18n para generadores de sitios estáticos te llevan directamente a ella.

La trampa persiste porque hace que lo incorrecto parezca obvio. Cuando piensas en "traducir este artículo", el instinto es copiar el archivo completo y entregárselo a un traductor. Eso funciona perfectamente para un sitio de marketing donde el contenido es prosa pura. Falla gravemente para un blog técnico donde el 40 al 60 por ciento de cada artículo es código que nunca debe traducirse, que permanece idéntico en todos los idiomas y se convierte en una carga de mantenimiento en el momento en que vive en múltiples archivos.

Qué contiene realmente un artículo técnico

Antes de diseñar una arquitectura de traducción, es útil categorizar qué hay realmente dentro de un artículo técnico.

Nunca se traduce - idéntico en todos los idiomas:

Todos los bloques de código (la implementación real)
Referencias de código en línea como $state(), load(), +page.server.ts
Rutas de archivos como src/routes/(locale)/[lang=locale]/+layout.ts
Comandos CLI como pnpm add @upstash/redis
Términos técnicos usados como nombres propios: SvelteKit, Runes, ISR, SSR, hydration, Vite
Campos estructurales del frontmatter: track, topic, tags, difficulty, position

Siempre se traduce - la prosa real:

Introducciones y explicaciones de secciones
El razonamiento detrás de las decisiones
Explicaciones de mensajes de error
Descripciones de errores comunes
Valores del frontmatter title y description
Valores de metadatos SEO

Se traduce con cuidado - prosa técnica:

Oraciones que mezclan explicación con referencias de código en línea
Comentarios dentro de bloques de código (mantener en inglés - los desarrolladores de todo el mundo esperan comentarios de código en inglés)
Analogías y metáforas que pueden no trasladarse claramente entre idiomas

En un artículo típico de SvelteKit de 3,000 palabras, aproximadamente 1,200 son prosa, 300 son encabezados y texto estructural, y 1,500 son código. Necesitas traducir 1,500 palabras para servir bien a un lector en portugués. Duplicar el archivo completo de 3,000 palabras significa que estás almacenando y manteniendo 1,500 palabras de código idéntico en cada idioma que agregues.

Cómo funciona realmente la traducción en esta arquitectura

El archivo .md canónico nunca cambia y nunca se mueve. Permanece como la única fuente de verdad para el artículo en todos los idiomas. Lo que cambia por idioma es solo la prosa - las oraciones y párrafos que un lector realmente lee.

El camino principal de traducción es bajo demanda a través de la API de Claude:

first visitor to /pt/[your-article-slug]
  → prose extractor strips all code blocks from the .md
  → prose-only content sent to Claude API
  → pre-rendered HTML stored in Upstash Redis (TTL based on completeness - see article 5)
  → article rendered: translated prose + original code blocks

every subsequent visitor
  → Redis cache hit → serve instantly, zero API cost

Para un ejemplo concreto: cuando un lector visita /pt/sveltekit/routing/dynamic-routes por primera vez, ese flujo se ejecuta completo. Cada lector posterior obtiene el resultado en caché al instante.

El archivo .md nunca se duplica. Los bloques de código nunca salen del servidor. El código fuente en inglés permanece intacto en todos los idiomas.

Para artículos importantes - contenido pilar y puntos de entrada de series - existe un camino opcional de pre-traducción estática que se ejecuta antes de que llegue el primer visitante. Un script CLI extrae la prosa del .md, llama a la API de Claude en modo por lotes con un 50 por ciento de descuento sobre la tarifa estándar, y escribe el resultado directamente en Redis:

src/posts/
  sveltekit/
    routing/
      dynamic-routes.md          ← canonical English, never changes

src/translations/                  ← optional static YAML overlays
  pt/
    sveltekit/
      routing/
        dynamic-routes.yaml      ← pre-translated prose only, no code

Cuando existe un archivo de superposición estática, el servidor lo usa directamente sin llamar a la API. Cuando no existe, el camino bajo demanda lo maneja automáticamente.

Por qué esto es mejor que todas las alternativas

vs. duplicación completa de archivos: Solo la prosa cruza el límite de la API y solo la prosa se almacena en caché. Cuando actualizas un ejemplo de código en el archivo canónico en inglés, todos los idiomas obtienen la actualización automáticamente porque el código nunca vivió en ningún otro lugar.

vs. traducción en tiempo de ejecución del archivo completo: Enviar un artículo completo en Markdown a una API de traducción es ineficiente y arriesgado. Los modelos de traducción ocasionalmente corrigen nombres de variables, traducen literales de cadenas de texto o ajustan el formato dentro de los bloques de código. El modelo de superposición extrae la prosa antes de la llamada a la API, por lo que la API nunca ve un solo acento grave.

vs. un sistema de gestión de traducciones: Herramientas como Crowdin o Lokalise están diseñadas para cadenas de interfaz de usuario - etiquetas cortas, texto de botones, mensajes de error. Funcionan mal con prosa de formato largo y no tienen concepto de "esta sección es código, omítela". También agregan infraestructura y costos significativos para un blog que necesita traducir 100 artículos una vez, no miles de cadenas de interfaz de usuario de forma continua.

vs. no hacer nada: Servir inglés a un desarrollador brasileño que habría leído el artículo en portugués es un costo real, aunque sea invisible en tus métricas. El modelo de superposición hace que la traducción sea lo suficientemente económica como para que no traducir deje de ser una opción razonable.

Diseñando para idiomas que aún no has agregado

La restricción arquitectónica más importante es que agregar un tercer o cuarto idioma más adelante no debería requerir tocar ningún código existente. Esto es alcanzable si haces de SUPPORTED_LOCALES la única fuente de verdad para todo lo relacionado con idiomas.

Cada parte del sistema que varía por idioma - validación de rutas, generación de hreflang, espaciado de nombres de claves de caché, scripts de traducción - lee desde ese único arreglo de configuración. Agregar coreano significa agregar 'ko' a SUPPORTED_LOCALES en config.ts y al comparador de rutas en src/params/locale.ts. Las rutas, el índice de contenido, la caché de Redis y las etiquetas hreflang se actualizan automáticamente.

La única excepción es el patrón glob de Vite para la carga opcional de superposiciones YAML. Vite analiza las cadenas glob estáticamente en tiempo de compilación y no puede construirlas desde una variable en tiempo de ejecución. Cada idioma necesita un glob escrito explícitamente:

// src/lib/content/index.ts - add one line per new language
const allOverlays = {
	pt: import.meta.glob('/src/translations/pt/**/*.yaml', { eager: true }),
	es: import.meta.glob('/src/translations/es/**/*.yaml', { eager: true })
	// ko: import.meta.glob('/src/translations/ko/**/*.yaml', { eager: true }),
}

Dos pasos para agregar cualquier idioma: agregar a SUPPORTED_LOCALES en la configuración, agregar al comparador de parámetros, descomentar el glob. Todos los demás archivos lo recogen automáticamente.

Una nota sobre el dominio de integración

Esta serie crea artículos con integration: [i18n] en el frontmatter. Ese dominio no está en la lista predeterminada en config.ts - agrégalo para mantener el índice de contenido consistente y potenciar la página hub de /integrations/i18n. Abre src/lib/config.ts y extiende la constante INTEGRATION_DOMAINS o dondequiera que tu sitio registre los slugs de integración válidos:

// src/lib/config.ts - add i18n to the integration domains
export const INTEGRATION_DOMAINS = [
	'api',
	'authentication',
	'databases',
	'email',
	'ai',
	'cms',
	'animation',
	'deployment',
	'testing',
	'payments',
	'i18n' // ← add this
] as const

Si tu índice de contenido valida contra esta lista, los artículos de esta serie se compilarán sin problemas.

Las opciones del pipeline de traducción

Una vez que la arquitectura está en su lugar, hay tres formas en que las traducciones se producen realmente:

Bajo demanda en la primera solicitud: Un lector visita una URL traducida por primera vez. El servidor detecta el idioma, verifica Redis, no encuentra nada, llama a la API de Claude solo con los segmentos de prosa, almacena el resultado y sirve la página. Cada visitante posterior obtiene la versión en caché. Esto maneja la larga cola de artículos que se visitan ocasionalmente pero no vale la pena pre-traducir manualmente.

Pre-traducción por CLI: Para artículos pilares y puntos de entrada de series, ejecutas pnpm translate --slug <slug> --lang pt para traducir antes de que llegue el primer visitante. El script escribe directamente en Redis.

Traducción del catálogo con la API por lotes: Para el lanzamiento inicial de un nuevo idioma, pnpm translate:catalog --lang pt envía todos los artículos como un único trabajo por lotes procesado en 24 horas con un 50 por ciento de descuento sobre la tarifa estándar.

Cuándo los archivos YAML auxiliares estáticos tienen más sentido

El enfoque de la API de Claude bajo demanda funciona bien para la mayoría de los blogs de desarrolladores donde los artículos son largos, el tráfico por idioma es impredecible y mantener cientos de archivos de traducción manualmente es impracticable. Los archivos YAML auxiliares estáticos confirmados en el repositorio son el mecanismo primario más adecuado para:

Catálogos pequeños y estables de menos de 30 artículos aproximadamente: Cuando todo tu conjunto de contenido es lo suficientemente pequeño como para pre-traducirlo en una sola ejecución por lotes y cambia con poca frecuencia, confirmar archivos YAML auxiliares para cada artículo elimina completamente la dependencia de Upstash Redis.

Sitios de documentación: La documentación técnica tiende a ser muy estable una vez escrita. El costo de traducción se paga una vez al momento del lanzamiento de la documentación, no bajo demanda. Herramientas como Docusaurus y VitePress adoptan este enfoque de forma nativa.

Equipos con traductores dedicados: Si un traductor humano produce las traducciones en lugar de una API de máquina, necesita un archivo en el que trabajar. Un archivo YAML auxiliar es un entregable natural.

El enfoque híbrido: Para un blog en crecimiento, la elección práctica es archivos YAML auxiliares estáticos para los 10 a 15 puntos de entrada con mayor tráfico (artículos pilares, primeros artículos de series), y traducción con la API de Claude bajo demanda almacenada en caché en Upstash Redis para todo lo demás. El primer visitante de cualquier artículo sin traducir paga una espera de 3 a 6 segundos una vez; cada visitante posterior no paga nada.

Qué construye esta serie

Esta serie implementa el enfoque híbrido - traducción con la API de Claude bajo demanda almacenada en caché en Upstash Redis como mecanismo primario, con archivos YAML auxiliares estáticos opcionales para artículos pilares que merecen latencia cero en el arranque en frío.

La duplicación completa de archivos falla: 100 artículos en 3 idiomas se convierten en 300 archivos para mantener sincronizados. Un sistema de gestión de traducciones está diseñado para cadenas de interfaz de usuario, no para prosa técnica de formato largo con mucho contenido de código. Un enfoque YAML estático puro para cada artículo requiere pre-traducir todo el contenido de antemano - algo impracticable para un blog que publica regularmente.

El enfoque híbrido se ajusta a la forma real del problema. La larga cola de artículos, que puede recibir visitas ocasionales de lectores en portugués o alemán, se gestiona automáticamente en la primera solicitud y se almacena en caché de forma permanente en Upstash Redis. Agregar un tercer idioma más adelante requiere dos líneas de código.

Costo y escalabilidad

La traducción por lotes inicial es el costo individual más grande: aproximadamente $4 para 100 artículos y $22 para 500 artículos usando la API por lotes con un 50 por ciento de descuento. Después de eso, el costo continuo está determinado exclusivamente por la cantidad de artículos nuevos que publiques - cinco artículos nuevos al mes en dos idiomas cuesta aproximadamente $0.44 al mes independientemente del tamaño del catálogo. El segundo año y los siguientes cuestan mucho menos que el primero. En ambos casos, la API de traducción es el elemento de menor costo en tu presupuesto de infraestructura.

Conclusiones clave

CMS, base de datos y Markdown son tres modelos de contenido fundamentalmente diferentes - cada uno requiere una estrategia de i18n diferente
El modelo de superposición está específicamente diseñado para proyectos centrados en Markdown donde los bloques de código hacen impracticable la duplicación completa de archivos
Los artículos técnicos son del 40 al 60 por ciento código que nunca debe traducirse - el extractor de prosa elimina todo el código antes de que llegue a la API de Claude
SUPPORTED_LOCALES como única fuente de verdad significa que agregar un idioma toca dos líneas de código - la configuración y el comparador de rutas
El comparador de rutas (src/params/locale.ts) es crítico - sin él, el grupo de idiomas secuestra rutas existentes como /svelte/ y /sveltekit/
Agrega i18n a tus dominios de integración en config.ts para que la página hub en /integrations/i18n funcione correctamente

¿Qué hay de Paraglide JS?

Paraglide JS vale la pena abordar directamente porque es la propia integración de i18n oficial recomendada por SvelteKit. Es una excelente biblioteca - pero resuelve un problema diferente al que esta serie aborda.

Paraglide es una biblioteca de i18n basada en compilador para cadenas de interfaz de usuario: etiquetas de navegación, texto de botones, etiquetas de formularios, mensajes de error. Defines mensajes con claves en archivos JSON y los llamas en tus componentes - el compilador genera funciones de mensajes con tipos seguros y elimina las no utilizadas mediante tree-shaking, produciendo paquetes de i18n significativamente más pequeños.

Es la herramienta incorrecta para el contenido de artículos por tres razones concretas. Primero, las claves de mensajes no se corresponden con la prosa - una introducción de artículo de 2,000 palabras no es una etiqueta corta, y codificarla como una clave de mensaje JSON es impracticable. Segundo, todas las traducciones deben existir en tiempo de compilación, por lo que no puedes generar traducciones bajo demanda desde una API. Tercero, la optimización de tree-shaking de Paraglide no aplica a la prosa de formato largo que no debería estar en el paquete en absoluto.

La relación correcta es aditiva: un blog SvelteKit completamente internacionalizado usaría ambos. Paraglide maneja la capa de interfaz de usuario - navegación, pie de página, botones, etiquetas de metadatos - y el enfoque de la API de Claude maneja el contenido de los artículos. Operan sobre datos completamente separados y nunca entran en conflicto. Esta serie omite Paraglide por simplicidad; agregarlo más adelante para la capa de interfaz de usuario no requiere tocar la arquitectura de traducción de artículos.

Lecturas adicionales

Documentación de Paraglide JS - la recomendación oficial de i18n de SvelteKit para cadenas de interfaz de usuario
Documentación de enrutamiento de SvelteKit - comprensión de grupos de rutas y comparadores de parámetros
Documentación de la API de Claude de Anthropic - la API utilizada para la traducción bajo demanda
Upstash Redis en el Marketplace de Vercel - la capa de caché cubierta en el artículo 5, gratuita en el plan Hobby
Localización de Contentful - el enfoque CMS mencionado en este artículo
Documentación de i18n de Sanity - otro enfoque CMS para comparación