ベストプラクティス - Lingo.dev Compiler

@lingo.dev/compilerの推奨パターンとワークフロー。

開発ワークフロー

デフォルトでPseudotranslatorを使用する

推奨:

{
  dev: {
    usePseudotranslator: true, // Fast, free, instant feedback
  }
}

理由:

即座にフィードバックが得られる—APIレイテンシなし
コストゼロ—APIクレジットを消費しない
視覚的なマーカーで翻訳対象を表示
さまざまなテキスト長でUIをテスト

実際の翻訳品質を確認する場合のみ無効にしてください。

開発、CI、本番環境を分離する

開発:

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

CI:

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

本番:

{
  buildMode: "cache-only",
}

このワークフローにより:

開発を高速かつ低コストに保つ
デプロイごとにCIで実際の翻訳を1回生成
本番ビルドを決定論的かつ高速にする

翻訳戦略

ほとんどの翻訳をAIに任せる

推奨:

<p>Welcome to our application</p>

非推奨:

<p data-lingo-override={{ es: "...", de: "...", fr: "..." }}>
  Welcome to our application
</p>

オーバーライドは控えめに使用し、以下の場合のみ使用してください:

ブランド名
特定の翻訳が必要な技術用語
認証が必要な法的文書
人間によるレビューが必要なマーケティングコピー

オーバーライドを一貫して使用する

推奨:

// Consistent brand name across app
<h1 data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>
  Lingo.dev
</h1>

<p>
  Welcome to <span data-lingo-override={{ es: "Lingo.dev", de: "Lingo.dev" }}>
    Lingo.dev
  </span>
</p>

非推奨:

<h1 data-lingo-override={{ es: "Lingo.dev" }}>Lingo.dev</h1>
<p>Welcome to Lingo.dev</p> // Missing override—inconsistent

設定

シンプルに始める

推奨:

{
  sourceLocale: "en",
  targetLocales: ["es", "de"],
  models: "lingo.dev",
}

非推奨:

{
  sourceLocale: "en",
  targetLocales: ["es", "de", "fr", "pt", "it", "ja", "zh", "ar", "ru", "ko"],
  models: {
    "en:es": "groq:...",
    "en:de": "google:...",
    // Complex mappings for 10 locales
  },
  prompt: "Long custom prompt...",
  pluralization: { enabled: false },
}

2~3のターゲットロケールから始めましょう。必要に応じて追加します。早すぎる最適化は避けてください。

Lingo.devエンジンを使用する

推奨:

{
  models: "lingo.dev" // Simple, optimized, supports all features
}

非推奨:

{
  models: {
    "*:*": "groq:...", // Requires manual model selection
  }
}

Lingo.devエンジンは以下を提供します:

自動モデル選択
フォールバック処理
翻訳メモリ
用語集サポート

完全な制御やコスト最適化が必要な場合のみ、LLMプロバイダーを直接使用してください。

ロケール検出

デフォルトのCookieベース永続化を使用する

推奨:

{
  localePersistence: {
    type: "cookie",
    config: {
      name: "locale",
      maxAge: 31536000,
    },
  },
}

カスタマイズが必要な場合:

localStorageが必要な場合(SPAの設定)
URLベースのルーティング(/en/about)
サブドメインルーティング(es.example.com)
データベースベースのユーザー設定

デフォルトが適合しない場合のみ、カスタムロケールリゾルバーを実装してください。

バージョン管理

.lingo/ディレクトリをコミットする

推奨:

git add .lingo/
git commit -m "chore: update translations"
git push

理由:

バージョン管理で翻訳の変更を追跡できる
チームで翻訳を共有できる
CI/CDでコミット済みの翻訳を使用できる
本番ビルドでAPIキーが不要

CIの実行後にコミット

推奨(CI内):

- name: Generate translations
  run: npm run build

- name: Commit translations
  run: |
    git add .lingo/
    git commit -m "chore: update translations" || exit 0
    git push

これにより、本番ビルドで常に最新の翻訳を使用できます。

CI/CD

CI内で翻訳を生成

推奨:

# GitHub Actions
- name: Generate translations
  env:
    LINGODOTDEV_API_KEY: ${{ secrets.LINGODOTDEV_API_KEY }}
  run: npm run build

非推奨:

# Production build without API key
- name: Build
  run: npm run build # Fails if translations missing

APIキーを使用できるCI内で翻訳を生成します。本番ビルドではキャッシュされた翻訳を使用します。

本番環境ではcache-onlyを使用

推奨:

# Production build
LINGO_BUILD_MODE=cache-only npm run build

非推奨:

# Production build with translate mode
LINGO_BUILD_MODE=translate npm run build # Non-deterministic, requires API keys

パフォーマンス

複数形を選択的に有効化

推奨(複数形を使用する場合):

{
  pluralization: {
    enabled: true,
  }
}

推奨(複数形を使用しない場合):

