@lingo.dev/cli はソースコンテンツを ローカライゼーションエンジン に送り、エンジンが翻訳を生成する間待機し、出力をディスクに書き戻します。従来の npx lingo.dev フローに代わるものですが、同じプロジェクトでもアーキテクチャは根本から異なります。
従来のCLIとの違い#
従来のCLI（npx lingo.dev run）は文字列を抽出し、手元のマシンから直接LLMを呼び出して、1回の同期処理でファイルを書き出していました。新しいCLIは非同期が前提です。
lingo pushはソースをあなたのエンジンにアップロードし、サーバー側のワークフローを開始して、完了まで待機するか、run IDを返してすぐに終了しますlingo pullは直近のpushの出力を取得します。翻訳の途中でターミナルを閉じても、別のマシンからpullしても動作します- lockfile（
.lingo/lock.json）は各ターゲットのサーバー上での最終既知バージョンを追跡し、上書き前にローカルの編集を競合として検出できるようにします
これにより、従来のCLIではできなかった2つのことが可能になります。ターミナルを占有し続けずに長時間の翻訳を走らせることと、pushを実行したマシンとは別のマシン（またはCI）で結果をpullすることです。
結果を待つ#
現時点では、lingo push はソースをアップロードし、サーバー側のワークフローを開始し、完了まで待機して、出力を書き込みます。これらすべてを1つのコマンドで実行します。--wait（-w）を付けると、このブロッキング動作を明示できます。完了済みのrunには、あとから lingo pull で再接続することもできます。
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 stateはマシンごとに~/.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 | ブートストラップ — まだ存在しないターゲットファイルを作成します | 最初のpush時、または新しいロケールを追加したあと |
lingo push --force | 完全再翻訳 — すべてのターゲットを上書きします（手動編集を含む）。--yes/-y で確認プロンプトをスキップします | まれに（例: 用語集やエンジンの変更後） |
--backfill-missing はブートストラップ用のフラグです。対象を絞った新規リクエストを実行し、足りないターゲットファイル全体だけを追加します。すでに翻訳済みのファイルに新しく追加されたキーは翻訳しません（runでは「already up-to-date」と表示され、そのキーはスキップされます）。継続的な編集には通常の lingo push を使ってください。
翻訳を手動で編集する#
通常の lingo push では、キー単位で手動編集が保持されます。
- ターゲット文字列を編集する（対応するソースは未変更）→ その文字列は保持され、他のキーは引き続き更新されます。
- 手動編集したキーの元ソースが変更される → そのキーには新しい翻訳が生成され、手動編集は置き換えられます。
- 新しいソースキーが追加される → 手動編集を含むファイルであっても、翻訳されて追加されます。
