クイックスタート

インストール、認証、エンジンへのリンク、ソースの 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

設定済みのすべてのパターンに対して、未翻訳のターゲットをまとめて翻訳します。CLI は実行完了まで待機し、出力（locales/de.json、locales/fr.json、...）をディスクに書き込みます。クリーンなチェックアウトでは、小さな JSON なら数秒、大きな Markdown バンドルなら数分かかることがあります。

完了すると:

text

✓ Run run_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

別のマシンで pull する#

push は実行 ID を ~/.lingo/runs/<hash>.json に記録します（絶対プロジェクトパスをキーとして保存）。同じチェックアウトと同じ認証情報を使えるマシンであれば、どこでも:

bash

lingo pull

…直近の push の出力を取得できます。CI（「翻訳担当者がノート PC から push を実行し、CI がビルドごとに pull を実行する」）や、ターミナルを閉じたあとに作業を再開したいときに便利です。

次に読むもの#

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

インストール、認証、エンジンへのリンク、ソースの 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

プロジェクトを初期化

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

bash

lingo init

エンジンにリンク

bash

lingo link

最初の push#

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

bash

lingo push --backfill-missing

完了すると:

text

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

次回以降の実行#

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

別のマシンで pull する#

bash

lingo pull

次に読むもの#

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