lingo push

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

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

Comportamiento por defecto — envío delta#

Sin argumentos, lingo push se ejecuta en 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 han cambiado
3. Sube las fuentes modificadas como una ejecución en el motor
4. Espera a que termine la ejecución
5. Escribe los archivos de salida en disco
6. Registra los nuevos hashes de las fuentes en el lockfile

Si no ha cambiado ninguna fuente desde el último envío correcto, el comando termina de inmediato con ✓ Nothing to push. — sin ida y vuelta al servidor y sin consumir tokens.

Argumentos y opciones#

Posicional: patterns... — envío acotado#

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

Restringe el envío a archivos concretos (deben coincidir con patrones ya definidos en .lingo/config.json). Cambia el comando al modo acotado:

• Sin diff respecto a fuentes anteriores: toda fuente coincidente se considera dentro del alcance, aunque no haya cambiado.
• No-op en el servidor para los destinos que ya existen con hashes de fuente coincidentes: el motor los omite y la CLI los muestra como almacenados 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 abarque un patrón, intégralas en la traducción existente y deja todas las demás claves idénticas byte a byte. Se puede repetir: un --key por patrón.

Un alcance de claves ignora el diff del archivo fuente, así que una clave cuyo texto original no haya cambiado se vuelve a traducir igualmente. Ese es precisamente el objetivo de la marca: es la forma admitida de rehacer unas cuantas cadenas tras un cambio de redacción, un cambio de modelo o una actualización del glosario, sin pagar por el resto del archivo.

--force no añade nada más y omite la solicitud de confirmación para el archivo completo.

Qué ocurre con cada clave#

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

Cómo coincide un patrón#

Un patrón coincide con una clave de forma exacta, como prefijo que termina en un límite ., /, - o [, o como glob. Se puede acceder a los miembros de un array mediante el límite de corchetes, así que nav.items abarca 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 marca en su lugar.

Qué rechaza#

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

• Un idioma sin traducción todavía. No hay nada en lo que integrarlo, 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 son necesarias para que el archivo siga siendo válido. Formatos incluye la lista completa. Estos archivos se descartan con una advertencia, así que un push aún puede mezclarlos con archivos de clave-valor; súbelos sin --key.
• Un alcance que no coincidió con nada lo indica, en lugar de informar de que la ejecución ya estaba al día.

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

No actualiza el lockfile#

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

--force / -f#

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

Vuelve a traducir cada destino que coincida, ignorando las traducciones existentes y saltándose la caché del lado del servidor. Delimítalo —con patrones posicionales o --backfill-missing— salvo que de verdad quieras abarcar todo el proyecto: lingo push --force sin más vuelve a traducir todos los patrones configurados, y la confirmación de abajo es lo único que lo impide.

En un proyecto que nunca se ha traducido, no hay nada que sobrescribir, así que --force no sirve de nada en ese caso; usa --backfill-missing en su lugar. En general, es la opción más segura: solo rellena los huecos y nunca muestra avisos.

Por defecto, --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 unas pocas cadenas en lugar de archivos completos, usa --key: solo pagas por las claves que indiques.

--backfill-missing#

lingo push --backfill-missing

Traduce todos los destinos que todavía no existen en todos los patrones configurados. Equivale a un envío acotado sobre todos los patrones de la configuración, pero solo genera archivos donde faltan. Úsalo después de añadir un nuevo idioma a targetLocales o en el primer envío de un proyecto nuevo.

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

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

--yes / -y#

Omite la solicitud de confirmación de --force. No tiene efecto sin --force, ni tampoco junto a --key: un alcance de claves nunca pide confirmación, porque solo toca las claves que has indicado.

--estimate#

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

Muestra el coste aproximado de este push y termina sin traducir. La CLI ejecuta todo el flujo de push —hashing, delta y subida de los bytes de origen para que el servidor pueda planificar el delta exacto— y después le pide al motor que calcule el precio de la ejecución en lugar de iniciarla. No se traduce, escribe ni factura nada; el lockfile y tus archivos de destino no se tocan.

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

Si no ha cambiado ningún archivo fuente, --estimate se interrumpe con ✓ Nothing to push., igual que en un push normal.

Si ya hay una ejecución en marcha 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 va 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) de destino localizados — el motor generó nuevas traducciones y la CLI las escribió.
• N ya actualizados — aciertos de caché en el servidor (la fuente coincidía y se reutilizó el destino).
• N artefacto(s) nuevos subidos — fuentes que el motor no había visto antes (contenido binario o de gran tamaño que se almacena una vez y después se referencia).
• N destino(s) omitidos (ediciones locales) — los hashes locales de los destinos difieren del lockfile. Vuelve a ejecutar con --force para sobrescribirlos.

Si falla un destino concreto, la CLI muestra el error de cada destino fallido y sale 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 los reintentos#

El lockfile se actualiza solo después de una ejecución completamente correcta. Un fallo parcial (por ejemplo, si un idioma agota el tiempo de espera) deja sin cambios los hashes de las fuentes en el lockfile, así que el siguiente lingo push reintenta el mismo diff — sin necesidad de reinicio manual.

Si el motor devuelve un error antes de que se produzca ninguna traducción (autenticación, validación), no se escribe nada y el lockfile no cambia.

Patrones habituales#

CI: traducir al fusionar#

- 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 rellena los huecos.

Rehace unas pocas cadenas#

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

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

Iteración sobre un único archivo#

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

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

Añadir un nuevo idioma#

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

lingo push --backfill-missing

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