i18n.json設定

i18n.jsonは、Lingo.dev CLIおよび**Lingo.dev CI/CD統合**の動作を制御する標準設定ファイルです。

i18n.jsonは、言語設定、ファイル検索パターン、AI翻訳エンジン設定を個別のセクションに分離するスキーマ駆動型設定を実装しています。その結果、開発者は設定ファイルを読むだけで、ローカライゼーションワークフローがどのように動作するかを正確に理解できます。

このガイドは、Lingo.dev CLIがインストールされており、翻訳ワークフローを設定していることを前提としています。完了すると、i18n.jsonの完全な構造、設定オプション、および各セクションが翻訳動作をどのように制御するかを理解できます。

バージョン

versionフィールドは、設定スキーマのバージョンを指定します。

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10"
}

設定要素：

  • $schema — IDEの自動補完と検証のためのJSONスキーマ定義を指します。スキーマは、インラインドキュメントと型チェックを提供することで、設定エラーを早期に検出するのに役立ちます。
  • version — 移行互換性のための設定スキーマバージョン。

Lingo.dev CLIは、新しいスキーマバージョンがリリースされた際の自動設定移行にこのフィールドを使用します。

ロケール設定

localeセクションは、Lingo.dev CLIが処理する言語を定義します。

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

言語コードは、言語タグのBCP 47標準に従います。これは、ISO 639の言語コードと、ISO 3166-1のオプションの地域コードを組み込んでいます。例としては、en、en-US、es-ES、zh-Hansなどがあります。

Lingo.dev CLIは、リソースディレクトリ用のAndroidのen-rUS規則のようなプラットフォーム固有のロケール形式もサポートしています。サポートされているロケールコードの完全なリストを取得するには、次のコマンドを実行してください。

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

お使いのロケールコードがサポートされていない場合は、プルリクエストを開いて追加してください。

設定要素：

  • locale.source — 正式なコンテンツを含むファイルを識別するソース言語コード。すべての翻訳はソースからターゲットへ流れます。
  • locale.targets — ターゲット市場を表すターゲット言語コードの配列。各コードは、形式に応じて、個別のファイルまたはファイル内のセクションに対応します。

言語検証コマンド：

プロバイダー設定

providerセクションは、Lingo.dev CLIが使用するAI翻訳サービスを決定します。このセクションは任意であり、省略した場合はLingo.devのAI翻訳エンジンがデフォルトで使用されます。

Raw LLM APIアクセスの場合：

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "Your custom translation prompt with {source} and {target} placeholders"
  }
}

Lingo.dev Engineの場合：

Lingo.dev Engineを使用するには、providerセクションを完全に省略してください。エンジンは最適化研究とLingo.dev Engineの設定に基づいて、モデルとプロンプトを自動的に選択します。

設定要素：

  • provider.id — AI翻訳サービス識別子（例：「openai」または「anthropic」）。
  • provider.model — AI翻訳モデル名（例：OpenAIの場合は「gpt-4o-mini」、Anthropicの場合は「claude-3-haiku」）。
  • provider.prompt — 翻訳動作を導くシステムプロンプト。{source}および{target}プレースホルダーは、実行時に実際の言語コードに置き換えられます。

バケット設定

バケットは、ファイル検出パターンと処理ルールを定義します。各バケットは、特定のインクルード/エクスクルードパターンを持つファイル形式を表します。

{
  "buckets": {
    "json": {
      "include": ["locales/[locale].json", "app/[locale]/*.json"],
      "exclude": ["locales/[locale]/internal.json"],
      "lockedKeys": ["app/version", "config/apiUrl"],
      "injectLocale": ["settings/language"]
    },
    "markdown": {
      "include": ["docs/[locale]/*.md"],
      "exclude": ["docs/[locale]/drafts/*.md"]
    }
  }
}

