Docs / Conceptos
Página traducida automáticamente
Cómo funciona una ejecución
La canalización de traducción de principio a fin, desde leer el locale de origen y encontrar las claves cambiadas hasta escribir las traducciones y el lock.
Una ejecución es una canalización: leer el locale de origen, comparar cada destino con el archivo de
bloqueo, enviar al proveedor solo lo que necesita trabajo, comprobar lo que vuelve, escribir y
registrar el resultado. La canalización es la misma tanto si la ejecución viene de la CLI, del SDK
o de watch.
Leer el locale de origen
El adaptador de formato lee el archivo de origen como un conjunto neutro de entradas con clave, de
modo que cada paso posterior funciona igual para todos los formatos. Una clave de origen cuyo valor
no es válido para la sintaxis de mensajes del formato (ICU no válido) se aparta y se informa, en
lugar de enviarse rota al proveedor. Un archivo de origen que falta o no se puede analizar hace
fallar la ejecución; consulta
SOURCE_ y
SOURCE_.
Comparar con la línea base del bloqueo
La comparación es lo que hace incremental una ejecución. verbatra lee el archivo de destino
existente (un archivo ausente cuenta como vacío, aunque los escritores de xliff y apple-xcstrings rechazan un destino ausente) y compara cada clave de origen con
el archivo de bloqueo, el registro de lo que ya se tradujo:
| Grupo | Significado | Qué hace la ejecución |
|---|---|---|
| missing | el destino aún no tiene la clave | la traduce |
| changed | el origen ya no coincide con el hash registrado | la traduce |
| unchanged | el origen sigue coincidiendo con el hash registrado | la deja como está |
| orphaned | la clave está en el destino pero no en el origen | la informa; la elimina solo con --prune o prune: true |
Claves retenidas
Dos tipos de candidatos se retienen. Una clave cambiada cuyo valor actual escribió o importó una
persona está protegida por defecto (humanEdits), y una clave que coincide con pinnedKeys nunca
se traduce automáticamente. Ambas siguen desactualizadas hasta que una persona las resuelve;
consulta Conserva las traducciones humanas.
Enviar lotes al proveedor
Cada candidato se busca primero en la caché de traducciones. Un acierto se reutiliza y nunca llega al proveedor. De los fallos, las claves con el mismo contenido de origen se agrupan, para que ese texto cueste una petición por locale en lugar de una por clave.
Los grupos van a tu proveedor en sublotes secuenciales de como mucho maxBatchSize (50 por
defecto), cada uno con las entradas, los términos del glosario de ese locale y tu tone. Si un
sublote falla (un límite de peticiones, un tiempo de espera agotado, una clave revocada), sus claves
se retienen en esta ejecución mientras los demás sublotes siguen adelante.
Proveedores describe cómo aplica cada proveedor estas entradas.
Validar la respuesta
La salida del proveedor son datos, nunca texto libre. Para los proveedores LLM, la respuesta debe ajustarse a un esquema fijo:
- Una respuesta mal formada, o una que contiene una clave que nunca se pidió, hace fallar el sublote entero.
- Una clave pedida que vuelve ausente o duplicada se pide una vez más.
- Una clave que sigue sin resolverse después no se traduce en esta ejecución.
Los proveedores de traducción automática no tienen esquema de respuesta, pero sus resultados pasan por la misma puerta de integridad.
Ejecutar la puerta de integridad
Una traducción que cumple el esquema aún puede estar rota, así que verbatra decide a partir del propio valor candidato si lo acepta y nunca se fía del informe del proveedor. Un candidato que pierde un placeholder, rompe un mensaje ICU o su marcado, vuelve vacío o degenera se retiene en lugar de escribirse. Las comprobaciones están en Seguridad de la traducción.
Escribir 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 un orden de claves estable: una clave que ya está en el destino conserva su posición, y las claves nuevas se añaden detrás de las existentes, en el orden del origen. Una escritura interrumpida nunca deja un archivo a medio escribir, y quien revisa ve diffs pequeños y estables.
Actualizar el bloqueo
Tras escribir un locale, sus entradas del bloqueo se refrescan con los hashes de origen actuales. Una clave retenida en esta ejecución conserva su hash anterior, así que la siguiente ejecución la sigue viendo pendiente. Cada locale se escribe bajo un bloqueo de escritura entre procesos, de modo que dos ejecuciones solapadas nunca comparan con una línea base desfasada ni pagan dos veces la misma llamada.
Un locale cada vez, los fallos como datos
Cada locale de destino se ejecuta por su cuenta, y que uno 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 y avisos. Qué contiene cada campo está en RunSummary.
Lo que garantiza este diseño:
- Una segunda ejecución sin cambios en el origen no llama al proveedor para nada.
- Nada que una comprobación rechazó se escribe nunca, y nada retenido se registra como hecho.
- Una ejecución de prueba (
--dry-run) se detiene tras la comparación y devuelve un resumen con la misma forma, sin construir un proveedor ni escribir un archivo.
Lo que no hace: nunca juzga si una traducción es buena. Para eso están las señales de revisión y una persona.
Relacionado
verbatra translate: flags, salida y códigos de salida de una ejecución.- El archivo de bloqueo y la procedencia: qué registra la línea base.
- La caché de traducciones: cómo se indexa la reutilización.
- Seguridad de la traducción: la puerta de integridad y las señales de revisión.
- Códigos de error: cada código que puede informar una ejecución.