i18n.json 設定

i18n.json は、Lingo.dev CLI と CI/CD integrations を制御する設定ファイルです。翻訳対象の言語、翻訳可能なコンテンツの場所、使用する翻訳バックエンドを定義します。

最小構成の例#

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

$schema フィールドは、IDE での自動補完とバリデーションを有効にします。version フィールドは、スキーマのバージョンを管理し、自動移行との互換性を保ちます。

ロケール#

locale セクションでは、ソース言語とターゲット言語を定義します。

json

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  }
}

フィールド	説明
`locale.source`	ソースコンテンツが書かれている言語です。すべての翻訳はこのロケールを起点に行われます。
`locale.targets`	ターゲット言語の配列です。各ターゲットごとに、bucket 形式に応じた別々のファイル（またはセクション）が生成されます。

言語コードは BCP 47 標準に準拠しています。en、en-US、es-ES、zh-Hans に加え、Android の en-rUS のようなプラットフォーム固有の形式にも対応しています。

利用可能なロケールコードを一覧表示するには、次を実行します。

bash

npx lingo.dev@latest show locale sources   # Available source languages
npx lingo.dev@latest show locale targets   # Available target languages

Buckets#

Buckets では、ファイル検出パターンと処理ルールを定義します。各 bucket キーはファイル形式を表し、その値で対象ファイルと除外ファイルを設定します。

json

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "exclude": ["locales/[locale]/internal.json"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  }
}

フィールド	説明
`include`	`[locale]` プレースホルダーを含むファイルパターンの配列です。glob ワイルドカード（`*`）に対応しています。
`exclude`	任意。処理時にスキップするパターンの配列です。
`lockedKeys`	任意。値が翻訳されず、ソースからそのままコピーされるキーです。Key Locking を参照してください。
`ignoredKeys`	任意。翻訳対象から完全に除外されるキーです。ターゲットファイルには出力されません。Key Ignoring を参照してください。
`preservedKeys`	任意。最初にソースから一度だけ初期化され、その後は自動更新から保護されるキーです。Key Preserving を参照してください。
`injectLocale`	任意。ターゲットのロケールコードが自動で挿入されるキーです。

対象パターン#

対象パターンでは [locale] プレースホルダーを使用します。実行時に、設定済みのロケールコードへ展開されます。

locales/[locale].json → locales/en.json、locales/es.json
docs/[locale]/*.md → docs/en/*.md、docs/es/*.md

再帰的な glob パターン（**/*.json）には対応していません。代わりに、明示的なディレクトリパスを使用してください。

カスタムロケール区切り文字#

デフォルトでは、ファイル名内のロケールコードはダッシュ（-）区切りで扱われます: en-US.json。代わりにアンダースコアを使うには、delimiter フィールドを持つオブジェクトを渡します。

json

{
  "include": [
    "standard/[locale].json",
    { "path": "legacy/[locale].json", "delimiter": "_" }
  ]
}

これにより、legacy/en-US.json ではなく legacy/en_US.json が生成されます。

キーパス記法#

lockedKeys、ignoredKeys、preservedKeys の各配列では、ネストされたキーにスラッシュ（/）記法を使用し、ワイルドカードにはアスタリスク（*）を使用します。

json

{
  "lockedKeys": ["brand/name", "config/*"]
}

対応している bucket タイプの一覧は、Supported Formats を参照してください。

プロバイダー#

provider セクションでは、翻訳に使用する LLM プロバイダーを直接設定します。このセクションは任意です。省略した場合、CLI は Lingo.dev 上のローカライゼーションエンジンを使用します。

json

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Translate the provided text from {source} to {target}."
  }
}

フィールド	説明
`provider.id`	プロバイダー識別子: `openai`、`anthropic`、`google`、`mistral`、`openrouter`、または `ollama`。
`provider.model`	プロバイダー側のモデル名です（例: `gpt-4o-mini`、`claude-3-haiku`）。
`provider.prompt`	システムプロンプトです。`{source}` と `{target}` は実行時にロケールコードへ置き換えられます。
`provider.baseUrl`	任意。カスタム API エンドポイントです（Ollama では必須: `http://localhost:11434`）。

エンジン接続#

翻訳を特定のローカライゼーションエンジン経由で処理するには、engineId フィールドを追加します。

json

