Acerca de 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 bien por debajo de $30 incluso para un catálogo de 500 artículos, y una fracción de eso cada año siguiente.

Los ejemplos a lo largo de la serie usan portugués y español como locales 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 confirmas 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 eliges depende casi por completo de dónde vive tu contenido.

Dónde vive el contenido lo define todo

Hay 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 locales, los autores escriben directamente en cada idioma dentro de la interfaz del CMS, y la API devuelve el locale correcto a solicitud. Los flujos de trabajo de traducción, los estados de aprobación y las puertas de publicación son manejados por el propio CMS.

Esta es la opción correcta cuando autores no técnicos gestionan contenido en múltiples idiomas y las herramientas de flujo de trabajo editorial son un requisito indispensable. La contrapartida es que el CMS se convierte en una dependencia para cada renderizado de página, el contenido queda bloqueado 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 operaciones de contenido grandes 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 consultas, y cada carga de página golpea 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 puede desplegar 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. La contrapartida es que las herramientas editoriales estilo CMS no existen por defecto, pero para un blog de desarrollador no las necesitas.

Esta serie se centra en archivos Markdown

Si tu contenido vive en un CMS, el CMS maneja 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 locales. 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á diseñada específicamente 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 centra 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 los bloques de código, la estructura y los 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 que priorizan Markdown, la traducción bajo demanda resuelve un problema que ni los enfoques 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 locale 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 de riesgo cero: configuración de locales con tipos TypeScript adecuados, detección de locale en hooks.server.ts, el atributo HTML lang, el comparador de rutas (src/params/locale.ts) que evita que el grupo de locales secuestre rutas existentes, y el grupo de rutas (locale)/[lang=locale]/ que agrega rutas traducidas sin modificar 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, además del 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 de marked v15 y Shiki, la configuración de la clave de la API de Claude, y la implementación completa de +page.server.ts usando translateBatch para traducción fragmentada con reintentos.

Artículo 5 agrega la caché de traducción Upstash Redis: configuración paso a paso en Vercel Marketplace, el módulo de caché con TTL condicional (permanente para traducciones completas, 2 horas para las incompletas), escrituras HTML de tipo fire-and-forget, 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 desplegar, y el pipeline de traducción de catálogo con la API de Lotes para traducir cientos de artículos de noche con un 50 por ciento de descuento.

Lee los seis en orden para 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 se triplica en 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 directo a ella.

La trampa persiste porque hace que lo incorrecto parezca obvio. Cuando piensas "traducir este artículo", el instinto es copiar el archivo completo y dárselo a un traductor. Eso funciona perfectamente para un sitio de marketing donde el contenido es pura prosa. Falla gravemente para un blog técnico donde del 40 al 60 por ciento de cada artículo es código que nunca debe traducirse, 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, ayuda 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, hidratación, Vite
Campos estructurales de 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 de 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 (mantenlos 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 traducirse limpiamente entre idiomas

En un artículo típico de SvelteKit de 3,000 palabras, aproximadamente 1,200 palabras 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 agregas.

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 locale es solo la prosa - las oraciones y párrafos que un lector realmente lee.

La ruta de traducción principal 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 después de ellos obtiene el resultado en caché al instante.

El archivo .md nunca se duplica. Los bloques de código nunca abandonan el servidor. El código fuente en inglés permanece intacto en todos los locales.

Para artículos importantes - contenido pilar y puntos de entrada de series - hay una ruta 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 lote 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ático, el servidor lo usa directamente sin llamada a la API. Cuando no existe, la ruta bajo demanda lo maneja automáticamente.

Por qué esto es mejor que cualquier alternativa

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 automáticamente la actualización 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 Markdown completo a una API de traducción es costoso e imprudente. Los modelos de traducción ocasionalmente corrigen nombres de variables, traducen literales de cadena 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 ni un solo acento grave.

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

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 analíticas. El modelo de superposición hace que la traducción sea lo suficientemente barata 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 pieza del sistema que varía por locale - validación de rutas, generación de hreflang, namespacing de claves de caché, scripts de traducción - lee de ese único array 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 capturan 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 /integrations/i18n. Abre src/lib/config.ts y extiende la constante INTEGRATION_DOMAINS o donde sea 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 limpiamente.

Las opciones del pipeline de traducción

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

Bajo demanda en la primera solicitud: Un lector visita una URL traducida por primera vez. El servidor detecta el locale, verifica Redis, no encuentra nada, llama a la API de Claude con solo 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 de catálogo con la API de Lotes: Para el lanzamiento inicial de un nuevo idioma, pnpm translate:catalog --lang pt envía todos los artículos como un único trabajo en lote procesado dentro de 24 horas con un 50 por ciento de descuento sobre la tarifa estándar.

Cuándo los archivos auxiliares YAML 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 locale es impredecible y mantener cientos de archivos de traducción manualmente es poco práctico. Los archivos auxiliares YAML estáticos confirmados en el repositorio son el mecanismo primario más adecuado para:

Catálogos pequeños y estables de menos de aproximadamente 30 artículos: 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 por completo 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 en el momento del lanzamiento de la documentación en lugar de 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 son archivos YAML auxiliares estáticos para los 10 a 15 puntos de entrada de mayor tráfico (artículos pilares, openers de series), y traducción bajo demanda con la API de Claude almacenada en caché en Upstash Redis para todo lo demás. El primer visitante de cualquier artículo no traducido 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 bajo demanda con la API de Claude almacenada en caché en Upstash Redis como mecanismo principal, con archivos YAML auxiliares estáticos opcionales para artículos pilares que merecen latencia cero de 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 UI, no para prosa técnica de formato largo con contenido de código pesado. 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 maneja automáticamente en la primera solicitud y se almacena en caché permanentemente en Upstash Redis. Agregar un tercer locale más adelante requiere dos líneas de código.

Costo y escalabilidad

La traducción inicial por lotes es el mayor costo único: aproximadamente $4 para 100 artículos y $22 para 500 artículos usando la API de Lotes con un 50 por ciento de descuento. Después de eso, el costo continuo está determinado enteramente por cuántos artículos nuevos publicas - cinco artículos nuevos al mes en dos locales 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 la partida más pequeña 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á diseñado específicamente para proyectos que priorizan Markdown donde los bloques de código hacen que la duplicación completa de archivos sea poco práctica
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 locales 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 abordarlo directamente porque es la propia integración de i18n oficial recomendada por SvelteKit. Es una excelente librería - pero resuelve un problema diferente al que aborda esta serie.

Paraglide es una librería de i18n basada en compilador para cadenas de UI: etiquetas de navegación, texto de botones, etiquetas de formularios, mensajes de error. Defines mensajes con clave 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 mensaje no se corresponden con la prosa - una introducción de artículo de 2,000 palabras no es una etiqueta corta, y codificarla como 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 se aplica a la prosa de formato largo que no debería estar en el bundle en absoluto.

La relación correcta es aditiva: un blog SvelteKit completamente internacionalizado usaría ambos. Paraglide maneja la 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 después para la capa de UI no requiere tocar la arquitectura de traducción de artículos.

Lectura adicional

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