Lingo.dev CLIは、1つのi18n.json設定ファイルを読み込み、ソースファイルから翻訳可能な文字列を抽出し、それらをローカライゼーションエンジンまたはLLMプロバイダーに渡すことで、アプリやコンテンツを翻訳します。翻訳結果はディスクに書き戻され、変更内容も追跡されるため、次回の実行では差分だけが処理されます。
5つのステップで動くパイプライン#
npx lingo.dev@latest runを実行すると、CLIは次の5つのステップを順番に実行します。
コンテンツの検出
CLIは、i18n.json内のbucket configurationsに基づいて、プロジェクト内のソースファイルとターゲットファイルをスキャンします。各bucketでは、ファイル形式とinclude/excludeパターンのセットを定義し、翻訳可能なコンテンツがどこにあるかをCLIに伝えます。
{
"locale": {
"source": "en",
"targets": ["es", "fr", "de"]
},
"buckets": {
"json": {
"include": ["locales/[locale].json"]
},
"markdown": {
"include": ["docs/[locale]/*.md"]
}
}
}[locale]プレースホルダーは、実行時に設定済みのソースおよびターゲットのロケールコードに展開されます。
データのクリーニング
すべてのコンテンツを翻訳する必要があるわけではありません。CLIは、言語が変わってもそのままでよい値、たとえば数値、真偽値、ISO日付、UUID、URL、空文字列を除外します。これにより翻訳バックエンドへ送るペイロードを減らし、トークン消費量と処理時間を抑えられます。
差分の算出
CLIは各ソース文字列に対してSHA-256フィンガープリントを計算し、i18n.lockに保存された前回の状態と比較します。翻訳パイプラインに入るのは、新規または変更されたコンテンツだけです。変更のない文字列は完全にスキップされます。
この増分アプローチにより、10,000個のキーがあるプロジェクトでも、変更されたのが12個だけなら翻訳されるのはその12個だけで、全件を処理する必要はありません。
ローカライゼーション
差分は、設定された翻訳バックエンドに送信されます。CLIは2つのモードに対応しています。
| モード | 仕組み |
|---|---|
| Lingo.dev Engine | リクエストをローカライゼーションエンジン経由で処理し、ブランドボイス、glossary、instructions、model configurationを自動で適用します。 |
| Raw LLM provider | カスタムプロンプトを使って、翻訳リクエストをOpenAI、Anthropic、Google、Mistral、OpenRouter、Ollamaへ直接送信します。 |
CLIは失敗したリクエストを指数バックオフで再試行し、途中経過を保存しながら、複数のターゲット言語を並行して処理します。
コンテンツの書き戻し
翻訳された文字列は、ソースコンテンツがある正確な位置にディスクへ書き戻されます。CLIはファイル構造と書式を保つことで、最小限でレビューしやすい差分を生成します。プロジェクトでPrettierが設定されている場合は、出力もそのフォーマットルールに従います。
出力ファイル#
通常の実行では、次の2種類の変更が生成されます。
- ロケールファイル - 新規および変更された翻訳が反映されたターゲット言語ファイル
i18n.lock- 状態追跡用のコンテンツフィンガープリントで更新されたファイル
どちらもバージョン管理にコミットする必要があります。手動でも、CI/CD integrationを通じた自動でも構いません。
