ビルドモード

@lingo.dev/compilerは、翻訳の生成タイミングと方法を制御する2つのビルドモードをサポートしています。

モード概要

モード使用場面API呼び出し動作
translate開発、CIあり設定されたLLMを使用して不足している翻訳を生成
cache-only本番ビルドなし.lingo/metadata.jsonからキャッシュされた翻訳のみを使用

translateモード

目的: ビルド時にオンデマンドで翻訳を生成します。

{
  buildMode: "translate"
}

動作:

  • コードをスキャンして翻訳可能なテキストを検出
  • .lingo/metadata.jsonで既存の翻訳を確認
  • 設定されたLLMプロバイダー経由で不足している翻訳を生成
  • .lingo/metadata.jsonを新しい翻訳で更新
  • 翻訳生成が失敗した場合はビルドを失敗させる

使用場面:

  • ローカル開発(usePseudotranslator: trueを使用)
  • CI/CDパイプライン(実際のLLMプロバイダーを使用)
  • 初期セットアップと翻訳生成

必要条件:

  • 設定されたプロバイダーの有効なAPIキー(または疑似翻訳機能が有効)
  • LLMプロバイダーへのネットワーク接続

cache-onlyモード

目的: 事前生成された翻訳のみを使用してビルドします。

{
  buildMode: "cache-only"
}

動作:

  • .lingo/metadata.jsonから翻訳を読み込む
  • API呼び出しは行わない
  • いずれかのロケールで翻訳が不足している場合はビルドを失敗させる
  • 高速で決定論的なビルド

使用場面:

  • 本番ビルド
  • APIキーなしのデプロイメント
  • ネットワークアクセスが制限された環境

必要条件:

  • すべてのロケールの翻訳を含む.lingo/metadata.json
  • CIまたは開発環境で事前生成された翻訳

推奨ワークフロー

1. ローカル開発

即座のフィードバックのために疑似翻訳機能を使用します:

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: true,
  }
}

メリット:

  • 即座の疑似翻訳
  • APIコストなし
  • 翻訳対象を正確に確認可能
  • さまざまなテキスト長でUIをテスト

2. CI/CDパイプライン

CIで実際の翻訳を生成します:

{
  buildMode: "translate",
  dev: {
    usePseudotranslator: false,
  }
}

CIでのセットアップ:

# GitHub Actions example
- name: Install dependencies
  run: pnpm install

- name: Generate translations
  env:
    LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
  run: pnpm run build

- name: Commit translations
  run: |
    git config user.name "github-actions[bot]"
    git config user.email "github-actions[bot]@users.noreply.github.com"
    git add .lingo/
    git commit -m "chore: update translations" || exit 0
    git push

メリット:

  • デプロイごとに1回だけ実際の翻訳が生成される
  • バージョン管理にコミットされる
  • 本番ビルドにAPIキーが不要

3. 本番ビルド

キャッシュされた翻訳のみを使用します:

{
  buildMode: "cache-only",
}

メリット:

  • APIキーが不要
  • 高速なビルド
  • 決定論的—同じ入力は常に同じ出力を生成
  • 外部ネットワーク依存性なし

環境変数によるオーバーライド

環境変数を使用してビルドモードをオーバーライドします:

# Force cache-only mode
LINGO_BUILD_MODE=cache-only npm run build

# Force translate mode
LINGO_BUILD_MODE=translate npm run build

これは、設定を変更せずにcache-onlyを強制したいデプロイ環境で便利です。

翻訳の欠落への対処

translateモードの場合

翻訳が失敗した場合:

Error: Failed to generate translation for locale "es":
  - Hash: abc123def
  - Source text: "Welcome to our app"
  - Provider: lingo.dev
  - Reason: API key invalid

解決策: APIキーを修正し、ビルドを再実行します。

cache-onlyモードの場合

翻訳が欠落している場合:

Error: Missing translations for locale "es":
  - Hash: abc123def
  - Source text: "Welcome to our app"
  - File: app/page.tsx:12

Run with buildMode: "translate" to generate missing translations.

解決策: translateモードでビルドを実行して欠落している翻訳を生成し、.lingo/をコミットします。

インクリメンタル翻訳

コンパイラはコンテンツハッシュを使用して、翻訳が必要なものを判断します:

  1. 翻訳可能な各文字列は安定したハッシュを取得します
  2. ハッシュはソーステキスト+コンテキストに基づきます
  3. ハッシュが.lingo/metadata.jsonに存在する場合、翻訳が再利用されます
  4. 新規または変更されたテキストのみが再翻訳をトリガーします

結果: 翻訳の支払いは一度だけです。その後のビルドではキャッシュされた翻訳が再利用されます。

CI設定例

GitHub Actions

name: Generate Translations

on:
  push:
    branches: [main]
  pull_request:

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v2
        with:
          version: 8

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "pnpm"

      - name: Install dependencies
        run: pnpm install

      - name: Generate translations
        env:
          LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
        run: pnpm run build

      - name: Commit translations
        if: github.event_name == 'push'
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add .lingo/
          git diff --quiet && git diff --staged --quiet || git commit -m "chore: update translations"
          git push

GitLab CI

stages:
  - translate

generate-translations:
  stage: translate
  script:
    - pnpm install
    - pnpm run build
    - git config user.name "GitLab CI"
    - git config user.email "[email protected]"
    - git add .lingo/
    - git diff --quiet && git diff --staged --quiet || git commit -m "chore: update translations"
    - git push origin HEAD:$CI_COMMIT_REF_NAME
  only:
    - main

よくある質問

本番環境でAPIキーは必要ですか? いいえ。本番環境ではbuildMode: "cache-only"を使用してください。翻訳はCIで事前生成されます。

CIで翻訳の生成を忘れた場合はどうなりますか? 本番ビルドは、不足している翻訳を明確にリストアップしたエラーで失敗します。CIで翻訳を生成し、コミットして再デプロイしてください。

本番環境でtranslateモードを使用できますか? はい、ただし推奨されません。ビルドが非決定的になり、本番環境でAPIキーが必要になります。CIで翻訳を生成する方が良いでしょう。

ローカルでcache-onlyモードをテストするにはどうすればよいですか?

  1. translateモードで翻訳を生成します
  2. cache-onlyモードに切り替えます
  3. ビルドを実行します—キャッシュされた翻訳を使用して成功するはずです

ソーステキストが変更された場合はどうなりますか? ハッシュが変更されるため、新しい翻訳が生成されます(translateモード)。古い翻訳は履歴のために.lingo/metadata.jsonに保持されます。

.lingo/をgitにコミットする必要がありますか? はい。.lingo/ディレクトリはバージョン管理する必要があります。翻訳キャッシュが含まれています。

次のステップ