verbatra translate

Ejecuta una pasada de traducción sobre cada locale de destino y termina. translate compara el origen con el archivo de bloqueo, envía al proveedor solo los strings nuevos o modificados, ejecuta las comprobaciones de integridad, escribe los archivos de locale y actualiza el bloqueo. Nunca envía dos veces un string sin cambios. Una ejecución real también añade las entradas que falten a un .gitignore existente, consulta Entradas de .gitignore.

SinopsisCopiar enlace a esta sección

verbatra translate [flags]

EjemplosCopiar enlace a esta sección

# traduce una vez con la configuración que encuentre
verbatra translate

# muestra las claves que se eliminarían, sin gastar nada
verbatra translate --prune --dry-run

# un locale cada vez, que es lo que necesita un plan gratuito con límite
verbatra translate --locales de

# dimensiona y pon precio a la ejecución sin gastar nada
verbatra translate --estimate

# para antes de que la ejecución supere 50000 tokens
verbatra translate --max-tokens 50000

# retraduce también las claves obsoletas que escribió una persona
verbatra translate --include-human

FlagsCopiar enlace a esta sección

También acepta los flags globales --cwd, --config y --json. Antes de ejecutarse, translate carga los archivos de entorno.

ComportamientoCopiar enlace a esta sección

Ejecución de pruebaCopiar enlace a esta sección

--dry-run no construye ningún proveedor, así que no necesita clave de API y no puede gastar nada. Lee los archivos de origen y de destino, los compara con el archivo de bloqueo e informa exactamente de lo que cambiaría una ejecución real. No escribe nada (ni archivo de locale, ni actualización del bloqueo, ni instantánea del estado de ejecución), con un proveedor automático no lee ni escribe la caché (con el proveedor none lee la memoria de traducción, ver abajo) y no toma ningún bloqueo de escritura, así que nunca espera a una ejecución en curso.

Estimación de costeCopiar enlace a esta sección

--estimate añade a la ejecución de prueba una estimación previa: cuántas claves se enviarían, cuántas peticiones al proveedor serían y la cantidad que factura el proveedor (tokens en un LLM o en un endpoint openai-compatible, caracteres de origen en DeepL, Google Cloud Translation o LibreTranslate; un endpoint o servidor autoalojado no se factura, así que la estimación no indica coste de API). Una cifra en moneda solo aparece cuando la configuración tiene un bloque rates que cubre el proveedor y el modelo; si no, se nombra la clave de tarifa que falta en lugar de inventar 0.00. Consulta Estimar el coste.

Un subconjunto de localesCopiar enlace a esta sección

--locales de,fr limita la ejecución a una parte de los destinos configurados. Los demás locales conservan sus archivos, sus entradas de bloqueo y sus entradas de caché. Úsalo en un plan gratuito con límite de peticiones para traducir un locale cada vez, o para repetir un único locale que salió parcial. La instantánea del estado de ejecución describe entonces solo ese subconjunto.

Bloqueos de escritura e interrupcionesCopiar enlace a esta sección

Un locale espera hasta --lock-timeout por un bloqueo de escritura ocupado y luego falla con LOCK_CONTENDED, mientras los demás locales siguen. Un bloqueo que dejó un proceso de verbatra que ya no corre en esta máquina se recupera al momento. El timeout solo limita esa espera, anterior a cualquier llamada al proveedor: registrar un archivo escrito en el archivo de bloqueo espera siempre hasta el valor por defecto de diez minutos, para que ningún archivo escrito quede sin registrar. Una espera de más de un segundo imprime en stderr una línea que nombra el bloqueo y a quien lo tiene (con --json, un registro lock-wait), y --quiet no la omite. Ctrl-C o SIGTERM liberan los bloqueos de la ejecución antes de que el comando termine.

Tope de tokensCopiar enlace a esta sección

--max-tokens siempre es una parada dura: una petición al proveedor que superaría el tope se retiene, diga lo que diga budgetBehavior, y sus claves aparecen como budgetWithheld. Se cuenta igual que un presupuesto maxTokens configurado y puede endurecer ese presupuesto, nunca relajarlo. Una ejecución que el tope dejó a medias sale con 1. Ejecuta antes --estimate para elegir una cifra.

Locales en paraleloCopiar enlace a esta sección

--concurrency se rechaza con salida 2 cuando hay un presupuesto de tokens (de maxTokens o de --max-tokens), porque el orden en que se intercalan los locales decidiría cuál pierde el trabajo restante; una ejecución de prueba queda exenta. Si aparece un error de toda la ejecución, como un archivo de bloqueo dañado, mientras hay locales en marcha, no empieza ninguno más, y los que están en curso terminan y liberan sus bloqueos antes de que el comando salga con 2.

Claves que escribió una personaCopiar enlace a esta sección