設定要素：

  • buckets.[bucket-type] — 特定のファイル形式バケットの設定グループ。
    • buckets.[bucket-type].include — ファイル検出パターンの配列。文字列またはオブジェクトを含めることができます。
      • buckets.[bucket-type].include.[string] — [locale]プレースホルダーを含むシンプルなファイルパスパターン。
      • buckets.[bucket-type].include.[object] — 以下のプロパティを持つ高度なパターン設定：
        • path — [locale]プレースホルダーを含むファイルパスパターン。
        • delimiter — ロケールコードに使用する区切り文字。デフォルトは-（ダッシュ）で、_（アンダースコア）にオーバーライドできます。ロケール設定の区切り文字をオーバーライドします。
    • buckets.[bucket-type].exclude — 処理中にスキップするファイル除外パターンの配列。
    • buckets.[bucket-type].lockedKeys — 翻訳すべきでないキーの配列。ネストされたキーの区切り文字としてフォワードスラッシュ/を使用します。複数のキーにマッチさせるにはアスタリスク*を使用します。
    • buckets.[bucket-type].ignoredKeys — 翻訳中に無視すべきキーの配列。ネストされたキーの区切り文字としてフォワードスラッシュ/を使用します。複数のキーにマッチさせるにはアスタリスク*を使用します。
    • buckets.[bucket-type].injectLocale — ロケールコードを自動的に挿入すべきキーの配列。ネストされたキーの区切り文字としてフォワードスラッシュ/を使用します。複数のキーにマッチさせるにはアスタリスク*を使用します。

基本的なパターン構造

インクルードパターンは、特殊な[locale]プレースホルダーを使用したglob形式の構文を使用します。

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

除外パターンは、インクルードパターン内の特定のファイルの処理を防ぎます。

高度なパターンオプション

カスタムロケール区切り文字により、異なるファイル名形式に対応できます。

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

利用可能な区切り文字:

  • - (ダッシュ): en-US.json
  • _ (アンダースコア): en_US.json

ヒント: この設定はファイル名で使用される区切り文字を制御するため、異なるプロジェクトが異なる区切り文字規則を持つモノレポ設定で使用できます。

サポートされているバケットタイプ

Lingo.dev CLIは、さまざまなファイル形式に対して以下のバケットタイプをサポートしています。

  • android — Android XMLリソースファイル
  • csv — ターゲット言語ごとに個別のファイルを持つCSVファイル
  • flutter — Flutter ARBファイル
  • html — ターゲット言語ごとに個別のファイルを持つHTMLファイル
  • json — ターゲット言語ごとに個別のファイルを持つJSONファイル
  • markdown — ターゲット言語ごとに個別のファイルを持つMarkdownファイル
  • mdx — ターゲット言語ごとに個別のファイルを持つMDXファイル
  • xcode-strings — レガシーXcode .stringsファイル
  • xcode-stringsdict — 複数形化用のXcode .stringsdictファイル
  • xcode-xcstrings — Xcode stringsカタログファイル
  • yaml — ターゲット言語ごとに個別のファイルを持つYAMLファイル
  • yaml-root-key — ロケールベースのルートキーを持つYAMLファイル
  • properties — Java .propertiesファイル
  • po — GNU gettext .poファイル
  • xml — ターゲット言語ごとに個別のファイルを持つ汎用XMLファイル
  • php — PHP配列ファイル
  • vue-json — Vue.js i18n JSONファイル
  • typescript — ターゲット言語ごとに個別のファイルを持つTypeScriptファイル

設定例

基本設定

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

モノレポ設定

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": "1.10",
  "locale": {
    "source": "en-US",
    "targets": ["es-ES", "fr-FR"]
  },
  "buckets": {
    "json": {
      "include": ["apps/web/locales/[locale].json"]
    },
    "mdx": {
      "include": ["packages/docs/content/[locale]/*.mdx"]
    },
    "xcode-xcstrings": {
      "include": ["ios/Localizable.xcstrings"]
    },
    "android": {
      "include": ["android/values-[locale]/strings.xml"]
    }
  }
}

バージョン移行

i18n.jsonはスマートなバージョン移行を実装しており、すべてのユーザー設定を保持しながら、設定を新しいスキーマバージョンに自動的に更新します。

Lingo.dev CLIが古い設定バージョンを検出すると、次の処理を実行します。

  1. 現在のi18n.jsonファイルのバックアップを作成
  2. 最新のスキーマバージョンに設定を移行
  3. カスタムプロバイダー、バケット設定、ロックされたキーを含むすべての設定を保持
  4. 現在のスキーマに合わせてバージョンフィールドを更新

移行動作:

設定ファイルを読み取るCLI操作中に移行が自動的にトリガーされます。手動での介入は不要で、翻訳ワークフローは中断することなく継続されます。

この移行システムにより、i18n.jsonの設定はLingo.dev CLIのアップデートとの互換性を維持しながら、既存プロジェクトとの下位互換性も保たれます。