Índice
La mayoría de los AI translation tools siguen el mismo patrón: pegar texto, obtener traducción. Eso funciona para un correo rápido, pero falla cuando se gestionan miles de claves de traducción en una aplicación de producción con múltiples idiomas, un glosario de términos de marca y un equipo que necesita revisar los cambios antes de publicarlos.
Construimos el sistema AI de Better i18n de forma diferente. En lugar de una simple API de traducción, creamos un agent conversacional con 23 herramientas especializadas, aprobación Human-in-the-Loop para cada operación de escritura y una arquitectura diseñada para flujos de trabajo reales de gestión de traducciones.
Este artículo explica la ingeniería detrás de todo ello.
¿Por qué un Agent y no una API de traducción?
El flujo de trabajo típico de revisión de traducción automática se ve así: exportar cadenas, enviarlas a un servicio de traducción, recibir los resultados, importarlos, revisar manualmente, corregir problemas, re-exportar. Es lento, propenso a errores y desconecta el proceso de traducción del contexto que hace que las traducciones sean precisas.
Un enfoque basado en Agent cambia el modelo de forma fundamental. En lugar de operar sobre archivos, la AI opera directamente sobre tu proyecto — leyendo tus claves, entendiendo tu glosario, verificando tu configuración de sincronización y proponiendo cambios que apruebas en tiempo real.
La clave está en que la gestión de traducciones no es una tarea única. Es un flujo de trabajo que implica leer el estado del proyecto, tomar decisiones, ejecutar cambios y verificar resultados. Un Agent con múltiples herramientas maneja esto de forma natural. Una API de traducción no.
La arquitectura de 23 herramientas
El Agent tiene acceso a 23 herramientas de propósito específico, divididas en dos categorías con modelos de permisos muy diferentes.
Herramientas de lectura: Autonomía total
Diez herramientas dan al Agent acceso de lectura a tu proyecto. Estas se ejecutan automáticamente sin requerir aprobación, porque no pueden modificar datos:
- getTranslations — obtiene traducciones con filtrado por clave, namespace, idioma y estado
- getKeyDetails — recupera metadatos para claves individuales incluyendo notas de contexto, etiquetas y estado por idioma
- getLanguages — lista los idiomas configurados con porcentajes de completitud
- getProjectStats — devuelve métricas de todo el proyecto: claves totales, idiomas, cobertura de traducción
- getDoctorReport — ejecuta diagnósticos para identificar traducciones faltantes, claves no utilizadas, problemas con formas plurales e inconsistencias de terminología
- getSyncs y getSyncDetails — inspecciona integraciones de sincronización con GitHub/GitLab y su actividad reciente
- getContentModels y getContentEntries — navega la estructura de contenido CMS y las entradas
- createPlan — genera un plan de ejecución cuando el Agent necesita coordinar múltiples pasos
El Agent usa estas herramientas para construir contexto antes de proponer cualquier cambio. Cuando preguntas "traduce todas las claves faltantes al francés", el Agent primero llama a getTranslations para identificar exactamente qué claves faltan, luego llama a getProjectStats para entender el alcance, antes de generar una propuesta única y concreta.
Herramientas de escritura: Aprobación Human-in-the-Loop
Once herramientas pueden modificar los datos de tu proyecto. Cada una de ellas requiere aprobación humana explícita antes de ejecutarse. Este es el núcleo de nuestro enfoque para la calidad de traducción AI — la AI propone, el humano decide.
Herramientas de traducción:
- proposeTranslations — genera nuevas traducciones para claves que faltan en los idiomas de destino
- proposeTranslationEdits — sugiere mejoras a las traducciones existentes basándose en el contexto, el glosario o tu feedback
- translateBatch — procesa múltiples claves en múltiples idiomas en una sola operación
Herramientas de gestión de claves:
- proposeKeys — sugiere nuevas claves de traducción basándose en el análisis del codebase
- proposeDeleteKeys — identifica claves no utilizadas o duplicadas y propone su eliminación
Herramientas de gestión de idiomas:
- proposeLanguages — recomienda nuevos idiomas para añadir según las necesidades del proyecto
- proposeLanguageEdits — modifica nombres de visualización de idiomas, cadenas de fallback o configuración
Herramientas de publicación:
- publishChanges — envía las traducciones aprobadas al CDN o activa un GitHub PR
Herramientas de gestión de contenido:
- proposeContentEntries — crea o actualiza entradas de contenido CMS
- proposeContentModel — sugiere cambios de esquema en los modelos de contenido
- proposePublishEntries — pone en cola entradas de contenido para publicación
Human-in-the-Loop: La ingeniería del flujo de aprobación
El término "Human-in-the-Loop" se usa mucho en el marketing de AI. Aquí se explica cómo funciona realmente en nuestro sistema.
Cuando se llama a una herramienta de escritura, el Agent no la ejecuta directamente. En su lugar, genera una propuesta — un diff estructurado que muestra exactamente qué va a cambiar. La propuesta aparece en la interfaz de chat como un artefacto revisable.
Para las propuestas de traducción, verás:
- La cadena de origen en tu idioma base
- La traducción propuesta en el idioma de destino
- Los términos del glosario que se aplicaron
- El contexto de confianza (¿es esto una etiqueta simple de UI o una frase compleja de marketing?)
Luego tienes tres opciones:
- Aprobar todo — aceptar todos los cambios propuestos con un clic
- Aprobación selectiva — aceptar algunas traducciones y rechazar otras
- Solicitar cambios — decirle al Agent qué corregir y generará una propuesta revisada
Solo después de la aprobación se ejecuta la operación de escritura. Esto no es un diálogo de "confirmar/cancelar" — es un paso de revisión genuino donde puedes inspeccionar, editar e iterar.
Por qué esto importa para la calidad de traducción AI
La revisión de traducción automática es el cuello de botella en la mayoría de los flujos de trabajo de localización. Los equipos o se saltan la revisión (y publican errores) o revisan todo manualmente (y avanzan lento). Nuestro enfoque HITL encuentra el punto medio:
- La AI maneja el 80 % de las traducciones que son sencillas
- Los humanos enfocan su esfuerzo de revisión en el 20 % que requieren criterio
- Cada traducción tiene una procedencia clara: generada por AI, revisada por humanos o editada por humanos
- El audit trail registra quién aprobó qué, simplificando el cumplimiento
Renderizado progresivo: Tablas de traducción en streaming
Cuando el Agent genera traducciones para un lote de claves, los resultados no aparecen todos de golpe. La tabla de traducción hace streaming progresivo hacia la interfaz de chat — cada fila se renderiza cuando su traducción se completa.
Esta es una decisión de ingeniería impulsada por la experiencia de usuario. Cuando traduce 150 claves en 6 idiomas, eso son 900 traducciones individuales. Esperar a que las 900 se completen antes de mostrar algo significaría mirar un spinner de carga durante minutos. El renderizado progresivo te permite comenzar a revisar los primeros resultados de inmediato.
La implementación utiliza server-sent events para transmitir resultados de herramientas de vuelta a la interfaz de chat. El frontend mantiene un componente de tabla de traducción mutable que agrega filas a medida que llegan.
Gestión del contexto: Mantenerse fundamentado
Los grandes modelos de lenguaje tienden a perder contexto en conversaciones largas. Abordamos esto con tres mecanismos:
Caché de contexto de proyecto de 30 segundos
Cuando el Agent lee los datos de tu proyecto, los resultados se almacenan en caché durante 30 segundos. Si el Agent necesita referenciar el estado de tu proyecto múltiples veces dentro de una operación de varios pasos, accede al caché en lugar de hacer llamadas API redundantes. Esto reduce la latencia y evita que el Agent vea un estado inconsistente durante un flujo de trabajo complejo.
Reducción de contexto (slimToolResults)
Las respuestas de herramientas de la API de Better i18n pueden ser grandes — un proyecto con 2.000 claves y 12 idiomas genera payloads considerables. El sistema slimToolResults elimina automáticamente datos no esenciales de las respuestas de herramientas antes de que entren en el contexto de conversación.
Por ejemplo, cuando el Agent llama a getTranslations, la respuesta completa incluye metadatos como marcas de tiempo de creación, IDs de versión y atribuciones de usuario. El paso slimToolResults retiene solo los datos que el Agent necesita: nombres de claves, cadenas de origen y traducciones. Esto reduce significativamente el uso de tokens y previene el desbordamiento del context window.
Límite de 50 pasos de conversación
Cada conversación admite hasta 50 pasos de Agent (llamadas a herramientas). Esto es suficiente para flujos de trabajo complejos — traducir un namespace completo, revisar los resultados, hacer ediciones y publicar — al tiempo que previene bucles descontrolados. El contador de pasos es visible en la UI para que siempre sepas cuánta capacidad queda.
Historial de chat: Arquitectura de almacenamiento dual
Las conversaciones de Agent se almacenan en dos lugares simultáneamente:
- IndexedDB (local del navegador) — proporciona carga instantánea de conversaciones con cero latencia de red cuando regresas al dashboard
- Postgres (del lado del servidor) — mantiene un audit trail persistente y buscable de cada interacción con el Agent
El enfoque de almacenamiento dual resuelve dos requisitos que compiten. Los desarrolladores quieren acceso instantáneo a conversaciones recientes (IndexedDB ofrece lecturas en sub-milisegundos). Los equipos necesitan audit trails para cumplimiento y compartir conocimiento (Postgres proporciona almacenamiento duradero y consultable).
Cuando abres el chat AI, las conversaciones se cargan de IndexedDB inmediatamente. La copia de Postgres se sincroniza en segundo plano y sirve como fuente de verdad si se borra el almacenamiento local.
Flujo de trabajo real: Agregar coreano a una app de producción
Aquí hay un ejemplo concreto de cómo el Agent maneja una tarea real.
Paso 1: Tú preguntas — "Necesito agregar coreano al proyecto. Traduce todo en los namespaces common y settings."
Paso 2: El Agent lee — Llama a getLanguages (ve que el coreano no está configurado), getTranslations para el namespace common (encuentra 89 claves) y getTranslations para el namespace settings (encuentra 34 claves). Total: 123 claves a traducir.
Paso 3: El Agent propone agregar el idioma — Llama a proposeLanguages para agregar coreano (ko) al proyecto. Ves la propuesta y la apruebas.
Paso 4: El Agent traduce en lotes — Llama a translateBatch para el namespace common, luego el namespace settings. Las traducciones se transmiten progresivamente al chat. Ves las traducciones coreanas apareciendo junto a las cadenas de origen en inglés.
Paso 5: Tú revisas — Revisas las traducciones, marcas dos que usan un registro demasiado formal para la UI de una app casual e informas al Agent que las ajuste.
Paso 6: El Agent revisa — Llama a proposeTranslationEdits con tu feedback y genera traducciones revisadas para las dos cadenas marcadas. Las apruebas.
Paso 7: Tú publicas — Le dices al Agent que publique, llama a publishChanges y las traducciones coreanas están en vivo en el CDN.
Tiempo total: aproximadamente 10 minutos para 123 traducciones, revisadas y publicadas. Sin el Agent, este flujo de trabajo típicamente lleva horas de ciclos exportar-traducir-importar-revisar.
Lo que elegimos no construir
La transparencia sobre las limitaciones importa tanto como la documentación de características.
- Sin motor de traducción propietario — usamos Google Gemini como modelo subyacente. No reclamamos un "motor de traducción neuronal" personalizado ni AI propietaria.
- Sin pruebas A/B automatizadas de traducciones — tú eliges el modelo; no hay un framework que compare resultados de múltiples modelos.
- Sin Translation Memory — usamos consistencia de términos basada en glosario, no fuzzy matching de TM. Si necesitas TM, Better i18n no es la herramienta adecuada hoy.
- Sin métricas de precisión garantizadas — la calidad de traducción AI varía según el par de idiomas y el tipo de contenido. Recomendamos revisión humana para todo el contenido orientado al cliente, que es exactamente por qué HITL está integrado en cada operación de escritura.
Pruébalo
El AI Agent está disponible en todos los planes de Better i18n. Abre el dashboard, haz clic en el ícono de chat y comienza con algo simple: "Muéstrame el estado de traducción de este proyecto."
Desde allí, intenta una tarea real. Pídele que encuentre las traducciones faltantes, las genere y te guíe a través del proceso de aprobación. El Agent está diseñado para ser explorado conversacionalmente — no necesitas memorizar nombres de herramientas ni endpoints de API.
