Por Qué Dediqué 18 Horas a un Proyecto de Traducción 'Simple'

“Necesitamos el sitio en español.”

Cinco palabras que podían significar una tarde rápida con un plugin de traducción, o dos días de trabajo metódico construyendo infraestructura adecuada. Elegí lo segundo, y no porque disfrute tomar el camino largo.

The Chorotega Hotel es un retiro de hospitalidad espiritual en Montezuma, en la Zona Azul de Costa Rica. Su sitio web sirve a dos audiencias distintas: turistas de habla inglesa que reservan habitaciones desde el extranjero, y personal de habla hispana y socios locales que gestionan las operaciones. Una traducción mal hecha no serviría bien a ninguno de los dos grupos.

Esta es la historia de por qué la internacionalización adecuada importa, qué se necesita realmente para hacerlo bien, y el valor de negocio que viene de no tomar atajos.

El Problema: Más Que Solo Palabras

Cuando los clientes piden traducción, usualmente están pensando en el texto visible—botones, encabezados, descripciones. Pero un sitio web bilingüe es un desafío mucho más profundo:

• 19 componentes a través de 3 páginas principales
• 10 descripciones detalladas de habitaciones
• 8 respuestas de preguntas frecuentes sobre geografía local
• Mensajes de validación de formularios que se ejecutan en JavaScript
• Metadatos SEO y datos estructurados
• Estructuras de URL que necesitan funcionar en ambos idiomas
• Un sistema de diseño que había crecido orgánicamente sin estándares

Podía ver dos caminos hacia adelante. El rápido: instalar un plugin, pasar el contenido por una herramienta de traducción, darlo por terminado. El correcto: construir infraestructura adecuada que serviría al negocio por años.

El camino rápido tomaría una tarde. El camino correcto tomaría 18 horas de trabajo enfocado.

Por Qué los Atajos se Acumulan

He tomado atajos antes. Todos lo hemos hecho. Y he aprendido que cada atajo que tomas hoy es un problema que heredas mañana.

Un plugin de traducción podría funcionar bien inicialmente, pero ¿qué sucede cuando:

• Necesitas actualizar una traducción y no recuerdas cómo funciona el plugin?
• El plugin se actualiza y rompe tu construcción?
• Necesitas agregar un tercer idioma?
• Tu JavaScript del lado del cliente necesita cadenas traducidas?

Cada uno de estos se convierte en un rompecabezas para resolver después, usualmente cuando estás bajo presión y no tienes tiempo para pensar con claridad.

La alternativa es infraestructura: un sistema que es transparente, mantenible y predecible.

Construyendo la Fundación

Elegí el enfoque i18n nativo de Astro sobre bibliotecas de terceros por tres razones:

Enrutamiento basado en archivos. Cada idioma obtiene su propia ruta (/ para inglés, /es/ para español). URLs limpias que funcionan excelente para SEO, sin complejidad de middleware.

Seguridad de tipos. Usar TypeScript con un archivo de traducción centralizado significa autocompletado para cada clave. Si escribo algo mal, mi editor lo detecta antes de que la construcción siquiera se ejecute.

Escala. Ya sea que The Chorotega agregue portugués el próximo año o se quede con dos idiomas para siempre, la arquitectura lo soporta sin una refactorización.

La estructura es directa:

// src/i18n/ui.ts
export const ui = {
  en: {
    'nav.home': 'Home',
    'nav.about': 'About',
    // ... 290+ claves
  },
  es: {
    'nav.home': 'Inicio',
    'nav.about': 'Sobre Nosotros',
    // ... 290+ claves
  },
} as const;

Sin magia. Sin sorpresas en tiempo de ejecución. Solo un sistema que es fácil de entender dentro de seis meses.

El Trabajo de Traducción

290+ claves de traducción a través de todo el sitio. Descripciones de habitaciones que necesitaban mantener la voz cálida y espiritual de la marca en ambos idiomas. Respuestas de FAQ explicando geografía costarricense. Mensajes de validación de formularios. Metadatos SEO. Datos estructurados Schema.org para motores de búsqueda.

Cada traducción tenía que sentirse natural en español mientras preservaba el significado y tono. “Spiritual hospitality” y “Blue Zone living” no son frases que puedas simplemente pasar por un traductor y darlo por terminado.