{
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

engineId が設定されている場合、すべての翻訳リクエストにエンジンのブランドボイス、glossary、instructions、model configuration が自動で適用されます。これを省略し、LINGO_API_KEY が設定されている場合は、CLI が組織内のデフォルトエンジンを使用します。

詳しいセットアップ手順は、Connect Your Engine を参照してください。

環境変数#

変数	必須	説明
`LINGO_API_KEY`	Lingo.dev Engine 用	Lingo.dev API キーです。
`LINGO_API_URL`	No	カスタム API ベース URL（セルフホスト環境またはステージング環境向け）。
`OPENAI_API_KEY`	OpenAI プロバイダー用	OpenAI API キー。
`ANTHROPIC_API_KEY`	Anthropic プロバイダー用	Anthropic API キー。
`GOOGLE_API_KEY`	Google プロバイダー用	Google API キー。
`MISTRAL_API_KEY`	Mistral プロバイダー用	Mistral API キー。
`OPENROUTER_API_KEY`	OpenRouter プロバイダー用	OpenRouter API キー。

完全な例#

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["brand/name", "brand/tagline"],
      "ignoredKeys": ["internal/*"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  },
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

バージョン移行#

CLI は古い i18n.json 設定を最新のスキーマバージョンへ自動的に移行します。現在のファイルをバックアップしたうえでスキーマを更新し、すべての設定を保持します。手動対応は不要です。

次のステップ#

Supported Formats

すべての bucket タイプとその設定

i18n.lock

lockfile が翻訳状態を追跡する仕組み

Connect Your Engine

翻訳をローカライゼーションエンジン経由で処理

Setup

CLI をインストールして使い始める

最小構成の例#

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

ロケール#

locale セクションでは、ソース言語とターゲット言語を定義します。

json

{
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  }
}

フィールド	説明
`locale.source`	ソースコンテンツが書かれている言語です。すべての翻訳はこのロケールを起点に行われます。
`locale.targets`	ターゲット言語の配列です。各ターゲットごとに、bucket 形式に応じた別々のファイル（またはセクション）が生成されます。

利用可能なロケールコードを一覧表示するには、次を実行します。

bash

npx lingo.dev@latest show locale sources   # Available source languages
npx lingo.dev@latest show locale targets   # Available target languages

Buckets#

json

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "exclude": ["locales/[locale]/internal.json"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  }
}

フィールド	説明
`include`	`[locale]` プレースホルダーを含むファイルパターンの配列です。glob ワイルドカード（`*`）に対応しています。
`exclude`	任意。処理時にスキップするパターンの配列です。
`lockedKeys`	任意。値が翻訳されず、ソースからそのままコピーされるキーです。Key Locking を参照してください。
`ignoredKeys`	任意。翻訳対象から完全に除外されるキーです。ターゲットファイルには出力されません。Key Ignoring を参照してください。
`preservedKeys`	任意。最初にソースから一度だけ初期化され、その後は自動更新から保護されるキーです。Key Preserving を参照してください。
`injectLocale`	任意。ターゲットのロケールコードが自動で挿入されるキーです。

対象パターン#

対象パターンでは [locale] プレースホルダーを使用します。実行時に、設定済みのロケールコードへ展開されます。

locales/[locale].json → locales/en.json、locales/es.json
docs/[locale]/*.md → docs/en/*.md、docs/es/*.md

再帰的な glob パターン（**/*.json）には対応していません。代わりに、明示的なディレクトリパスを使用してください。

カスタムロケール区切り文字#

json

{
  "include": [
    "standard/[locale].json",
    { "path": "legacy/[locale].json", "delimiter": "_" }
  ]
}

これにより、legacy/en-US.json ではなく legacy/en_US.json が生成されます。

キーパス記法#

json

{
  "lockedKeys": ["brand/name", "config/*"]
}

対応している bucket タイプの一覧は、Supported Formats を参照してください。

プロバイダー#

json

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Translate the provided text from {source} to {target}."
  }
}

フィールド	説明
`provider.id`	プロバイダー識別子: `openai`、`anthropic`、`google`、`mistral`、`openrouter`、または `ollama`。
`provider.model`	プロバイダー側のモデル名です（例: `gpt-4o-mini`、`claude-3-haiku`）。
`provider.prompt`	システムプロンプトです。`{source}` と `{target}` は実行時にロケールコードへ置き換えられます。
`provider.baseUrl`	任意。カスタム API エンドポイントです（Ollama では必須: `http://localhost:11434`）。

エンジン接続#

翻訳を特定のローカライゼーションエンジン経由で処理するには、engineId フィールドを追加します。

json

{
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

詳しいセットアップ手順は、Connect Your Engine を参照してください。

環境変数#

変数	必須	説明
`LINGO_API_KEY`	Lingo.dev Engine 用	Lingo.dev API キーです。
`LINGO_API_URL`	No	カスタム API ベース URL（セルフホスト環境またはステージング環境向け）。
`OPENAI_API_KEY`	OpenAI プロバイダー用	OpenAI API キー。
`ANTHROPIC_API_KEY`	Anthropic プロバイダー用	Anthropic API キー。
`GOOGLE_API_KEY`	Google プロバイダー用	Google API キー。
`MISTRAL_API_KEY`	Mistral プロバイダー用	Mistral API キー。
`OPENROUTER_API_KEY`	OpenRouter プロバイダー用	OpenRouter API キー。

完全な例#

json

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.15",
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "de", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"],
      "lockedKeys": ["brand/name", "brand/tagline"],
      "ignoredKeys": ["internal/*"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"]
    }
  },
  "engineId": "eng_SxjMwMsfOIsvV1wh"
}

バージョン移行#

次のステップ#

Supported Formats

すべての bucket タイプとその設定

i18n.lock

lockfile が翻訳状態を追跡する仕組み

Connect Your Engine

翻訳をローカライゼーションエンジン経由で処理

Setup

CLI をインストールして使い始める