Cómo automatice mi propia documentación multilingüe con Localizeflow
Updated: 2/24/2026 · 6 min read
Mantener dos idiomas manualmente estaba matando mi concentración. Aquí te cuento cómo automatice la propia documentación de Localizeflow usando Localizeflow.
El problema: la traducción no era difícil. La sincronización sí.
Durante los últimos tres meses, he estado gestionando tanto la documentación como el contenido del blog en coreano e inglés.
Mi flujo de trabajo era simple:
- Redactar en coreano.
- Crear la versión en inglés.
- Mantener ambas con el tiempo.
Al principio, parecía manejable.
En muchos casos, podía pedirle a la IA que actualizara el otro idioma, y funcionaba sorprendentemente bien.
Por un tiempo, eso se sintió eficiente.
Pero una vez que la documentación comenzó a evolucionar más rápido — nuevas características, capturas de pantalla actualizadas, cambios en la API — las cosas empezaron a romperse silenciosamente.
Cada vez que actualizaba la versión en inglés, tenía que:
- Recordar que el coreano también necesitaba actualización.
- Encontrar manualmente qué había cambiado.
- Verificar dos veces que no hubiera omitido nada.
Al principio, mantenía ambas versiones perfectamente sincronizadas.
Pero en algún punto, noté algo incómodo:
Estaba actualizando la documentación en inglés de inmediato…
y diciéndome a mí mismo que “actualizaría el coreano después.”
El después raramente llegaba.
La traducción en sí no era la parte difícil.
Lo difícil era mantener sincronizados dos idiomas.
Y como fundador, mi enfoque no debería estar en buscar párrafos desactualizados en varios idiomas.
En algún punto, me di cuenta de algo un poco irónico:
Estaba construyendo un producto de automatización de localización
y mantenía manualmente mi propia documentación multilingüe.
Eso no tenía sentido.
Así que decidí usar Localizeflow en la propia documentación y blog de Localizeflow.
La decisión: automatizar o descartar un idioma
Solo había dos opciones realistas:
- Dejar de mantener el coreano.
- O automatizar el flujo de trabajo.
Descartar un idioma se sentía mal.
Pero continuar manualmente se sentía ineficiente.
Si la documentación multilingüe requiere disciplina y atención constante,
no sobrevivirá en una startup que se mueve rápido.
Así que en lugar de eliminar un idioma,
decidí eliminar la fricción.
Instalé Localizeflow en nuestro repositorio de documentación.
Sin YAML.
Sin configuración extra.
Solo instalación de la app de GitHub.
Eso fue todo.
No quería otro panel de control.
No quería otro portal de traducción.
Quería que mi flujo de trabajo actual en GitHub se mantuviera intacto.
Y así fue.
Si tienes curiosidad sobre el flujo exacto de integración, puedes consultar la guía de configuración:
https://docs.localizeflow.com/
Antes de profundizar, una nota rápida sobre la pila tecnológica.
Usamos Astro como nuestro generador estático de sitios.
Astro no ofrece soporte multilingüe muy opinado por defecto — al menos, no como lo hacen algunos frameworks de documentación.
Eso fue intencional.
Quería probar Localizeflow en un entorno menos “ayudoso” primero.
Si funciona bien con Astro, debería funcionar aún más suavemente con Hugo, Docusaurus o Mintlify — que ofrecen primitivas de i18n más robustas.
Ahora, lo que realmente cambió.
Cómo fue realmente la configuración
Después de instalar la App de GitHub durante el registro, conecté mi repositorio de documentación haciendo clic en el botón “Connect repositories”.
Una vez conectado, al hacer clic en el repositorio entras en el flujo de incorporación.
En lugar de un proceso largo de configuración, se resumió en tres decisiones:
- Idiomas
- Estructura de salida
- Reglas del glosario
Todo el proceso tomó unos minutos.
Lo que me llamó la atención no fue solo la velocidad,
sino que no tuve que modificar la infraestructura.
No agregué scripts de CI.
No reestructuré carpetas.
Principalmente confirmé cómo funcionaba mi repositorio ya.
Eso me pareció importante.
Porque en mi experiencia, las herramientas de “automatización” suelen requerir cambios en el sistema.
Esta no.
1. Selección de idiomas objetivo
La primera decisión fue la selección de idiomas objetivo.
Cada idioma se convierte en su propio flujo de Pull Requests de traducción.
Esa elección de diseño hace que los cambios sean visibles, no ocultos.
Se integra naturalmente en un flujo de trabajo de GitHub.
2. Definición de dónde viven las traducciones
Para las rutas de salida, usé la función de análisis del repositorio.
Escaneó el repositorio y sugirió rutas de origen y destino.
Revisé la sugerencia y la confirmé.
Antes de continuar, revisé la vista previa de cómo se vería la estructura de carpetas después de que se generaran las traducciones.
Esa vista previa fue importante.
Mostraba exactamente dónde vivirían los archivos traducidos, sin modificar nada aún.
No tuve que razonar manualmente sobre el mapeo de carpetas desde cero.
Simplemente validé lo que el sistema infería de la estructura existente.
3. Reglas del glosario
Antes de terminar la configuración, añadí un pequeño glosario.
Términos como:
- Localizeflow
- GitHub App
- Co-op Translator
se mantienen sin cambios en las traducciones.
Eso ahorra correcciones repetitivas en Pull Requests más tarde.
Tiempo total de configuración
Menos de cinco minutos.
Pero más importante:
No reconfiguré CI.
No creé nuevos pipelines.
No migré carpetas.
La configuración no se sintió como adoptar un sistema nuevo.
Se sintió como habilitar una capacidad dentro del que ya tenía.
Qué pasa cuando edito en inglés ahora
Esto fue lo que cambió en la práctica.
Antes:
- Editaba la documentación en inglés.
- Abría manualmente la doc en coreano.
- Buscaba las secciones cambiadas.
- Actualizaba.
- Hacía commit en ambas.
Ahora:
- Actualizo el archivo Markdown en inglés.
- Localizeflow detecta cambios en el contenido mediante comparación hash.
- Se genera automáticamente un Pull Request de traducción.
- Reviso y hago merge.
Eso es todo.
Ya no “hago traducción.”
Reviso un PR.
Y esa diferencia psicológica es enorme.
Después de la configuración, el panel de Localizeflow no es algo que vigile activamente.
El progreso del trabajo se publica directamente en el Pull Request como actualizaciones estructuradas de estado.
Si abres el PR, ves inmediatamente:
- Progreso actual
- Idiomas completados
- Trabajos restantes
- Cualquier fallo
Se comporta más como un estado de CI que como una herramienta de traducción separada.
Ese diseño hace que se sienta nativo en GitHub.
Qué mejoró realmente
1. Ahora pienso en un solo idioma
Solo actualizo la fuente en inglés.
Ya no me pregunto:
“¿Actualicé también el coreano?”
Esa carga cognitiva desapareció.
2. Los cambios no se acumulan
Antes, pequeñas actualizaciones se acumulaban porque actualizar ambos idiomas se sentía molesto.
Ahora, incluso las ediciones mínimas de la doc se sienten fáciles.
Lo que significa que la calidad de la documentación mejora indirectamente.
3. Se mantiene en mi flujo de trabajo
Todo sucede a través de Pull Requests.
No hay panel separado.
Solo revisar y hacer merge.
4. El tiempo de actualización bajó a minutos
Antes, incluso un pequeño cambio en la documentación significaba tocar dos archivos.
Ahora, actualizar una página toma el mismo tiempo sin importar cuántos idiomas soportemos.
El coste marginal de añadir un idioma es efectivamente cero.
Qué todavía necesita trabajo
El uso real también mostró algunas limitaciones:
-
Con Astro, después de que se generan las traducciones, todavía necesitaba ajustar manualmente ciertas URLs para referenciar correctamente las rutas localizadas. Esto puede no ser un problema con generadores estáticos que proveen un enrutamiento i18n incorporado más fuerte.
-
Implementé un conmutador de idiomas simple en el encabezado para facilitar la navegación entre páginas localizadas.
Incluso con estos pequeños pasos manuales, el esfuerzo general de mantenimiento es dramáticamente menor.
El resultado real
Antes:
Mantener dos idiomas se sentía como una carga extra.
Ahora:
Mantener múltiples idiomas se siente sostenible.
Y eso cambia la ecuación estratégica.
Cuando la localización deja de ser dolorosa,
el alcance global se vuelve algo natural — no una carga.
Reflexión final
Esto no se trataba de demostrar que el producto funciona.
Se trataba de demostrar que el flujo de trabajo funciona bajo presión real de un fundador.
Cuando estás construyendo funciones, hablando con usuarios, manejando operaciones —
la documentación es lo primero que se descuida.
Si la documentación multilingüe requiere disciplina,
no sobrevivirá.
Si solo requiere revisar un PR,
puede que sí.
Usar Localizeflow internamente dejó algo claro:
La traducción es fácil.
La sincronización es el verdadero problema.
Y la sincronización se puede automatizar.
A quién va dirigido esto
Este flujo de trabajo puede resonar contigo si:
- Mantienes README multilingües
- Gestionas un proyecto OSS que avanza rápido
- Manejas documentación pesada en MDX
- Actualizas frecuentemente ejemplos, capturas o referencias API
- O simplemente olvidas actualizar las traducciones después de cambiar la fuente
Si la documentación multilingüe solo se siente sostenible cuando las cosas van lento,
probablemente no sobrevivirá cuando tu proyecto empiece a avanzar más rápido.
La automatización no elimina la responsabilidad.
Elimina la fricción.
Y en entornos que se mueven rápido,
eliminar la fricción es a menudo lo que hace posible la consistencia.
Si mantienes documentación multilingüe y quieres ver cómo se vería esto en tu repositorio,
con gusto te guío con un ejemplo en vivo.