{
  pluralization: {
    enabled: false, // Skip plural detection—faster builds
  }
}

複数形化処理により、わずかなオーバーヘッドが発生します(数値を含むテキストごとに1回のLLM呼び出し)。不要な場合は無効化してください。

複数形化処理には高速モデルを使用する

推奨:

{
  pluralization: {
    enabled: true,
    model: "groq:llama-3.1-8b-instant", // Fast, cheap
  }
}

非推奨:

{
  pluralization: {
    model: "openai:gpt-4o", // Expensive overkill for plural detection
  }
}

ロケールペアマッピングの最適化

推奨(コスト最適化):

{
  models: {
    "en:es": "groq:llama-3.3-70b-versatile", // Fast & cheap
    "en:ja": "openai:gpt-4o", // High quality for complex language
    "*:*": "lingo.dev", // Fallback
  }
}

類似言語(ロマンス語派、ゲルマン語派)には高速で低コストなモデルを使用します。複雑な言語(CJK、アラビア語)には高品質なモデルを使用します。

テスト

まず疑似翻訳でテストする

推奨:

疑似翻訳を有効化
すべてのUIコンポーネントをテスト
レイアウトの問題(オーバーフロー、切り捨て)を修正
その後、実際の翻訳を生成

理由:

疑似翻訳は即座に生成される
レイアウトの問題を早期に発見できる
APIコストを節約できる

すべてのターゲットロケールをテストする

推奨:

// Test with locale switcher
<LanguageSwitcher /> // Switch between all locales

// Or manually test
setLocale("es"); // Spanish
setLocale("de"); // German
setLocale("fr"); // French

各ロケールを検証:

翻訳が正しく表示される
レイアウトがテキスト長に対応している
未翻訳のテキストがない
RTL言語が正しくレンダリングされる(該当する場合)

エラー処理

翻訳の欠落を適切に処理する

コンパイラは翻訳が欠落している場合、ビルドを失敗させます。これは意図的な動作です。破損したUIを出荷するよりも、翻訳の欠落を早期に検出する方が望ましいためです。

ビルドが失敗した場合:

buildMode: "translate"を実行して欠落している翻訳を生成
.lingo/metadata.jsonをコミット
buildMode: "cache-only"で本番ビルドを再試行

翻訳の失敗を監視する

CIで翻訳エラーを確認します:

- name: Generate translations
  run: npm run build 2>&1 | tee build.log

- name: Check for translation errors
  run: |
    if grep -q "Failed to generate translation" build.log; then
      echo "Translation generation failed"
      exit 1
    fi

メンテナンス

定期的なクリーンアップ

未使用の翻訳を定期的に削除します:

# Backup first
cp .lingo/metadata.json .lingo/metadata.backup.json

# Manual: Search for each hash in codebase, remove if not found

# Automated (coming soon):
npx @lingo.dev/compiler clean

ファイルサイズの監視

.lingo/metadata.jsonはアプリとともに増大します。大きくなった場合(5 MBを超える場合):

複数のアプリに分割することを検討
古い翻訳をアーカイブ
自動クリーンアップを使用

よくあるアンチパターン

オーバーライドを過度に使用しない

悪い例:

<p data-lingo-override={{ es: "...", de: "...", fr: "..." }}>
  Welcome to our app
</p>

通常のテキストはAIに処理させます。オーバーライドは例外的な場合にのみ使用します。

APIキーをコミットしない

悪い例:

// next.config.ts
{
  models: "lingo.dev",
  apiKey: "your-api-key-here", // NEVER commit API keys
}

良い例:

# .env (not committed)
LINGODOTDEV_API_KEY=your_key_here

本番環境でtranslateモードを使用しない

悪い例:

// production config
{
  buildMode: "translate", // Non-deterministic, requires API keys
}

良い例:

{
  buildMode: "cache-only", // Deterministic, no API keys
}

バージョン管理をスキップしない

悪い例:

# .gitignore
.lingo/ # DON'T ignore translations

良い例:

# .gitignore
.env # Ignore API keys only

移行戦略

段階的なロールアウト

既存のアプリにコンパイラを追加する場合:

1〜2のロケールから開始
疑似翻訳機能を有効化
すべてのページをテスト
レイアウトの問題を修正
さらにロケールを追加
実際の翻訳を生成
デプロイ

初日に20のロケールを翻訳しようとしないでください。

段階的な導入

アプリ全体を一度に翻訳する必要はありません:

{
  useDirective: true, // Opt-in per file
}

翻訳したいファイルに'use i18n'ディレクティブを追加します:

'use i18n'; // This file gets translated

export function HomePage() {
  return <h1>Welcome</h1>;
}

他のファイルは、オプトインするまで未翻訳のままです。

次のステップ

移行ガイド — 旧コンパイラからの移行
トラブルシューティング — よくある問題と解決策
設定リファレンス — すべてのオプションの説明