Una decisión que tomé temprano: las citas de testimonios se quedan en inglés. Son reseñas auténticas de huéspedes, y traducirlas se sentiría poco genuino. Todo lo demás recibió el tratamiento bilingüe completo.

Resolviendo el Desafío del Lado del Cliente

La parte más complicada fue la validación de formularios. La mayoría del contenido se renderiza en tiempo de construcción en un sitio estático, pero los mensajes de validación se ejecutan en el navegador vía JavaScript. ¿Cómo haces que estos sean conscientes del idioma sin cargar archivos de traducción en tiempo de ejecución?

La solución: pasar traducciones como atributos de datos en el elemento del formulario.

<form data-validation-required={t('contact.validation.required')} 
      data-validation-email={t('contact.validation.invalidEmail')}>
  <!-- campos del formulario -->
</form>

<script>
  const form = document.querySelector('form');
  const messages = {
    required: form.dataset.validationRequired,
    invalidEmail: form.dataset.validationEmail
  };
  // Usar mensajes en la lógica de validación
</script>

El navegador obtiene las cadenas traducidas en tiempo de construcción. JavaScript las usa en tiempo de ejecución. Problema resuelto, sin complejidad.

Arreglando lo Que Ya Estaba Ahí

Con las traducciones completas, di un paso atrás y vi lo que había estado ignorando por semanas: inconsistencia. Tarjetas con diferentes rellenos. Bordes que variaban. Niveles de encabezados que no tenían sentido semántico.

Si ya estaba tocando cada componente para las traducciones, ¿por qué no establecer estándares reales?

Creé un documento de especificación de diseño que catalogaba cada color, tamaño de fuente, patrón de componente y animación. Reveló:

• 8 tipos diferentes de tarjetas con relleno inconsistente
• Colores de fondo mezclados (bg-white/60, bg-white/70, bg-white/80)
• Jerarquía tipográfica que podía ser más limpia

Luego apliqué estándares a través de todo el sitio:

• Todas las tarjetas: relleno consistente p-4
• Todos los bordes: border-0 para una apariencia limpia y moderna
• Todos los contenedores: max-w-8xl para espacio para respirar
• Todos los niveles de encabezados: mejor jerarquía semántica
• Todos los fondos: unificados a bg-background/60

Cada componente actualizado. Consistencia perfecta.

Los Detalles se Acumulan

Una diferencia de 2px en el relleno no parece mucho hasta que tienes 50 tarjetas a través de 8 secciones, todas con espaciado ligeramente diferente. Entonces se siente caótico.

El modal de galería de habitaciones fue un buen ejemplo. Las miniaturas se superponían, el modal se sentía estrecho, las flechas de navegación eran difíciles de ver. Algunas mejoras enfocadas marcaron toda la diferencia:

• Miniaturas de desplazamiento horizontal sin superposición
• Modal dimensionado a 90vw en escritorio para un área de visualización generosa
• Botones de flecha más grandes con estados de hover claros
• Resaltado de miniatura activa
• Vistas previas de comodidades en las tarjetas de habitaciones

Cambios pequeños. Gran impacto en la experiencia del usuario.

El cliente también quería que las habitaciones destacadas “realmente resaltaran.” En lugar de solo hacer la insignia más grande, agregué bordes degradados con animaciones de pulso sutiles, insignias mejoradas con íconos, y fondos más brillantes. Ahora cuando desplazas a través de las habitaciones, las destacadas—Papaya, Bamboo y Mango—demandan tu atención.

Por Qué la Documentación Importa

Mantuve documentación detallada a través de este proyecto. No porque disfrute escribir especificaciones, sino porque dentro de seis meses cuando necesite agregar una nueva sección o actualizar una traducción, no estaré adivinando.

Cada decisión está registrada. Cada patrón está documentado. Cada estándar está explicado.

Eso no es trabajo innecesario. Eso es seguro contra el caos futuro.

Lo Que Esto Realmente Me Enseñó

Los estándares no son restricciones; son libertad. Una vez que establecí el estándar de estilo de tarjetas, dejé de pensar en esas decisiones. Solo apliqué el patrón. Eso liberó energía mental para problemas que realmente requerían creatividad.

La documentación es una conversación con tu yo futuro. Cada vez que escribo algo, estoy ayudando a la versión de mí que tiene que mantener este código dentro de seis meses. Ese tipo siempre aprecia el esfuerzo.

