@lingo.dev/cli はソースコンテンツを ローカライゼーションエンジン に送り、エンジンが翻訳を生成するのを待って、出力をディスクに書き戻します。従来の npx lingo.dev フローに代わる仕組みで、同じプロジェクトでもアーキテクチャは根本から異なります。
従来の CLI との違い#
従来の CLI（npx lingo.dev run）は文字列を抽出し、手元のマシンから直接 LLM を呼び出して、そのまま 1 回でファイルを書き出していました。現在の CLI では、この処理を push と pull に分けています。
lingo pushはソースをエンジンにアップロードし、サーバー側のワークフローを開始して、完了まで待機するか、run ID を返してすぐに終了しますlingo pullは直近の push の出力を取得します。翻訳の途中でターミナルを閉じていても、別のマシンから pull していても動作します- lockfile（
.lingo/lock.json）は各ターゲットのサーバー上の最新既知バージョンを追跡し、上書き前にローカルでの編集を競合として検出できるようにします
これにより、従来の CLI では難しかった 2 つのことが可能になります。1 つはターミナルを開いたままにせずに長時間の翻訳を走らせること、もう 1 つは push を実行したマシンとは別のマシン（または CI）で結果を pull することです。
結果を待つ#
現時点では、lingo push がソースをアップロードし、サーバー側のワークフローを開始し、完了まで待機して、出力を書き込みます。これらはすべて 1 つのコマンドで実行されます。--wait（-w）を付けると、このブロッキング動作を明示できます。あとから lingo pull を使って、完了済みの run に再接続することもできます。
lingo push # submit, wait, and write outputs (current default)
lingo push --wait # same thing, made explicit
lingo pull # later: re-attach to the most recent push and download its outputs今後の変更: 次回リリースではデフォルト動作が変わり、lingo push は run を送信するとすぐに終了するようになります。完了した翻訳のダウンロードは lingo pull で行い、--wait（-w）を使うと、1 コマンドで待機する従来のブロッキングフローに戻せます。
--wait（-w）はワークフローが完了するまで待機し、同じコマンド内で出力を書き込みます。lingo pullはこのプロジェクトの直近の push に再接続して、その出力をダウンロードします。ターミナルを閉じたあとでも使えます。run の状態はマシンごとに~/.lingo/runs/<project-hash>.jsonに保存されるため、pullは同じマシン上で再開されます。
認証: どちらのコマンドも LINGO_API_KEY（または --api-key、もしくは lingo login セッション）を参照します。CI では LINGO_API_KEY を設定するだけで十分です。
push モード#
| コマンド | モード | 使うタイミング |
|---|---|---|
lingo push | インクリメンタル — ソースを .lingo/lock.json と比較して差分を取り、新規または変更されたキーだけを既存のターゲットに翻訳し、それ以外はそのまま保持します | 日常的な実行 / CI |
lingo push --backfill-missing | ブートストラップ — まだ存在しないターゲット FILES を埋めます | 最初の push、または新しいロケールを追加したあと |
lingo push --force | 完全再翻訳 — すべてのターゲットを上書きします（手動編集を含む）。--yes/-y を付けると確認プロンプトをスキップします | ごくまれに（例: 用語集 / エンジンの変更後） |
--backfill-missing はブートストラップ用のフラグです。対象を絞った新規リクエストを行い、不足しているターゲットファイル全体だけを追加します。すでに翻訳済みのファイルに新しく追加されたキーは翻訳されません（run では "already up-to-date" と表示され、そのキーはスキップされます）。継続的な編集には通常の lingo push を使ってください。
翻訳を手動で編集する#
通常の lingo push では、キー単位で手動編集が保持されます。
- ターゲット文字列を編集した場合（対応するソースが未変更）→ その文字列は保持され、ほかのキーは引き続き更新されます。
- 手動編集したキーに対応するソースが変更された場合 → そのキーには新しい翻訳が生成され、手動編集は置き換えられます。
- 新しいソースキーが追加された場合 → 手動編集のあるファイルであっても、翻訳されて追加されます。
