トラブルシューティング

@lingo.dev/compilerの使用時によくある問題と解決方法。

インストールの問題

"Cannot find module '@lingo.dev/compiler'"

原因: パッケージがインストールされていないか、正しくインストールされていません。

解決策:

npm install @lingo.dev/compiler
# or
pnpm install @lingo.dev/compiler

インストールを確認:

ls node_modules/@lingo.dev/compiler

"Module not found: Can't resolve '@lingo.dev/compiler/react'"

原因: 間違ったパスからインポートしているか、パッケージが古いバージョンです。

解決策:

  1. import文を確認:

    import { LingoProvider } from "@lingo.dev/compiler/react"; // Correct

  2. パッケージを再インストール:

    rm -rf node_modules
npm install

設定の問題

"Config must be async function" (Next.js)

原因: Next.js設定が非同期関数でラップされていません。

解決策:

// Wrong
export default withLingo(nextConfig, {...});

// Correct
export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {...});
}

"sourceLocale is required"

原因: 設定にsourceLocaleが不足しています。

解決策:

{
  sourceLocale: "en", // Required
  targetLocales: ["es", "de"],
}

"targetLocales must be an array"

原因: targetLocalesが配列ではないか、空です。

解決方法:

{
  targetLocales: ["es", "de"], // Must be array with at least one locale
}

翻訳の問題

翻訳が表示されない

症状: テキストがソース言語でのみ表示されます。

原因と解決方法:

1. LingoProviderが追加されていないか、誤った場所に配置されている

// Wrong - too low in tree
export default function Page() {
  return (
    <LingoProvider>
      <Content />
    </LingoProvider>
  );
}

// Correct - in root layout
export default function RootLayout({ children }) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

2. メタデータに翻訳が存在しない .lingo/metadata.jsonを確認してください:

{
  "translations": {
    "abc123": {
      "locales": {
        "es": "..." // Should have translation
      }
    }
  }
}

空または存在しない場合は、buildMode: "translate"を指定して実行してください:

npm run dev # or build

3. ビルドモードがキャッシュのみで、キャッシュされた翻訳が存在しない

# Generate translations first
LINGO_BUILD_MODE=translate npm run build

# Then use cache-only
LINGO_BUILD_MODE=cache-only npm run build

すべての翻訳が「[!!! ...]」になる

原因: 疑似翻訳機能が有効になっています。

解決方法:

{
  dev: {
    usePseudotranslator: false, // Disable for real translations
  }
}

開発サーバーを再起動してください。

一部のテキストが翻訳されない

原因:

1. 動的コンテンツまたはprops

// Not translated (yet) - string in variable
const title = "Welcome";
<h1>{title}</h1>

// Translated - string in JSX
<h1>Welcome</h1>

解決方法: コンパイラは文字列リテラルをサポートするよう改良中です。現時点では、テキストを直接JSX内に記述してください。

2. 属性内のテキストには特定の処理が必要です

// Translated automatically
<img alt="Logo" />
<button aria-label="Close" />

// May need explicit handling
<div custom-attr="Some text" /> // Not translated unless configured

3. useDirectiveが有効になっています useDirective: trueの場合、'use i18n'のないファイルは翻訳されません。

解決策: ディレクティブを追加してください:

'use i18n';

export function Component() { ... }

ビルドの問題

「ロケールXの翻訳が見つかりません」

原因: buildMode: "cache-only"ですが、翻訳が存在しません。

解決策:

  1. 翻訳を生成してください:

    npm run dev # or
LINGO_BUILD_MODE=translate npm run build

  2. .lingo/metadata.jsonをコミットしてください

  3. cache-onlyで再試行してください

「翻訳の生成に失敗しました」

原因:

1. 無効なAPIキー

# Check .env file
cat .env | grep API_KEY

プロバイダーに対してAPIキーが正しいことを確認してください。

2. ネットワークの問題 API接続をテストしてください:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

3. レート制限 翻訳生成を遅くするか、APIティアをアップグレードしてください。

4. 無効なモデル設定

// Wrong
{
  models: {
    "*:*": "invalid-provider:model",
  }
}

// Correct
{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",
  }
}

ビルドが遅い

原因:

1. 多数の翻訳を生成しています 新しいテキストを含む最初のビルドは遅くなります。その後のビルドは高速です(キャッシュされます)。

2. 開発環境で疑似翻訳が無効になっています

{
  dev: {
    usePseudotranslator: true, // Enable for fast development
  }
}

3. 不要な複数形化の有効化

{
  pluralization: {
    enabled: false, // Disable if not using plural forms
  }
}

HMRの問題

HMRが動作しない

原因: LingoProviderの配置またはフレームワーク設定。

解決策:

Next.js: LingoProviderがルートレイアウトにあり、ネストされたレイアウトにないことを確認してください。

