アルファ
Lingo.dev Compiler はアルファ版です。動作は安定しておらず、本番利用は推奨されません。また、API はリリースごとに変更される可能性があります。
Lingo.dev Compiler には、ビルド中に新しい翻訳を生成するかどうかを制御する2つのビルドモードがあります。信頼性の高い開発・CI・本番パイプラインを構築するうえで、これらのモードを理解することは欠かせません。
2つのモード#
| モード | 動作 | 使用する場面 |
|---|---|---|
"translate" | 設定された LLM プロバイダーを呼び出し、不足している翻訳を生成します。キャッシュ済みの翻訳は再利用されます。 | 開発と CI。新規または変更されたテキストを翻訳する必要があるときに使用します。 |
"cache-only" | .lingo/metadata.json の翻訳のみを使用します。翻訳が1つでも不足していると失敗します。 | 本番ビルド。外部 API を呼び出さず、再現性のある出力が得られます。 |
translate mode の仕組み#
translate モードでは、Compiler が各翻訳対象の文字列を .lingo/metadata.json と照合します。キャッシュ済みの翻訳があり、ソーステキストに変更がなければ、そのキャッシュが使われます。文字列が新規または変更済みの場合は、Compiler が設定された翻訳プロバイダーを呼び出して翻訳を生成し、キャッシュを更新します。
{
buildMode: "translate",
}このモードがデフォルトです。疑似翻訳ツール（API 呼び出しなしですぐにダミー翻訳を生成）と、実際の LLM プロバイダーの両方に対応しています。
cache-only mode の仕組み#
cache-only モードでは、Compiler は .lingo/metadata.json からのみ翻訳を読み込みます。LLM は呼び出されません。翻訳対象の文字列が1つでもキャッシュにない場合は、不足している文字列を一覧表示したエラーとともにビルドが失敗します。
.lingo/metadata.json は必ずバージョン管理にコミットしてください。cache-only モードでの本番ビルドは、このファイルがローカルで生成されているだけでなく、リポジトリに存在していることを前提とします。
{
buildMode: "cache-only",
}このモードでは再現性のあるビルドが可能です。つまり、同じソースコードとキャッシュからは常に同じ出力が生成されます。さらに、本番ビルド時の外部 API 依存も排除できます。
推奨ワークフロー#
開発 - 疑似翻訳ツール
API を呼び出さずにすぐフィードバックを得るには、疑似翻訳ツールを有効にします。
{
buildMode: "translate",
dev: {
usePseudotranslator: true,
},
}疑似翻訳は [!!! Welcome !!!] のように表示されるため、未翻訳の文字列を見つけやすく、文字数の違いによるレイアウト崩れもテストしやすくなります。
CI - translate mode
buildMode: "translate" と実際の LLM プロバイダーで実行します。CI ジョブが新規または変更された文字列の翻訳を生成し、更新された .lingo/metadata.json をリポジトリにコミットし直します。
# CI environment
LINGO_BUILD_MODE=translate npm run build本番 - cache-only mode
事前生成済みの翻訳のみを使うため、buildMode: "cache-only" でデプロイします。本番環境では API キーは不要です。
# Production environment
LINGO_BUILD_MODE=cache-only npm run build環境変数による上書き#
LINGO_BUILD_MODE 環境変数は buildMode の設定オプションより優先されます。これにより、環境をまたいで同じ設定ファイルを使えます。
# Override in any environment
LINGO_BUILD_MODE=cache-only npm run build環境変数は設定ファイルの値より優先されます。
CI の例#
# .github/workflows/translate.yml
name: Generate Translations
on:
push:
branches: [main]
jobs:
translate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm run build
env:
LINGO_BUILD_MODE: translate
LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
- uses: stefanzweifel/git-auto-commit-action@v5
with:
commit_message: "chore: update translations"
file_pattern: ".lingo/metadata.json"必ず .lingo/metadata.json をバージョン管理にコミットしてください。cache-only モードでの本番ビルドはこのファイルに依存します。ファイルがない、または内容が不完全な場合、ビルドは失敗します。