La consistencia se acumula. Cada pequeña inconsistencia crea carga cognitiva. Multiplica eso por docenas de componentes y cientos de elementos, y has creado una experiencia sutilmente caótica. Límpialo, y todo simplemente se siente mejor.

El viaje enseña más que el destino. Podría haber usado un agente de IA para hacer estos cambios en una fracción del tiempo. Pero no habría internalizado los patrones. No habría desarrollado opiniones sobre lo que funciona. No habría construido la memoria muscular que hace el próximo proyecto más fácil.

El Stack Técnico

Para los desarrolladores leyendo esto:

Framework Principal:

• Astro 5.14.4 con i18n nativo
• TypeScript para traducciones con seguridad de tipos
• Tailwind CSS para estilos
• Enrutamiento basado en archivos para variantes de idioma

Seguridad de Tipos:

export const ui = { /* ... */ } as const;
export type TranslationKey = keyof typeof ui['en'];

Cada t('some.key') tiene verificación de tipos. La refactorización es segura. El autocompletado funciona en todas partes.

Implementación SEO:

• Etiquetas hreflang para variantes de idioma
• Meta etiquetas y descripciones traducidas
• og:locale y og:locale:alternate para compartir en redes sociales
• Datos estructurados Schema.org en ambos idiomas

El sitio no solo funciona en dos idiomas; está optimizado para descubrimiento en ambos idiomas.

El Valor de Negocio

Esto no fue solo un ejercicio técnico. The Chorotega Hotel sirve a un mercado bilingüe—turistas de habla inglesa reservando habitaciones desde el extranjero, y personal de habla hispana y socios locales gestionando operaciones.

Un plugin de traducción rápido les habría dado palabras en dos idiomas. Pero no les habría dado un sistema mantenible. Ahora cuando necesiten agregar una nueva descripción de habitación o actualizar información de precios, es directo. La estructura soporta el negocio, no al revés.

Ese es el valor real: infraestructura que no solo funciona hoy, sino que todavía tendrá sentido dentro de un año cuando alguien necesite hacer cambios.

Reflexiones

“Cómo haces cualquier cosa es cómo haces todo.”

Podría haber apresurado las traducciones. Podría haber omitido las mejoras de UX. Podría haber ignorado las inconsistencias. Pero cada uno de esos atajos habría sido un pequeño compromiso, y los pequeños compromisos se acumulan.

En cambio, tomé el tiempo para construir infraestructura adecuada, documentar decisiones, aplicar estándares consistentemente, e iterar sobre los detalles. El resultado es una base de código de la que estoy orgulloso y que servirá bien a The Chorotega en el futuro.

¿Vale la pena 18 horas en lugar de una tarde? Para mí, sí. Porque el valor no está solo en lo que entregué—está en lo que aprendí, en los estándares que establecí, y en la confianza de que este sistema será mantenible dentro de seis meses.

La Conclusión

Si estás enfrentando un proyecto similar—ya sea i18n, una refactorización importante, o algo completamente diferente—esto es lo que recomendaría:

Entiende lo que tienes antes de cambiarlo. Haz un inventario. No puedes mejorar lo que no entiendes.

Construye infraestructura, no hagas soluciones improvisadas alrededor de problemas. Los atajos que tomas hoy se convierten en los problemas que heredas mañana.

Establece estándares y aplícalos consistentemente. Una vez que tienes un patrón, deja de pensar en esas decisiones y enfócate en problemas que realmente requieren creatividad.

Documenta para tu yo futuro. Dentro de seis meses, estarás agradecido.

Este proyecto me recordó por qué hago este trabajo. No se trata de producir características o cumplir plazos. Se trata del oficio de construir algo bien—algo que sirve su propósito, mantiene sus estándares, y todavía tendrá sentido cuando vuelvas a él más tarde.

Ese es el tipo de trabajo que se siente que vale la pena hacer.

---

Si alguna vez estás en Montezuma, Costa Rica, visita The Chorotega Hotel. Y si estás trabajando en un sitio bilingüe, espero que esto te haya dado algunas ideas.

Gracias por leer.

Enlaces:

• The Chorotega Hotel: thechorotega.com
• Receta i18n de Astro: docs.astro.build/en/recipes/i18n