Vite: lingoCompilerPluginがreact()プラグインの前に配置されていることを確認してください:

plugins: [
  lingoCompilerPlugin({...}), // Before react plugin
  react(),
]

翻訳変更時の状態リセット

原因: ロケール変更によってページリロードがトリガーされる。

期待される動作: setLocale()はデフォルトで新しいロケールを適用するためにページをリロードします。

リロードを回避するには: リロードなしのカスタムpersistLocaleを実装してください:

// .lingo/locale-resolver.client.ts
export function persistLocale(locale: string): void {
  localStorage.setItem("locale", locale);
  // Don't call window.location.reload()
}

注: これにはすべてのロケールの翻訳を事前にロードする必要があります。

API/認証の問題

「APIキーが無効です」

解決策:

1. 環境変数名を確認

# Lingo.dev Engine
LINGODOTDEV_API_KEY=...

# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

2. APIキーが有効であることを確認 プロバイダーのダッシュボードにログインし、キーのステータスを確認してください。

3. キー追加後に開発サーバーを再起動

npm run dev

環境変数は起動時にロードされます。

「認証に失敗しました」(Lingo.dev)

解決方法:

1. 再認証

npx lingo.dev@latest login

2. 手動でAPIキーを設定

# Add to .env
LINGODOTDEV_API_KEY=your_key_here

lingo.devのプロジェクト設定からキーを取得してください。

ブラウザが認証フローをブロック

原因: Braveブラウザまたは拡張機能が認証をブロックしています。

解決方法: .envに手動でAPIキーを追加してください:

LINGODOTDEV_API_KEY=...

サーバーの問題

「翻訳サーバーの起動に失敗しました」

原因: ポート60000〜60099がすべて使用中です。

解決方法:

1. 異なるポート範囲を設定

{
  dev: {
    translationServerStartPort: 61000,
  }
}

2. 既存のプロセスを終了

# Find processes using ports
lsof -i :60000-60099

# Kill process
kill -9 <PID>

「ポート60000は既に使用中です」

原因: 別のプロセスがそのポートを使用しています。

解決方法: サーバーは自動的に次の利用可能なポートを検索します。実際のポートはコンソールで確認してください:

[lingo] Translation server started on port 60001

すべてのポートが使用中の場合は、上記の「翻訳サーバーの起動に失敗しました」を参照してください。

型エラー

"Property 'data-lingo-override' does not exist"

原因: TypeScriptが属性を認識していません。

解決方法: 型宣言を追加してください:

// global.d.ts
declare namespace React {
  interface HTMLAttributes<T> {
    "data-lingo-override"?: Record<string, string>;
  }
}

または引用符を使用してください:

<div {"data-lingo-override"}={{ es: "..." }}>
  Text
</div>

"Type error: Config must return Promise"

原因: Next.js設定が適切に型付けされていません。

解決方法:

import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {...});
}

本番環境の問題

本番環境で翻訳が表示されない

原因:

1. .lingo/がコミットされていない

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

2. 本番ビルドモードが間違っている

// Should be cache-only in production
{
  buildMode: "cache-only",
}

3. CIが翻訳を生成していない CIログを確認してください。翻訳が生成され、コミットされていることを確認してください。

開発環境と本番環境で翻訳が異なる

原因: 本番環境で疑似翻訳機能が有効になっています。

解決方法:

{
  dev: {
    usePseudotranslator: process.env.NODE_ENV === "development", // Only in dev
  }
}

サポートを受ける

それでも解決しない場合:

  1. ログを確認 — コンソールでエラーメッセージを確認してください
  2. .lingo/metadata.jsonを確認 — 構造と内容を検証してください
  3. 疑似翻訳機能でテスト — API問題を切り分けてください
  4. GitHubのissueを確認 — github.com/lingodotdev/lingo.dev/issues
  5. Discordで質問 — discord.gg/lingo

ヘルプを求める際は、以下を含めてください：

  • エラーメッセージ（完全なスタックトレース）
  • 設定（next.config.tsまたはvite.config.ts）
  • パッケージバージョン（npm list @lingo.dev/compiler）
  • 再現手順

よくある質問

Q: 本番環境でAPIキーは必要ですか？ A: いいえ、buildMode: "cache-only"を使用する場合は不要です。翻訳はCI内で事前生成されます。

Q: ビルドが失敗するのはなぜですか？ A: エラーメッセージを確認してください。一般的な原因：翻訳の欠落、無効なAPIキー、ネットワークの問題。

Q: 複数のLLMプロバイダーを使用できますか？ A: はい、models設定でロケールペアマッピングを使用できます。

Q: APIコストをかけずにテストするにはどうすればよいですか？ A: 開発環境でusePseudotranslator: trueを有効にしてください。

次のステップ