設定リファレンス

アルファ

Lingo.dev Compiler は現在アルファ版です。動作は安定しておらず、本番環境での利用は推奨されません。また、API はリリースごとに変更される可能性があります。

Lingo.dev Compiler の設定オブジェクトは、React アプリケーションをビルド時にどのように翻訳するかを制御します。このページでは、利用可能なすべてのオプションを、型、デフォルト値、使用例とあわせて紹介します。

コアオプション#

オプション	型	デフォルト	説明
`sourceRoot`	`string`	`"src"`	翻訳対象のコンポーネントが含まれるディレクトリ。プロジェクトルートからの相対パスです。
`lingoDir`	`string`	`".lingo"`	翻訳メタデータとキャッシュファイルを保存するディレクトリ。
`sourceLocale`	`string`	必須	ソースコンテンツの言語コード（例: `"en"`）。
`targetLocales`	`string[]`	必須	ターゲット言語コードの配列（例: `["es", "de", "fr"]`）。
`useDirective`	`boolean`	`false`	`true` の場合は、`'use i18n'` ディレクティブが付いたファイルだけが翻訳対象になります。`false` の場合は、`sourceRoot` 配下のすべてのファイルが翻訳されます。
`models`	`string \| object`	`"lingo.dev"`	翻訳プロバイダーの設定です。文字列を指定すると、すべてのロケールペアに共通のデフォルト値として使われます。オブジェクトを指定すると、ロケールペアごとに使用するプロバイダーを割り当てられます。
`prompt`	`string`	`undefined`	翻訳用 LLM に渡すカスタムシステムプロンプトです。`{SOURCE_LOCALE}` と `{TARGET_LOCALE}` のプレースホルダーをサポートします。
`buildMode`	`"translate" \| "cache-only"`	`"translate"`	Compiler が新しい翻訳を生成するか、キャッシュ済みの翻訳だけを使うかを制御します。

開発オプション#

dev キー配下のオプションでは、開発時の挙動を制御できます。

オプション	型	デフォルト	説明
`dev.usePseudotranslator`	`boolean`	`false`	LLM を呼び出す代わりに、すぐに疑似翻訳（例: `[!!! Welcome !!!]`）を生成します。API キーは不要です。
`dev.translationServerStartPort`	`number`	`60000`	ローカル翻訳サーバーの開始ポートです。Compiler は 60000〜60099 の範囲から利用可能なポートを自動で見つけます。
`dev.translationServerUrl`	`string`	`undefined`	翻訳サーバーの URL を上書きします。カスタム構成やリモート翻訳サーバーを使う場合に便利です。

ロケール保持#

localePersistence 配下のオプションでは、ユーザーが選択したロケールをどのように保存・取得するかを制御します。

オプション	型	デフォルト	説明
`localePersistence.type`	`string`	`"cookie"`	保持の仕組みです。現在は `"cookie"` をサポートしています。
`localePersistence.config.name`	`string`	`"locale"`	ロケールの保存に使用する Cookie 名です。
`localePersistence.config.maxAge`	`number`	`31536000`	Cookie の max-age を秒単位で指定します（デフォルトは1年）。

カスタムの保持ロジック（localStorage、URL ベース、ヘッダー）については、カスタムロケールリゾルバーをご覧ください。

複数形処理#

pluralization 配下のオプションでは、自動的な複数形の検出と生成を制御します。

オプション	型	デフォルト	説明
`pluralization.enabled`	`boolean`	`true`	自動複数形検出の有効・無効を切り替えます。
`pluralization.model`	`string`	`"groq:llama-3.1-8b-instant"`	ソーステキスト内の複数形を検出するために使う LLM モデルです。検出は翻訳よりもシンプルなタスクのため、より小さく高速なモデルを推奨します。

複数形検出の仕組みについて詳しくは、自動複数形処理をご覧ください。

環境変数#

環境変数を使うと、設定を上書きしたり補完したりできます。

変数	必要になる場合	説明
`LINGO_BUILD_MODE`	任意	`buildMode` 設定オプションを上書きします。`"translate"` または `"cache-only"` を設定してください。
`LINGODOTDEV_API_KEY`	`"lingo.dev"` モデルを使用する場合	Lingo.dev ローカライゼーションエンジンの API キーです。`npx @lingo.dev/cli login` から取得できます。
`OPENAI_API_KEY`	`"openai:*"` モデルを使用する場合	OpenAI API キー。
`ANTHROPIC_API_KEY`	`"anthropic:*"` モデルを使用する場合	Anthropic API キー。
`GOOGLE_API_KEY`	`"google:*"` モデルを使用する場合	Google AI API キー。
`GROQ_API_KEY`	`"groq:*"` モデルを使用する場合	Groq API キー。
`MISTRAL_API_KEY`	`"mistral:*"` モデルを使用する場合	Mistral API キー。
`OPENROUTER_API_KEY`	`"openrouter:*"` モデルを使用する場合	OpenRouter API キー。

完全な例#

// next.config.ts
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, {
    sourceRoot: "./app",
    lingoDir: ".lingo",
    sourceLocale: "en",
    targetLocales: ["es", "de", "fr", "ja"],
    useDirective: false,
    models: {
      "*:*": "lingo.dev",
      "*:ja": "anthropic:claude-3-5-sonnet",
    },
    prompt: "Translate UI text from {SOURCE_LOCALE} to {TARGET_LOCALE}. Keep it concise.",
    buildMode: "translate",
    dev: {
      usePseudotranslator: true,
      translationServerStartPort: 60000,
    },
    localePersistence: {
      type: "cookie",
      config: {
        name: "locale",
        maxAge: 31536000,
      },
    },
    pluralization: {
      enabled: true,
      model: "groq:llama-3.1-8b-instant",
    },
  });
}

次のステップ#

翻訳プロバイダー

サポートされているすべての LLM プロバイダーとロケールペアのマッピング