Cómo funciona

Una ejecución es una canalización: leer el locale de origen, hacer diff de cada destino contra el archivo de bloqueo, enviar al proveedor solo lo que necesita trabajo, comprobar lo que vuelve, escribir y registrar el resultado. Esta página recorre esa canalización para que sepas exactamente qué pasa cuando ejecutas verbatra translate.

Una ejecución parte de tu configuración validada; consulta Archivo de configuración para saber dónde se encuentra y qué contiene. Todo lo de abajo es igual tanto si la ejecución vino de la CLI, del SDK o de watch.

Lee el locale de origen

El adaptador de formato lee el archivo del locale de origen y lo convierte en un conjunto neutral de entradas con clave, para que el resto de la canalización funcione igual con cualquier formato. Un archivo de origen ausente hace fallar la ejecución con SOURCE_UNREADABLE; un archivo que el adaptador no puede parsear falla con SOURCE_INVALID. Mientras lee, el adaptador también marca las claves de origen cuyos valores son inválidos para la sintaxis de mensajes del formato (ICU inválido): esas claves siguen el viaje pero se apartan en lugar de enviarse al proveedor en un estado roto.

Haz diff contra la línea base del bloqueo

Este diff existe para que una ejecución sea incremental: al proveedor solo se le llama por cadenas que de verdad necesitan trabajo. verbatra lee el archivo del locale de destino existente (un archivo ausente cuenta como vacío) y hace diff del origen contra él, usando el archivo de bloqueo como línea base de lo que se tradujo antes. Cada clave de origen cae en uno de cuatro grupos:

• faltante: el destino todavía no tiene la clave.
• modificada: el valor de origen ya no coincide con el hash registrado en el bloqueo.
• sin cambios: el valor de origen sigue coincidiendo con el hash registrado.
• huérfana: la clave está en el destino pero ya no en el origen.

Solo las claves faltantes y modificadas se convierten en candidatas a traducción. Las claves sin cambios se dejan en paz. Las claves huérfanas se informan y, por defecto, se dejan donde están; con --prune (o prune: true en la configuración) se eliminan exactamente esas claves del archivo de destino y del bloqueo, y nada más.

Envía lotes al proveedor

Las candidatas van a tu proveedor configurado en sublotes secuenciales de como mucho maxBatchSize (por defecto 50), así que una solicitud sobredimensionada no puede tumbar un locale entero. Cada sublote lleva las entradas más tus glossary y tone opcionales. Si la llamada de un sublote falla (un límite de tasa, un tiempo de espera agotado, una clave revocada), sus claves se retienen en esta ejecución y se recogen de nuevo en la siguiente mientras los demás sublotes siguen avanzando. Consulta Proveedores para ver cómo aplica cada proveedor estas entradas.

Valida la respuesta

La salida del proveedor nunca se trata como texto libre de confianza. Para los proveedores LLM (Anthropic, OpenAI, Gemini y openai-compatible), la respuesta son datos ligados a un esquema, validados antes de cualquier otra cosa: una respuesta malformada, o que contiene una clave que nunca se pidió, hace fallar el sublote, y una clave solicitada que vuelve ausente o duplicada se vuelve a pedir una vez; si tras eso sigue sin resolverse, la clave se trata como no traducida en esta ejecución y se reintenta en la siguiente. DeepL es una API de traducción automática sin esta capa de respuesta, pero sus resultados pasan por las mismas comprobaciones de integridad de abajo.

Comprueba la integridad de marcadores de posición e ICU

Una traducción que pasó la validación de esquema todavía puede estar rota, así que verbatra recalcula su propia decisión de aceptar o rechazar a partir del propio valor candidato: nunca se fía del informe del proveedor. Cada candidata aceptada debe llevar los mismos marcadores de posición que su origen, y para los formatos ICU debe seguir siendo un mensaje válido. Una candidata que falla cualquiera de las dos comprobaciones se retiene en lugar de escribirse, aparece en el resumen de la ejecución y se reintenta en la siguiente. Consulta Seguridad de la traducción para el modelo de seguridad completo.

Escribe a través del adaptador

Las traducciones aceptadas se fusionan en el destino y las escribe el adaptador de formato, de forma atómica y en el orden de claves del documento: una clave que ya está en el destino conserva su posición, y una clave nueva se añade donde la coloca el origen. Una escritura interrumpida nunca deja un archivo de locale a medias, y un formateador o un revisor de código ve diffs estables y mínimos.

Actualiza el bloqueo

Después de escribir un locale, sus entradas del bloqueo se refrescan con los hashes de origen actuales, con una excepción deliberada: una clave retenida en esta ejecución conserva su hash anterior, para que la siguiente ejecución siga viéndola como pendiente de trabajo. La escritura de cada locale ocurre bajo un bloqueo de escritura entre procesos, así que dos ejecuciones solapadas nunca hacen diff contra una línea base obsoleta ni pagan dos veces la misma llamada al proveedor. Los detalles están en El archivo de bloqueo.

Un locale cada vez, los fallos como datos

Cada locale de destino corre por su cuenta: que un locale falle no detiene a los demás. La ejecución devuelve un resumen por locale (traducidas, sin cambios, huérfanas, retenidas, marcadas para revisión, avisos), y una ejecución en seco (--dry-run) produce la misma forma de resumen después del paso de diff, sin construir un proveedor ni escribir nada.