lingo push

Envoyez les fichiers source au moteur, attendez la fin de l’exécution, puis écrivez les fichiers de sortie sur le disque.

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

Comportement par défaut — push delta#

Sans argument, lingo push exécute le mode delta uniquement :

1. Calculer le hash de chaque fichier source correspondant aux motifs files de la configuration
2. Comparer chaque hash au fichier de verrouillage pour repérer les sources modifiées
3. Téléverser les sources modifiées sous forme d’exécution sur le moteur
4. Attendre la fin de l’exécution
5. Écrire les fichiers de sortie sur le disque
6. Enregistrer les nouveaux hash source dans le fichier de verrouillage

Si aucune source n’a changé depuis le dernier push réussi, la commande s’arrête immédiatement avec ✓ Nothing to push. — aucun aller-retour vers le serveur, aucune consommation de jetons.

Arguments et options#

Positionnel : patterns... — push ciblé#

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

Limite le push à des fichiers précis (ils doivent déjà correspondre à des motifs définis dans .lingo/config.json). La commande bascule alors en mode ciblé :

• Aucune comparaison avec l’état précédent des sources — chaque source correspondante est considérée dans le périmètre, même si elle n’a pas changé.
• No-op côté serveur pour les cibles qui existent déjà avec des hash source identiques — le moteur les ignore et le CLI les signale comme mises en cache.

À utiliser si vous voulez traduire exactement un fichier mis à jour sans recalculer les hash de tout le projet, ou retraduire une seule page avec --force.

--key <pattern>#

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

Retraduisez uniquement les clés couvertes par un motif, fusionnez-les dans la traduction existante et laissez toutes les autres clés strictement identiques, octet pour octet. Répétable — un --key par motif.

Une portée de clés ignore le diff de la source : même une clé dont le texte source n’a jamais changé est retraduite. C’est précisément le but de ce flag : la méthode prise en charge pour retravailler une poignée de chaînes après un changement de formulation, de modèle ou de glossaire, sans payer pour le reste du fichier.

--force n’ajoute rien d’autre et supprime l’invite de confirmation pour le fichier entier.

Ce qui arrive à chaque clé#

C’est cette dernière ligne qui distingue une portée de clés d’un push normal. Une clé ajoutée à la source depuis votre dernier push complet n’est pas reprise dans la traduction sous forme de texte source : elle est laissée de côté, et le prochain lingo push simple la traduira.

Comment un motif correspond#

