--- title: "verbatra translate" description: "Traduce cada locale de destino una vez: solo las claves nuevas y cambiadas van a tu proveedor; después escribe los resultados y termina." type: "reference" --- # verbatra translate Traduce cada locale de destino una vez: solo las claves nuevas y cambiadas van a tu proveedor; después escribe los resultados y termina. Ejecuta una pasada de traducción sobre cada locale de destino y termina. `translate` compara el origen con [el archivo de bloqueo](https://verbatra.kreitz-webdev.de/es/docs/the-lock-file.md), envía al proveedor solo los strings nuevos o modificados, ejecuta las [comprobaciones de integridad](https://verbatra.kreitz-webdev.de/es/docs/translation-safety.md), 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](https://verbatra.kreitz-webdev.de/es/docs/cli.md#entradas-de-gitignore). ## Sinopsis [#sinopsis] ```bash verbatra translate [flags] ``` ## Ejemplos [#ejemplos] ```bash # 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 ``` ## Flags [#flags] | Flag | Argumento | Por defecto | Efecto | | --- | --- | --- | --- | | `--locales` | `` | cada locale de destino configurado | traduce solo este subconjunto separado por comas; un locale no configurado falla con `UNKNOWN_LOCALE` y una lista vacía con `INVALID_LOCALES`, ambos con salida `2` | | `--dry-run` | ninguno | desactivado | informa de lo que cambiaría una ejecución sin llamar a un proveedor ni escribir archivos; no necesita clave de API | | `--prune` | ninguno | la opción `prune` de la configuración, si no, desactivado | elimina las claves huérfanas (en un archivo de destino, ausentes del origen) del archivo escrito y del bloqueo | | `--lock-timeout` | `` | `600` | espera este tiempo por un bloqueo de escritura ocupado de un locale; un entero de `1` a `3600` | | `--concurrency` | `` | `1` | traduce hasta `n` locales de destino a la vez; un entero de `1` a `100`, rechazado con un presupuesto de tokens | | `--max-tokens` | `` | el `maxTokens` de la configuración | tope duro de tokens para esta ejecución, un número entero positivo (si no, `INVALID_MAX_TOKENS`); se aplica el menor entre este y el `maxTokens` de la configuración | | `--no-cache` | ninguno | desactivado (caché activa) | omite la [caché de memoria de traducción](https://verbatra.kreitz-webdev.de/es/docs/the-cache.md) (`verbatra.cache.json`) en esta ejecución | | `--include-human` | ninguno | desactivado | retraduce también, solo en esta ejecución, las claves obsoletas que escribió o importó una persona; las [claves fijadas](https://verbatra.kreitz-webdev.de/es/docs/protecting-human-translations.md#fijar-claves) no se tocan | | `--estimate` | ninguno | desactivado | estima lo que la ejecución enviaría y costaría, y termina; implica `--dry-run` | También acepta los [flags globales](https://verbatra.kreitz-webdev.de/es/docs/cli.md#flags-globales) `--cwd`, `--config` y `--json`. Antes de ejecutarse, `translate` carga los [archivos de entorno](https://verbatra.kreitz-webdev.de/es/docs/cli.md#archivos-de-entorno). ## Comportamiento [#comportamiento] Una ejecución sin `--dry-run` ni `--estimate` envía cada string nuevo o modificado al proveedor, y un proveedor alojado lo factura: mide la ejecución con `--estimate` y limítala con `--max-tokens`. Una clave de API enviada a un servidor autoalojado por `http://` simple (no loopback) cruza la red sin cifrar, consulta [Las claves son opcionales](https://verbatra.kreitz-webdev.de/es/docs/providers.md#las-claves-son-opcionales). ### Ejecución de prueba [#ejecución-de-prueba] `--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. Por defecto una ejecución no borra nada: las claves huérfanas se informan y se quedan donde están. `--prune`, o `prune: true` en la configuración, borra exactamente esas claves de los archivos de destino y del bloqueo; `--prune --dry-run` te las muestra antes. ### Estimación de coste [#estimación-de-coste] `--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](https://verbatra.kreitz-webdev.de/es/docs/estimating-cost.md). ### Un subconjunto de locales [#un-subconjunto-de-locales] `--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 interrupciones [#bloqueos-de-escritura-e-interrupciones] Un locale espera hasta `--lock-timeout` por un [bloqueo de escritura](https://verbatra.kreitz-webdev.de/es/docs/the-lock-file.md#el-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 tokens [#tope-de-tokens] `--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`](https://verbatra.kreitz-webdev.de/es/docs/config-file.md#maxtokens-y-budgetbehavior) 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 paralelo [#locales-en-paralelo] `--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 persona [#claves-que-escribió-una-persona] 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](https://verbatra.kreitz-webdev.de/es/docs/protecting-human-translations.md). ### Proyectos solo humanos [#proyectos-solo-humanos] En un proyecto [solo humano](https://verbatra.kreitz-webdev.de/es/docs/human-only-workflow.md) (`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`](https://verbatra.kreitz-webdev.de/es/docs/cli/export.md), con el que pasas las claves `unfilled` a una persona. ### Locales fallidos y parciales [#locales-fallidos-y-parciales] 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](https://verbatra.kreitz-webdev.de/es/docs/translation-safety.md#señales-de-revisión); con `--json` están en `needsReview`. ### Locales no admitidos [#locales-no-admitidos] 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](https://verbatra.kreitz-webdev.de/es/docs/language-support.md#comprobar-el-soporte-antes-de-una-ejecución). 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 JSON [#salida-json] Esquema: [`translate-envelope.json`](https://verbatra.kreitz-webdev.de/schema/v1/translate-envelope.json) valida el envoltorio completo; [Esquemas](https://verbatra.kreitz-webdev.de/es/docs/cli/output.md#esquemas) enumera los demás. Con `--json`, stdout lleva un [envoltorio](https://verbatra.kreitz-webdev.de/es/docs/cli/output.md#salida-json) cuyo `result` es un `RunSummary`; [RunSummary](https://verbatra.kreitz-webdev.de/es/docs/sdk/run-summary.md) enumera cada campo, de la ejecución y de cada locale. ### Información en el terminal [#información-en-el-terminal] `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: ```text output 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` . Estas líneas van a stderr, y `--quiet` las omite. Consulta [Salida en el terminal](https://verbatra.kreitz-webdev.de/es/docs/cli/output.md#salida-en-el-terminal). ## Códigos de salida [#códigos-de-salida] | Código | Significado | | --- | --- | | `0` | todos los locales de destino quedaron completos | | `1` | la ejecución terminó, pero un locale falló o quedó parcial | | `2` | no pudo ejecutarse: un error de configuración, origen, formato, proveedor, locale no admitido o archivo de bloqueo, o un error de uso | | `3` | proyecto solo humano: la ejecución (también de prueba o con `--estimate`) terminó limpia, pero quedan claves para una traducción humana | | `130` | interrumpido con Ctrl-C (SIGINT) tras liberar los bloqueos de escritura | | `143` | detenido con SIGTERM tras liberar los bloqueos de escritura | 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: ` 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](https://verbatra.kreitz-webdev.de/es/docs/cli/output.md#códigos-de-salida). ## Relacionado [#relacionado] - [Cómo funciona](https://verbatra.kreitz-webdev.de/es/docs/how-it-works.md) explica el proceso de leer, comparar, traducir y escribir. - [La caché](https://verbatra.kreitz-webdev.de/es/docs/the-cache.md) explica qué omite `--no-cache`. - [Seguridad de las traducciones](https://verbatra.kreitz-webdev.de/es/docs/translation-safety.md) cubre las comprobaciones de integridad y la cola de revisión. - [`verbatra diff`](https://verbatra.kreitz-webdev.de/es/docs/cli/diff.md) muestra las mismas claves pendientes en modo solo lectura. - [CI y códigos de salida](https://verbatra.kreitz-webdev.de/es/docs/ci-and-exit-codes.md) muestra cómo reaccionar a estos códigos en un pipeline.