クイックスタート

インストール、認証、エンジンへのリンク、ソースの push、翻訳の pull まで、一連の流れをひととおり進めます。

前提条件

Node.js 22 以上（確認には node -v を使用）。CLI はインストール後、lingo として実行できます。

セットアップ#

インストール

bash

npm install -g @lingo.dev/cli

または pnpm add -g @lingo.dev/cli / yarn global add @lingo.dev/cli / bun add -g @lingo.dev/cli を使います。

認証

bash

lingo login

メールアドレスを入力すると、CLI からワンタイムコードが送信され、セッショントークンが ~/.lingo/auth.json に保存されます。CI や非対話環境では、API キーを使ってください: lingo login --api-key lk_...（または、任意のコマンドで --api-key をグローバルフラグとして指定することもできます）。

プロジェクトを初期化

プロジェクトのルートで次を実行します:

bash

lingo init

source locale、target locales、file patterns（ソースファイルを指定する glob）を順に設定します。ローカライゼーション設定は .lingo/config.json に書き込まれます。このファイルは必ずコミットしてください。何を翻訳対象にするかを定義する正本です。

エンジンにリンク

bash

lingo link

組織とローカライゼーションエンジンを選ぶか、新しく作成します。エンジンには、AIモデルの設定、用語集、ブランドボイス、ルールがまとめて保存されます。Lingo.dev platform で一度設定しておけば、複数のプロジェクトで繰り返し使えます。link は orgId と engineId を .lingo/config.json に追記します（こちらもコミットされます）。

最初の push#

空ではないソースファイル（例: locales/en.json）を用意したら、

bash

lingo push --backfill-missing --wait

設定済みのすべてのパターンにわたって、未翻訳のターゲットをすべて翻訳します。--wait を付けると、実行が完了するまで CLI が接続されたままになり、その後、出力（locales/de.json、locales/fr.json、...）をディスクに書き出します。クリーンなチェックアウトでは、所要時間は数秒（小さな JSON）から数分（大きな markdown バンドル）までさまざまです。--wait を付けない場合、push は実行の送信後すぐに終了し、lingo pull が後から出力を書き出します。

完了すると:

text

✓ Run lrg_a8c... : localized 12 target file(s), uploaded 1 new artifact(s).

次回以降の実行#

ソースファイルを編集したあとは、通常の lingo push で差分だけが翻訳されます。ソースハッシュが変わっていないファイルは、サーバー側でスキップされます。ローカルで編集したターゲットはデフォルトで保持されます。上書きしたい場合は、スコープを指定して --force を渡してください。

bash

lingo push                       # delta only
lingo push docs/en/**/*.md       # scoped: only this subtree
lingo push docs/en/about.md -f   # scoped + force: retranslate even if up to date

これらはどれも、実行を送信すると終了します。同じコマンドで出力まで書き出すには --wait を追加するか、lingo pull で後から取得してください。

後で取得する#

push は実行 ID を ~/.lingo/runs/<hash>.json に記録します（絶対プロジェクトパスをキーとして使用）。その後、同じマシンの同じチェックアウトから次のように実行できます。

bash

lingo pull

…まだ実行中であれば、最後のプッシュが完了するまで待ってから出力を書き出します。翻訳の途中でターミナルを閉じてしまった場合に便利です。ほかのマシンでは、コミット後に翻訳を取得できます。

次に読むもの#

Configuration — .lingo/config.json のスキーマ、lockfile、実行状態の保存場所。
lingo push — スコープ付きパターン、--force、再試行のしくみ。
lingo pull — 競合検出、--dry-run。