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.8
}

設定要素：

  • $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  # 利用可能なソース言語
npx lingo.dev@latest show locale targets  # 利用可能なターゲット言語

あなたのロケールコードがサポートされていない場合は、追加するためにプルリクエストを開いてください！

設定要素：

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

言語検証コマンド：

プロバイダー設定

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

生のLLM APIアクセスの場合：

{
  "provider": {
    "id": "openai",
    "model": "gpt-4o-mini",
    "prompt": "カスタム翻訳プロンプト（{source}と{target}のプレースホルダーを含む）"
  }
}

Lingo.devエンジンの場合：

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

設定要素：

  • 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] プレースホルダーを使用します：

  • 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ストリングカタログファイル
  • 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.8,
  "locale": {
    "source": "en",
    "targets": ["es", "fr", "ja"]
  },
  "buckets": {
    "json": {
      "include": ["locales/[locale].json"]
    }
  }
}

モノレポ設定

{
  "$schema": "https://lingo.dev/schema/i18n.json",
  "version": 1.8,
  "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の更新との互換性を確保します。