Webアプリのローカライゼーション

Lingo.dev のCLIは、Web アプリのリソースファイル（JSON、YAML、XLIFF、PO、PHP）を、設定済みのローカライゼーションエンジン経由で翻訳します。フレームワークで i18n を設定し、CLI で翻訳ファイルを指定して実行するだけです。

仕組み#

どの Web フレームワークにも、リソースファイルから翻訳を読み込む i18n ライブラリがあります。たとえば React では JSON、Angular では XLIFF、Django では PO を使います。CLI はそれらのファイルを直接翻訳するため、コードを変更しなくてもフレームワーク側でそのまま翻訳を取り込めます。

前提条件#

CLI をインストールして認証します。

npm install -g @lingo.dev/cli
lingo login

CLI の利用には Node.js 22 以降が必要です。CI では対話型ログインをスキップし、--api-key または LINGO_API_KEY 環境変数でキーを渡してください。

CLI を実行するたびに、コンテンツは ローカライゼーションエンジン を通ります。これは、どの LLM モデル、用語集、ブランドボイス、ルールを適用するかを決める設定です。Lingo.dev のダッシュボードで作成し、API key を生成してください。lingo link は、そのエンジンの orgId と engineId を .lingo/config.json に書き込みます。

JavaScript フレームワーク#

各 pattern に含まれるロケールセグメントは、対象ロケールごとに置き換えられます。たとえば public/locales/en/translation.json は public/locales/de/translation.json になります。ソースパスには、ソースロケールのコードが含まれている必要があります。

{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "public/locales/en/translation.json" }]
}

サーバーサイドフレームワーク#

{
  "orgId": "org_...",
  "engineId": "eng_...",
  "sourceLocale": "en",
  "targetLocales": ["es", "fr", "de", "ja"],
  "files": [{ "pattern": "lang/en/messages.php" }]
}

翻訳の実行#

.lingo/config.json を用意したら、1 つのコマンドですべてのリソースファイルを翻訳できます。

lingo push

CLI はソースロケールのファイルを読み込み、lockfile（.lingo/lock.json。設定ファイルとあわせてコミットします）を使って前回の実行以降の変更を判定し、差分だけを翻訳して対象ロケールのファイルに書き込みます。既存の翻訳はそのまま保持され、CLI が補完するのは未翻訳または更新された文字列のみです。

初回実行時、または新しい対象ロケールを追加したあとは、すべてをゼロから翻訳します。

lingo push --backfill-missing

glob を指定すれば、実行対象を一部のファイルだけに絞れます。

lingo push "messages/**"

翻訳は行わず、別の場所（たとえば別のマシンやビルドステップ）で最新の翻訳だけを取得したい場合は、lingo pull を実行します。翻訳が最新の状態かを確認するデプロイゲートとして lingo check を使ってください。

次のステップ#