lingo push

Envía archivos fuente al motor, espera a que termine la ejecución y escribe las salidas en disco.

lingo push [patterns...] [--key <pattern>] [--force] [--backfill-missing] [--yes] [--wait] [--estimate]

Comportamiento predeterminado — push delta#

Sin argumentos, lingo push ejecuta el modo solo delta:

1. Calcula el hash de cada archivo fuente que coincida con los patrones files de la configuración
2. Compara cada hash con el lockfile para detectar qué fuentes cambiaron
3. Sube las fuentes modificadas como una ejecución al motor
4. Espera a que termine la ejecución
5. Escribe las salidas en disco
6. Guarda los nuevos hashes de origen en el lockfile

Si ninguna fuente cambió desde el último push exitoso, el comando termina de inmediato con ✓ Nothing to push. — sin ida y vuelta al servidor, sin consumo de tokens.

Argumentos y flags#

Posicional: patterns... — push con alcance#

lingo push docs/en/about.md
lingo push 'docs/en/**/*.md' 'locales/en.json'

Restringe el push a archivos específicos (deben coincidir con patrones ya definidos en .lingo/config.json). Cambia el comando al modo con alcance:

• No compara con la fuente anterior: toda fuente coincidente se considera dentro del alcance, incluso si no cambió.
• Noop del lado del servidor para los targets que ya existen con hashes de origen coincidentes: el motor los omite y la CLI los reporta como en caché.

Úsalo cuando quieras traducir exactamente un archivo actualizado sin volver a calcular el hash de todo el proyecto, o cuando quieras retraducir una sola página con --force.

--key <pattern>#

lingo push --key auth.login
lingo push --key auth.login --key billing.plan
lingo push --key "auth.*"

Vuelve a traducir solo las claves que cubre un patrón, combínalas con la traducción existente y deja todas las demás claves idénticas byte por byte. Se puede repetir: un --key por patrón.

Un alcance por clave ignora el diff del origen, así que una clave cuyo texto fuente nunca cambió igual se vuelve a traducir. Justamente para eso sirve la bandera: es la forma compatible de rehacer unas cuantas cadenas después de un cambio de redacción, un cambio de modelo o una actualización del glosario, sin pagar por el resto del archivo.

--force no agrega nada más y además omite la confirmación para el archivo completo.

Qué pasa con cada clave#

La última fila es lo que distingue un alcance por clave de un push normal. Una clave agregada al origen desde tu último push completo no se incorpora a la traducción como texto fuente: se queda fuera, y el siguiente lingo push simple la traduce.

Cómo coincide un patrón#