Un motif peut correspondre exactement à une clé, à un préfixe se terminant sur une frontière ., /, - ou [, ou encore à un glob. Les éléments de tableau sont accessibles via la frontière entre crochets, donc nav.items couvre nav.items[0].title.

Mettez les globs entre guillemets. Votre shell les développe d’abord : dans zsh, un --key auth.* nu échoue soit avec no matches found, soit — si un fichier comme auth.json se trouve dans le répertoire — devient silencieusement ce nom de fichier. Une valeur séparée par des virgules n’est pas une liste : --key "a,b" est un seul motif littéral qui ne correspond à rien. Répétez plutôt le flag.

Ce qu’il refuse#

Une portée de clés signale puis ignore, plutôt que d’en faire discrètement plus que demandé :

• Une langue sans traduction existante. Il n’y a rien dans quoi fusionner, donc la langue est indiquée puis ignorée — traduisez-la une première fois avec --backfill-missing, puis utilisez --key.
• Formats pour lesquels aucune clé ne peut être omise — Les formats de document, dont les clés changent dès que le document est modifié, ainsi que xcode-stringsdict, pour lesquels le fichier a besoin des catégories de pluriel pour rester valide. Formats contient la liste complète. Ces fichiers sont ignorés avec un avertissement ; un push peut donc malgré tout les mélanger à des fichiers clé-valeur. Envoyez-les sans --key.
• Une portée qui ne correspond à rien le signale, au lieu d’indiquer que l’exécution est déjà à jour.

Les éléments positionnels conservent leur texte source même avec une portée — éléments de tableau, éléments Android <string-array>, quantités <plurals> — car en retirer un renuméroterait tous les autres.

Cela ne met pas à jour le lockfile#

Une exécution avec portée de clés ne traduit qu’une partie d’un fichier ; elle laisse donc volontairement intact le hash source dans le lockfile. Tout le reste qui a changé dans ce fichier reste en attente, et le prochain lingo push simple le prendra en compte.

--force / -f#

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

Retraduit chaque cible correspondante, en ignorant toute traduction existante et en contournant le cache côté serveur. Limitez sa portée — avec des motifs positionnels ou --backfill-missing — sauf si vous visez vraiment l’ensemble du projet : un lingo push --force nu retraduit tous les motifs configurés, et seule la confirmation ci-dessous s’y oppose.

Sur un projet qui n’a jamais été traduit, il n’y a rien à remplacer, donc --force n’apporte rien ici — préférez plutôt --backfill-missing. De manière générale, c’est aussi l’option la plus sûre : elle se contente de combler les manques et ne déclenche jamais d’invite.

Par défaut, --force demande une confirmation avant de s’exécuter :

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

Passez --yes / -y pour ignorer la demande de confirmation (compatible CI).

Pour retravailler quelques chaînes plutôt que des fichiers entiers, utilisez --key — vous ne payez que pour les clés que vous nommez.

--backfill-missing#

lingo push --backfill-missing

Traduit chaque cible qui n’existe pas encore pour tous les motifs configurés. Équivalent à un push ciblé sur tous les motifs de la configuration, mais en ne produisant que les fichiers absents. À utiliser après l’ajout d’une nouvelle langue à targetLocales, ou lors du premier push d’un nouveau projet.

Combinez-le avec --force pour tout retraduire depuis zéro :

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

--yes / -y#

Ignore l’invite de confirmation --force. Aucun effet sans --force, ni aux côtés de --key — une portée de clés ne demande jamais de confirmation, puisqu’elle ne touche qu’aux clés que vous avez nommées.

--estimate#

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

Affiche le coût approximatif de ce push, puis s’arrête sans traduire. Le CLI exécute tout le pipeline de push — hachage, delta et téléversement des octets source — pour permettre au serveur de calculer le delta exact, puis demande au moteur d’estimer le coût de l’exécution au lieu de la lancer. Rien n’est traduit, écrit ni facturé ; le fichier de verrouillage et vos fichiers cibles restent inchangés.

Ces valeurs sont des estimations, pas des devis. --estimate se combine avec la portée ainsi qu’avec --key / --force / --backfill-missing, pour vous permettre de chiffrer exactement le push que vous vous apprêtez à lancer.

Si aucune source n’a changé, --estimate s’interrompt immédiatement avec ✓ Nothing to push., comme lors d’un push classique.

Si une exécution portant sur les mêmes sources est déjà en cours, --estimate échoue plutôt que d’estimer le coût d’une exécution déjà partiellement lancée :

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

Sortie#

En cas de succès :

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

Le résumé se décompose ainsi :

• N fichier(s) cible localisé(s) — le moteur a généré de nouvelles traductions et le CLI les a écrites.
• N déjà à jour — correspondances dans le cache côté serveur (source identique, cible réutilisée).
• N nouvel/nouveaux artefact(s) téléversé(s) — sources que le moteur n’avait encore jamais vues (contenu binaire/volumineux stocké une seule fois, puis référencé).
• N cible(s) ignorée(s) (modifications locales) — les hash locaux des cibles diffèrent du fichier de verrouillage. Relancez avec --force pour écraser.

En cas d’échec sur une cible, le CLI affiche l’erreur de chaque cible en échec et se termine avec un code non nul — pratique pour la 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

Avec --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.

Sémantique de relance#

Le fichier de verrouillage n’est mis à jour qu’après une exécution entièrement réussie. En cas d’échec partiel (par ex. une langue expire sur délai), les hash source restent inchangés dans le fichier de verrouillage, de sorte que le prochain lingo push relance le même diff — sans réinitialisation manuelle.

Si le moteur renvoie une erreur avant toute traduction (authentification, validation), rien n’est écrit et le fichier de verrouillage reste inchangé.

Motifs courants#

CI : traduction au merge#

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

--backfill-missing est l’option sûre par défaut : rien n’est écrasé, seuls les manques sont comblés.

Retravailler quelques chaînes#

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

Retraduisez exactement ces clés après un changement de formulation, sans toucher aux autres clés du fichier.

Itération sur un seul fichier#

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

Retraduisez une seule source après une modification majeure du contenu. Ignorez l’invite de confirmation pour itérer rapidement.

Ajout d’une nouvelle langue#

Après avoir mis à jour targetLocales dans .lingo/config.json :

lingo push --backfill-missing

Traduit l’ensemble du corpus dans la nouvelle langue, sans retraduire les langues existantes.