Una clave obsoleta cuyo valor escribió, importó o cambió una persona fuera de verbatra se conserva por defecto: aparece como protected, no se envía al proveedor y sigue obsoleta para verbatra check. Un aviso en stderr dice cuántas se conservaron (las claves fijadas no cuentan) y remite a --include-human, que las retraduce durante una ejecución (humanEdits: "overwrite") y por eso no imprime el aviso. Las claves protegidas no cambian el código de salida, salvo en un proyecto solo humano. Consulta Proteger las traducciones humanas.

Proyectos solo humanosCopiar enlace a esta sección

En un proyecto solo humano (provider: { id: "none" }) no se llama a ningún proveedor. Las claves que cubre la memoria de traducción se escriben, y cualquier otra clave ausente o modificada aparece como unfilled y da salida 3; un locale fallido o parcial sigue ganando con 1. Aquí una ejecución de prueba sí lee la memoria, así que su plan muestra las mismas claves cacheHits y unfilled, y --estimate no informa de nada facturado; ambos salen con 3 igual. Sin --json, un aviso en stderr dice cuántas claves necesitan a una persona, y una pista next: remite a verbatra export, con el que pasas las claves unfilled a una persona.

Locales fallidos y parcialesCopiar enlace a esta sección

Que falle un locale no es fatal: la ejecución termina y sale con 1. Un locale parcial también sale con 1: su archivo se escribió pero aún faltan claves, normalmente porque falló un sublote del proveedor o la puerta de integridad rechazó una traducción. La salida legible lista cada clave rechazada bajo integrity-withheld con su motivo (placeholder, markup, icu, degenerate o empty); con --json, cada locale los lleva en integrityRefusals. Las claves que la ejecución marcó para revisión siguen al recuento N needs-review del locale bajo una línea needs-review:, cada una con sus motivos de revisión; con --json están en needsReview.

Locales no admitidosCopiar enlace a esta sección

Un locale que el proveedor DeepL o Google Cloud Translation configurado no admite rechaza toda la ejecución con LOCALE_UNSUPPORTED_BY_PROVIDER y salida 2, también en una ejecución de prueba y con --estimate, antes de gastar nada. Déjalo fuera con --locales o consulta Soporte de idiomas. Un glosario o un tono que el proveedor no puede aplicar solo añade un aviso (GLOSSARY_UNSUPPORTED_BY_PROVIDER, FORMALITY_UNSUPPORTED_BY_PROVIDER), igual que LOCALE_UNVERIFIED_BY_PROVIDER y, en un LLM, LOCALE_NOT_WELL_TESTED.

Salida JSONCopiar enlace a esta sección

Esquema: translate-envelope.json valida el envoltorio completo; Esquemas enumera los demás.

Con --json, stdout lleva un envoltorio cuyo result es un RunSummary; RunSummary enumera cada campo, de la ejecución y de cada locale.

Información en el terminalCopiar enlace a esta sección

translate nombra los locales y el proveedor antes de la ejecución, y después imprime el tiempo transcurrido, los tokens usados y el siguiente comando. En un terminal interactivo el progreso es una línea con spinner; cuando stderr está redirigido, cada paso es una línea propia:

verbatra: translating 2 locales with gemini/gemini-2.5-flash
verbatra: translating de
verbatra: de batch 1/1
verbatra: de: writing
verbatra: de done, 12 translated
verbatra: translating fr
verbatra: fr batch 1/1
verbatra: fr: writing
verbatra: fr done, 12 translated
verbatra: run finished, 2 locales processed
[ok] done in 4.2s, 1830 tokens
next: verbatra check (confirm every locale is in sync)

Una ejecución de prueba empieza con dry run over 2 locales, no provider call, una estimación con estimating 2 locales, no provider call y un proyecto solo humano con filling 2 locales from the translation memory (provider none). Una ejecución de prueba o una estimación termina cada locale con would translate. Un locale que solo conservó parte de las claves termina con partly done, uno que falla con failed, y la línea final indica cuántos fallaron. Una ejecución de prueba cierra con dry run done in 4.2s, nothing written. Una estimación cierra con estimate done in 4.2s, nothing written nuevo. Estas líneas van a stderr, y --quiet las omite. Consulta Salida en el terminal.

Códigos de salidaCopiar enlace a esta sección

Tras una interrupción, stderr termina con verbatra: interrupted (SIGINT), released locks, o con --json con el registro {"type":"interrupted","signal":"SIGINT","locksReleased":true}. Si liberar los bloqueos falla o no termina en 5 segundos, la línea lo dice en su lugar (could not release locks: <reason> o lock release did not finish within 5s), y el registro JSON lleva "locksReleased":false con "reason":"failed" (más message) o "reason":"timed-out" (más deadlineMs). Consulta el contrato de códigos de salida.

RelacionadoCopiar enlace a esta sección

• Cómo funciona explica el proceso de leer, comparar, traducir y escribir.
• La caché explica qué omite --no-cache.
• Seguridad de las traducciones cubre las comprobaciones de integridad y la cola de revisión.
• verbatra diff muestra las mismas claves pendientes en modo solo lectura.
• CI y códigos de salida muestra cómo reaccionar a estos códigos en un pipeline.