Un patrón coincide con una clave exacta, como prefijo que termina en un límite ., /, - o [, o como glob. Se puede llegar a los miembros de arreglos por el límite de corchetes, así que nav.items cubre nav.items[0].title.

Pon los globs entre comillas. Tu shell los expande primero: en zsh, un --key auth.* sin comillas o bien aborta con no matches found, o bien —si un archivo como auth.json está en el directorio— se convierte silenciosamente en ese nombre de archivo. Un valor separado por comas no es una lista: --key "a,b" es un único patrón literal que no coincide con nada. Repite la bandera en su lugar.

Lo que rechaza#

Un alcance por clave informa y omite, en lugar de hacer discretamente más de lo que pediste:

• Un idioma que todavía no tiene traducción. No hay nada con qué combinar, así que se indica el idioma y se omite; tradúcelo una vez con --backfill-missing y luego usa --key.
• Formatos en los que no se puede omitir ninguna clave: los formatos de documento, cuyas claves cambian en cuanto se edita el documento, y xcode-stringsdict, cuyas categorías de plural el archivo necesita para seguir siendo válido. En Formatos encontrarás la lista completa. Estos archivos se omiten con una advertencia, así que un push aún puede mezclarlos con archivos de clave-valor. Envíalos sin --key.
• Un alcance que no coincidió con nada lo informa, en vez de reportar la ejecución como si ya estuviera actualizada.

Los miembros posicionales conservan su texto fuente incluso dentro de un alcance —elementos de arreglos, elementos <string-array> de Android, cantidades <plurals>— porque quitar uno renumeraría el resto.

No actualiza el lockfile#

Una ejecución con alcance por clave traduce solo parte de un archivo, así que deliberadamente deja intacto el hash de origen en el lockfile. Cualquier otro cambio en ese archivo sigue pendiente, y el siguiente lingo push simple lo recogerá.

--force / -f#

lingo push docs/en/about.md --force

Vuelve a traducir cada destino que coincida, ignorando cualquier traducción existente y saltándose el caché del lado del servidor. Dale alcance —con patrones posicionales o --backfill-missing— a menos que de verdad quieras incluir todo el proyecto: lingo push --force sin nada vuelve a traducir todos los patrones configurados, y la confirmación de abajo es lo único que se interpone.

En un proyecto que nunca se ha traducido, no hay nada que sobrescribir, así que --force no sirve de nada ahí; mejor usa --backfill-missing. En general, es la opción más segura: solo rellena los huecos que faltan y nunca pide confirmación.

De forma predeterminada, --force pide confirmación antes de ejecutarse:

! --force will retranslate every target for pattern(s): docs/en/about.md and
  overwrite existing translations. Continue? (Yes, retranslate / Cancel)

Pasa --yes / -y para omitir la confirmación (ideal para CI).

Si quieres rehacer solo unas cuantas cadenas en lugar de archivos completos, usa --key: solo pagas por las claves que indiques.

--backfill-missing#

lingo push --backfill-missing

Traduce cada target que todavía no existe en todos los patrones configurados. Equivale a un push con alcance sobre todos los patrones de la configuración, pero solo genera archivos donde faltan. Úsalo después de agregar un nuevo idioma a targetLocales, o en el primer push de un proyecto nuevo.

Combínalo con --force para retraducir todo desde cero:

lingo push --backfill-missing --force --yes

--yes / -y#

Omite la confirmación de --force. No tiene efecto sin --force, ni tampoco junto con --key: un alcance por clave nunca pide confirmación, porque solo toca las claves que indicaste.

--estimate#

lingo push --estimate
lingo push 'docs/en/**/*.md' --estimate

Muestra el costo aproximado de este push y sale sin traducir. El CLI ejecuta todo el flujo de push —hashing, delta y carga de los bytes de origen— para que el servidor pueda planificar el delta exacto, y luego le pide al motor que calcule el precio de la ejecución en vez de iniciarla. No se traduce, escribe ni factura nada; el lockfile y tus archivos de destino quedan intactos.

Los valores son estimaciones, no cotizaciones. --estimate se combina con el alcance y con --key / --force / --backfill-missing, así que puedes calcular el precio exacto del push que estás por ejecutar.

Si ninguna fuente cambió, --estimate se interrumpe antes con ✓ Nothing to push., igual que un push normal.

Si ya hay una ejecución en curso para las mismas fuentes, --estimate falla en lugar de calcular el precio de una ejecución iniciada a medias:

Error: Cannot estimate: existing group run_a8c... is already in 'running' state. Change a source file or wait for the run to finish.

Salida#

Si todo sale bien:

Pushing source files to localization engine…
✓ Run run_a8c...: localized 12 target file(s), 4 already up-to-date, uploaded 1 new artifact(s).

El resumen se desglosa así:

• N archivo(s) target localizados — el motor generó traducciones nuevas y la CLI las escribió.
• N ya actualizados — aciertos de caché del lado del servidor (la fuente coincidió y se reutilizó el target).
• Se subieron N artifact(s) nuevos — fuentes que el motor no había visto antes (contenido binario o de gran tamaño que se almacena una vez y luego se referencia).
• N target(s) omitidos (ediciones locales) — los hashes de target locales difieren del lockfile. Vuelve a ejecutar con --force para sobrescribirlos.

Si falla algún target, la CLI imprime el error de cada uno y termina con un código distinto de cero — útil para CI:

✓ Run run_a8c...: localized 10 target file(s).
  2 target(s) failed:
    locales/de.json: rate limit on engine; retry later
    locales/fr.json: timeout

Con --estimate:

Estimating push cost…
› Estimated cost: ~$1.87 (12 target(s), ~48,000 output tokens — estimate, not a quote)
  de: ~$0.9350 (6 target(s), ~24,000 tokens)
  fr: ~$0.9350 (6 target(s), ~24,000 tokens)
  4 target(s) already up-to-date — no cost.
✓ Estimate complete — nothing was translated. Run `lingo push` to start the translation.

Semántica de reintento#

El lockfile se actualiza solo después de una ejecución completamente exitosa. Un fallo parcial (por ejemplo, si un idioma supera el tiempo de espera) deja los hashes de origen sin cambios en el lockfile, así que el siguiente lingo push reintenta el mismo diff — sin necesidad de restablecer nada manualmente.

Si el motor falla antes de que ocurra cualquier traducción (auth, validación), no se escribe nada y el lockfile no cambia.

Patrones comunes#

CI: traducir al hacer merge#

- run: lingo push --backfill-missing --yes
- run: git add . && git commit -m "chore: refresh translations" && git push

--backfill-missing es la opción segura por defecto: no sobrescribe nada, solo completa lo que falta.

Rehacer unas cuantas cadenas#

lingo push --key auth.login --key billing.plan --wait

Vuelve a traducir exactamente esas claves después de un cambio de redacción, dejando intactas todas las demás claves del archivo.

Iteración en un solo archivo#

lingo push docs/en/onboarding.md -f -y

Retraduce solo una fuente después de un cambio importante en el copy. Omite la confirmación para iterar más rápido.

Agregar un nuevo idioma#

Después de actualizar targetLocales en .lingo/config.json:

lingo push --backfill-missing

Traduce todo el corpus al nuevo idioma sin retraducir los que ya existen.