Por qué construimos Localizeflow
Updated: 11/28/2025 · 4 min read
La documentación técnica requiere más que traducción. Necesita una línea automatizada que preserve la estructura, el contexto y la coherencia entre idiomas.
La documentación técnica es un sistema vivo
La documentación técnica evoluciona continuamente a medida que un producto evoluciona.
Cada adición de función, actualización o cambio en la API requiere actualizaciones en la documentación, y esas actualizaciones deben reflejarse en todos los idiomas, no solo en el original.
Traducir texto es la parte fácil.
Mantener las versiones traducidas consistentemente actualizadas es el verdadero desafío.
En la práctica, mantener documentación multilingüe introduce un flujo constante de trabajo:
- rastrear qué páginas cambiaron
- identificar qué secciones requieren retraducción
- asegurar que los bloques de código, HTML, frontmatter y el formato permanezcan intactos
- preparar PR limpios para revisión
- gestionar estructuras de directorio cada vez más complejas
Cuanta más documentación tengas, más pesado se vuelve este costo operativo.
Después de gestionar varios proyectos de documentación por mí mismo, una conclusión se volvió imposible de ignorar:
La documentación es más difícil de mantener que de traducir.
FastAPI hizo visible el problema para todos
En 2025, el equipo de FastAPI anunció que dejarían de depender de PRs de traducción impulsados por la comunidad y pasarían a una canalización interna automatizada.
Esto fue revelador.
El problema no se limitaba a un gran proyecto open-source. Reflejaba un problema universal que enfrenta cualquier equipo que mantiene documentación multilingüe.
Los proyectos grandes pueden permitirse construir sistemas internos.
La mayoría de equipos, mantenedores pequeños de OSS y startups en etapas tempranas no pueden.
Localizeflow fue creado para abordar esta realidad.
Necesitábamos una canalización, no otra herramienta de traducción
Localizeflow nunca estuvo pensado para ser un simple traductor.
Lo que queríamos era un sistema donde cada paso disparado por una actualización de documentación fluya automáticamente dentro de GitHub:
- actualizar un documento y solo se regeneren los idiomas requeridos
- se preserve la estructura Markdown
- código, HTML y frontmatter permanezcan intactos
- las imágenes se escaneen y traduzcan
- los resultados aparezcan como un PR limpio listo para revisión
Una instalación de GitHub App.
Sin scripts personalizados.
Sin manejo manual de directorios.
Una canalización completa que se activa cuando la documentación cambia.
Por qué regeneramos a nivel de estructura del documento
La mayoría de herramientas de traducción operan al nivel de oración.
La documentación técnica no es una lista de oraciones. Es una combinación estructurada de Markdown, metadatos, ejemplos de código, diagramas y plantillas.
Localizeflow evalúa los cambios al nivel de estructura del documento y regenera la salida en consecuencia.
El diff puede ser mayor a veces, pero los beneficios son claros:
- terminología consistente
- contexto preservado
- estructura de documento estable
En múltiples proyectos reales, este método demostró ser significativamente más confiable.
Construido sobre el motor Co-op Translator
Localizeflow está impulsado por el motor Co-op Translator.
Este sistema fue desarrollado a través de más de un año traduciendo y manteniendo documentación real en GitHub.
No es un envoltorio alrededor de una API.
Es un motor probado en producción usado en varias canalizaciones de documentación open-source de Microsoft hoy en día.
Incluye:
- análisis robusto de Markdown
- preservación de código, HTML y frontmatter
- traducción de diagramas Mermaid
- extracción y traducción de texto en imágenes
- características de consistencia de terminología y contexto
Estas capacidades se construyeron porque los flujos de trabajo reales de documentación las requerían.
A medida que motores de documentación como Astro, Hugo y Docusaurus se popularizan, el volumen y la complejidad del contenido siguen aumentando.
Mantener la documentación actualizada se ha convertido en una ventaja de producto.
Localizeflow existe porque esta necesidad ahora es fundamental.
El idioma sigue siendo una barrera en tecnología
Operar Co-op Translator reveló una verdad clara.
Muchos desarrolladores aún no pueden acceder a documentación de alta calidad en su propio idioma.
La documentación es parte del producto.
Si la información se retrasa o es difícil de acceder, el aprendizaje se ralentiza, los ciclos de retroalimentación se amplían y la adopción del producto disminuye.
La misión de Localizeflow es simple:
Ningún equipo debería tener que construir su propio sistema de traducción.
Ya sea DevRel, equipos de documentación, compañías SaaS, mantenedores OSS o startups en etapas tempranas, una actualización de documentación debe actualizar automáticamente todos los idiomas, regenerar solo los cambios necesarios y producir un único PR para revisión.
Localizeflow existe para remover el punto de quiebre
La mayoría de equipos eventualmente renuncian a mantener documentación multilingüe.
A medida que la documentación crece y las actualizaciones se vuelven frecuentes, las traducciones rápidamente quedan desfasadas.
Localizeflow apunta a remover ese punto de quiebre.
No solo facilita la traducción.
Hace que mantener la documentación traducida sea sostenible.