Intlayer 設定ドキュメント

概要

Intlayerの設定ファイルは、国際化、ミドルウェア、コンテンツ処理など、プラグインのさまざまな側面をカスタマイズすることを可能にします。本ドキュメントでは、設定内の各プロパティについて詳細に説明します。

設定ファイルの対応形式

IntlayerはJSON、JS、MJS、TSの設定ファイル形式をサポートしています：

• intlayer.config.ts
• intlayer.config.js
• intlayer.config.json
• intlayer.config.cjs
• intlayer.config.mjs
• .intlayerrc

設定ファイルの例

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH], // 対応するロケールのリスト  },  content: {    autoFill: "./{{fileName}}.content.json", // 自動入力用のコンテンツファイルパス    contentDir: ["src", "../ui-library"], // コンテンツディレクトリの配列  },  middleware: {    noPrefix: false, // プレフィックスなしの設定  },  editor: {    applicationURL: "https://example.com", // エディタのアプリケーションURL  },  ai: {    apiKey: process.env.OPENAI_API_KEY, // AI APIキー    applicationContext: "This is a test application", // アプリケーションコンテキスト  },  build: {    importMode: "dynamic", // インポートモードの設定  },};export default config;

設定リファレンス

以下のセクションでは、Intlayerで利用可能なさまざまな設定項目について説明します。

国際化設定

国際化に関連する設定を定義します。利用可能なロケールやアプリケーションのデフォルトロケールを含みます。

プロパティ

• locales:

  • 型: string[]
  • デフォルト: ['en']
  • 説明: アプリケーションでサポートされているロケールのリスト。
  • 例: ['en', 'fr', 'es']
• requiredLocales:
  • 型: string[]
  • デフォルト: []
  • 説明: アプリケーションで必須とされるロケールのリスト。
  • 例: []
  • 注意: 空の場合、strict モードではすべてのロケールが必須となります。
  • 注意: 必須のロケールは locales フィールドにも定義されていることを確認してください。

• strictMode:

  • 型: string
  • デフォルト: inclusive
  • 説明: TypeScriptを使用して国際化コンテンツの強力な実装を保証します。
  • 注意: "strict" に設定すると、翻訳関数 t は宣言されたすべてのロケールが定義されていることを要求します。ロケールが1つでも欠けているか、設定に宣言されていないロケールがある場合はエラーをスローします。
  • 注意: "inclusive" に設定すると、翻訳関数 t は宣言されたすべてのロケールが定義されていることを要求します。ロケールが1つでも欠けている場合は警告を出します。ただし、設定に宣言されていないが存在するロケールは許容します。
  • 注意: "loose" に設定すると、翻訳関数 t は存在する任意のロケールを受け入れます。

• defaultLocale:

  • タイプ: string
  • デフォルト: 'en'
  • 説明: 要求されたロケールが見つからない場合にフォールバックとして使用されるデフォルトのロケール。
  • 例: 'en'
  • 注意: URL、クッキー、またはヘッダーでロケールが指定されていない場合に、どのロケールを使用するかを決定するために使用されます。

エディター設定

統合エディターに関連する設定を定義します。サーバーポートやアクティブ状態などが含まれます。

プロパティ

• applicationURL:

  • タイプ: string
  • デフォルト: http://localhost:3000
  • 説明: アプリケーションのURL。セキュリティ上の理由からエディターのオリジンを制限するために使用されます。
  • 例:
    • 'http://localhost:3000'
    • 'https://example.com'
    • process.env.INTLAYER_EDITOR_URL
  • 注意: アプリケーションのURL。セキュリティ上の理由からエディターのオリジンを制限するために使用されます。'*'に設定すると、どのオリジンからでもエディターにアクセス可能になります。

• port:

  • タイプ: number
  • デフォルト: 8000
  • 説明: ビジュアルエディターサーバーが使用するポート。

• editorURL:

  • タイプ: string
  • デフォルト: 'http://localhost:8000'
  • 説明: エディターサーバーのURL。セキュリティ上の理由からエディターのオリジンを制限するために使用されます。
    • 'http://localhost:3000'
    • 'https://example.com'
    • process.env.INTLAYER_EDITOR_URL
  • 注: アプリケーションからアクセスするエディターサーバーのURL。セキュリティ上の理由から、アプリケーションとやり取りできるオリジンを制限するために使用されます。'*'に設定すると、エディターは任意のオリジンからアクセス可能になります。ポートを変更した場合やエディターが異なるドメインでホストされている場合に設定する必要があります。

• cmsURL:

  • 型: string
  • デフォルト: 'https://intlayer.org'
  • 説明: Intlayer CMSのURL。
  • 例: 'https://intlayer.org'
  • 注: Intlayer CMSのURL。

• backendURL:

  • 型: string
  • デフォルト: https://back.intlayer.org
  • 説明: バックエンドサーバーのURL。
  • 例: http://localhost:4000

• enabled:

  • 型: boolean
  • デフォルト: true
  • 説明: アプリケーションがビジュアルエディターと連携するかどうかを示します。
  • 例: process.env.NODE_ENV !== 'production'
  • 注意: true の場合、エディターはアプリケーションと連携可能です。false の場合、エディターはアプリケーションと連携できません。いずれの場合も、エディターはビジュアルエディターによってのみ有効化されます。特定の環境でエディターを無効にすることは、セキュリティを強化する方法の一つです。

• clientId:

  • タイプ: string | undefined
  • デフォルト: undefined
  • 説明: clientId と clientSecret は、intlayer パッケージが oAuth2 認証を使用してバックエンドと認証するために使用されます。アクセストークンは、プロジェクトに関連するユーザーを認証するために使用されます。アクセストークンを取得するには、https://intlayer.org/dashboard/project にアクセスしてアカウントを作成してください。
  • 例: true
  • 注意: 重要: clientId と clientSecret は秘密にしておく必要があり、公開しないでください。環境変数などの安全な場所に保管することをお勧めします。

• clientSecret:

  • タイプ: string | undefined
  • デフォルト: undefined
  • 説明: clientId と clientSecret は、intlayer パッケージが oAuth2 認証を使用してバックエンドと認証するために使用されます。アクセストークンは、プロジェクトに関連するユーザーを認証するために使用されます。アクセストークンを取得するには、https://intlayer.org/dashboard/project にアクセスしてアカウントを作成してください。
  • 例: true
  • 注意: 重要: clientId と clientSecret は秘密にしておく必要があり、公開しないでください。環境変数などの安全な場所に保管することを推奨します。

• dictionaryPriorityStrategy:

  • タイプ: string
  • デフォルト: 'local_first'
  • 説明: ローカル辞書と遠隔辞書の両方が存在する場合に、どちらを優先するかの戦略です。'distant_first' に設定すると、アプリケーションは遠隔辞書をローカル辞書より優先します。'local_first' に設定すると、アプリケーションはローカル辞書を遠隔辞書より優先します。
  • 例: 'distant_first'

• liveSync:

  • 型: boolean
  • デフォルト: false
  • 説明: CMS / ビジュアルエディター / バックエンドで変更が検出された際に、アプリケーションサーバーがコンテンツをホットリロードするかどうかを示します。
  • 例: true
  • 注意: 例えば、新しい辞書が追加または更新された場合、アプリケーションはページに表示するコンテンツを更新します。
  • 注記: ライブ同期はアプリケーションのコンテンツを別のサーバーに外部化する必要があります。これはアプリケーションのパフォーマンスにわずかな影響を与える可能性があります。これを制限するために、アプリケーションとライブ同期サーバーを同じマシン上にホストすることを推奨します。また、ライブ同期と optimize の組み合わせはライブ同期サーバーへのリクエスト数を大幅に増加させる可能性があります。インフラストラクチャに応じて、両方のオプションおよびその組み合わせをテストすることを推奨します。

• liveSyncPort:

  • タイプ: number
  • デフォルト: 4000
  • 説明: ライブ同期サーバーのポート番号。
  • 例: 4000
  • 注記: ライブ同期サーバーのポート番号。

• liveSyncURL:

  • タイプ: string
  • デフォルト: 'http://localhost:{liveSyncPort}'
  • 説明: ライブシンクサーバーのURL。
  • 例: 'https://example.com'
  • 注意: デフォルトではlocalhostを指しますが、リモートのライブシンクサーバーの場合は任意のURLに変更可能です。

ミドルウェア設定

ミドルウェアの動作を制御する設定で、アプリケーションがクッキー、ヘッダー、ロケール管理のためのURLプレフィックスをどのように扱うかを含みます。

プロパティ

• headerName:

  • 型: string
  • デフォルト: 'x-intlayer-locale'
  • 説明: ロケールを判定するために使用されるHTTPヘッダーの名前。
  • 例: 'x-custom-locale'
  • 注意: APIベースのロケール判定に便利です。

• cookieName:

  • 型: string
  • デフォルト: 'intlayer-locale'
  • 説明: ロケールを保存するために使用されるクッキーの名前。
  • 例: 'custom-locale'
  • 注意: セッション間でロケールを保持するために使用されます。

• prefixDefault:

  • タイプ: boolean
  • デフォルト: false
  • 説明: デフォルトのロケールをURLに含めるかどうか。
  • 例: true
  • 注意:
    • true かつ defaultLocale = 'en' の場合: パスは /en/dashboard または /fr/dashboard
    • false かつ defaultLocale = 'en' の場合: パスは /dashboard または /fr/dashboard
• basePath:
  • タイプ: string
  • デフォルト: ''
  • 説明: アプリケーションのURLのベースパス。
  • 例: '/my-app'
  • 注意:
    • アプリケーションが https://example.com/my-app にホストされている場合
    • ベースパスは '/my-app'
    • URLは https://example.com/my-app/en となります

• serverSetCookie:

  • タイプ: string
  • デフォルト: 'always'
  • 説明: サーバー側でロケールクッキーを設定するルール。
  • オプション: 'always', 'never'
  • 例: 'never'
  • 注意: ロケールクッキーをすべてのリクエストで設定するか、まったく設定しないかを制御します。

• noPrefix:

  • タイプ: boolean
  • デフォルト: false
  • 説明: URLからロケールのプレフィックスを省略するかどうか。
  • 例: true
  • 注意:
    • true の場合: URLにプレフィックスはありません
    • false の場合: URLにプレフィックスがあります
    • basePath = '/my-app' の例:
      • noPrefix = false の場合: URLは https://example.com/my-app/en
      • noPrefix = true の場合: URLは https://example.com

• detectLocaleOnPrefetchNoPrefix:

  • タイプ: boolean
  • デフォルト: false
  • 説明: Next.jsのプリフェッチリクエスト時にロケール検出を行うかどうかを制御します。
  • 例: true
  • 注意: この設定はNext.jsのロケールプリフェッチの動作に影響します：
    • 例のシナリオ:
      • ユーザーのブラウザ言語が 'fr'
      • 現在のページが /fr/about
      • リンクが /about をプリフェッチする
    • detectLocaleOnPrefetchNoPrefix: true の場合:
      • プリフェッチはブラウザから 'fr' ロケールを検出
      • プリフェッチを /fr/about にリダイレクト
    • detectLocaleOnPrefetchNoPrefix: false（デフォルト）の場合:
      • プリフェッチはデフォルトロケールを使用
      • プリフェッチを /en/about にリダイレクト（'en' がデフォルトの場合）
    • true を使うべき場合:
      • アプリがローカライズされていない内部リンクを使用している場合（例：<a href="/about">）
      • 通常のリクエストとプリフェッチリクエスト間で一貫したロケール検出動作を望む場合
    • false（デフォルト）を使用する場合：
      • アプリがロケール接頭辞付きリンクを使用している場合（例：<a href="/fr/about">）
      • プリフェッチのパフォーマンスを最適化したい場合
      • リダイレクトループの可能性を回避したい場合

コンテンツ設定

アプリケーション内のコンテンツ処理に関連する設定。ディレクトリ名、ファイル拡張子、および派生設定を含みます。

プロパティ

• autoFill:

  • 型: boolean | string | { [key in Locales]?: string }
  • デフォルト: undefined
  • 説明: コンテンツをAIを使って自動的にどのように埋めるかを示します。intlayer.config.tsファイルでグローバルに宣言することができます。
  • 例: true
  • 例: './{{fileName}}.content.json'
  • 例: { fr: './{{fileName}}.fr.content.json', es: './{{fileName}}.es.content.json' }
  • 注意: 自動埋め設定は以下のいずれかです:
    • boolean: すべてのロケールで自動埋めを有効にする
    • string: 単一ファイルのパスまたは変数を含むテンプレート
    • object: ロケールごとのファイルパス

• watch:

  • 型: boolean
  • デフォルト: process.env.NODE_ENV === 'development'
  • 説明: Intlayerがアプリ内のコンテンツ宣言ファイルの変更を監視し、関連する辞書を再構築するかどうかを示します。

• fileExtensions:

  • 型: string[]
  • デフォルト: ['.content.ts', '.content.js', '.content.cjs', '.content.mjs', '.content.json', '.content.tsx', '.content.jsx']
  • 説明: 辞書を構築する際に探すファイル拡張子。
  • 例: ['.data.ts', '.data.js', '.data.json']
  • 注意: ファイル拡張子をカスタマイズすることで競合を回避できます。

• baseDir:

  • タイプ: string
  • デフォルト: process.cwd()
  • 説明: プロジェクトのベースディレクトリ。
  • 例: '/path/to/project'
  • 注意: これはすべてのIntlayer関連ディレクトリを解決するために使用されます。

• dictionaryOutput:

  • タイプ: string[]
  • デフォルト: ['intlayer']
  • 説明: 使用する辞書出力のタイプ。例：'intlayer' または 'i18next'。

• contentDir:

  • タイプ: string[]
  • デフォルト: ['.']
  • 例: ['src', '../../ui-library', require.resolve("@my-package/content")]
  • 説明: コンテンツが保存されているディレクトリパス。

• dictionariesDir:

  • タイプ: string
  • デフォルト: '.intlayer/dictionaries'
  • 説明: 中間結果または出力結果を保存するためのディレクトリパス。

• moduleAugmentationDir:

  • タイプ: string
  • デフォルト: '.intlayer/types'
  • 説明: モジュール拡張用のディレクトリで、IDEの補完や型チェックを向上させるためのもの。
  • 例: 'intlayer-types'
  • 注意: これを必ず tsconfig.json に含めてください。

• unmergedDictionariesDir:

  • タイプ: string
  • デフォルト: '.intlayer/unmerged_dictionary'
  • 説明: マージされていない辞書を保存するためのディレクトリ。
  • 例: 'translations'

• dictionariesDir:

  • タイプ: string
  • デフォルト: '.intlayer/dictionary'
  • 説明: ローカリゼーション辞書を格納するディレクトリ。
  • 例: 'translations'

• i18nextResourcesDir:

  • タイプ: string
  • デフォルト: 'i18next_dictionary'
  • 説明: i18n辞書を格納するディレクトリ。
  • 例: 'translations'
  • 注意: このディレクトリがi18nextの出力タイプ用に設定されていることを確認してください。

• typesDir:

  • タイプ: string
  • デフォルト: 'types'
  • 説明: 辞書の型を格納するディレクトリ。
  • 例: 'intlayer-types'

• mainDir:

  • タイプ: string
  • デフォルト: 'main'
  • 説明: メインアプリケーションファイルが格納されるディレクトリ。
  • 例: 'intlayer-main'

• excludedPath:

  • タイプ: string[]
  • デフォルト: ['node_modules']
  • 説明: コンテンツ検索から除外するディレクトリ。
  • 注意: この設定はまだ使用されていませんが、将来的に実装予定です。

ロガー設定

ロガーを制御する設定で、使用するプレフィックスも含みます。

プロパティ

• mode:

  • タイプ: string
  • デフォルト: default
  • 説明: ロガーのモードを示します。
  • オプション: default, verbose, disabled
  • 例: default
  • 注意: ロガーのモードです。verboseモードはより多くの情報をログに記録しますが、デバッグ目的で使用されます。disabledモードはロガーを無効にします。

• prefix:

  • タイプ: string
  • デフォルト: '[intlayer] '
  • 説明: ロガーのプレフィックス。
  • 例: '[my custom prefix] '
  • Note: ロガーのプレフィックス。

AI構成

IntlayerのAI機能を制御する設定で、プロバイダー、モデル、APIキーを含みます。

この設定は、アクセスキーを使用してIntlayerダッシュボードに登録している場合はオプションです。Intlayerは、最も効率的でコスト効果の高いAIソリューションを自動的に管理します。デフォルトのオプションを使用することで、Intlayerが継続的に最適なモデルを使用するように更新されるため、長期的な保守性が向上します。

独自のAPIキーや特定のモデルを使用したい場合は、カスタムAI構成を定義できます。 このAI構成は、Intlayer環境全体でグローバルに使用されます。CLIコマンドはこれらの設定をコマンド（例：fill）のデフォルトとして使用し、SDK、ビジュアルエディター、CMSでも同様です。特定のユースケースに対しては、コマンドパラメータを使ってこれらのデフォルト値を上書きすることができます。

Intlayerは、柔軟性と選択肢を高めるために複数のAIプロバイダーをサポートしています。現在サポートされているプロバイダーは以下の通りです：

• OpenAI（デフォルト）
• Anthropic Claude
• Mistral AI
• DeepSeek
• Google Gemini
• Meta Llama

プロパティ

• provider:

  • タイプ: string
  • デフォルト: 'openai'
  • 説明: IntlayerのAI機能に使用するプロバイダー。
  • オプション: 'openai', 'anthropic', 'mistral', 'deepseek', 'gemini'
  • 例: 'anthropic'
  • 注意: プロバイダーによっては異なるAPIキーが必要であり、料金体系も異なる場合があります。

• model:

  • タイプ: string
  • デフォルト: なし
  • 説明: IntlayerのAI機能で使用するモデル。
  • 例: 'gpt-4o-2024-11-20'
  • 注意: 使用するモデルはプロバイダーによって異なります。

• temperature:

  • タイプ: number
  • デフォルト: なし
  • 説明: AIの応答のランダム性を制御する温度パラメータ。
  • 例: 0.1
  • 注意: 温度が高いほど、AIの応答はより創造的で予測不可能になります。

• apiKey:

  • タイプ: string
  • デフォルト: なし
  • 説明: 選択したプロバイダーのAPIキー。
  • 例: process.env.OPENAI_API_KEY
  • 注意: 重要: APIキーは秘密にしておく必要があり、公開しないでください。環境変数などの安全な場所に保管することを必ず行ってください。

• applicationContext:

  • タイプ: string
  • デフォルト: なし
  • 説明: AIモデルに対してアプリケーションの追加コンテキストを提供し、より正確で文脈に適した翻訳を生成するのに役立ちます。これには、アプリのドメイン、ターゲットユーザー、トーン、特定の用語などの情報が含まれます。

ビルド設定

Intlayerがアプリケーションの国際化をどのように最適化しビルドするかを制御する設定。

ビルドオプションは @intlayer/babel と @intlayer/swc プラグインに適用されます。

開発モードでは、Intlayer は辞書を静的にインポートして、開発体験を簡素化します。

最適化された場合、Intlayer は辞書の呼び出しを置き換えてチャンク分割を最適化し、最終バンドルには実際に使用されている辞書のみがインポートされるようにします。

プロパティ

• optimize:

  • 型: boolean
  • デフォルト: process.env.NODE_ENV === 'production'
  • 説明: ビルドを最適化するかどうかを制御します。
  • 例: true
  • 注意: 有効にすると、Intlayer は辞書のすべての呼び出しを置き換えてチャンク分割を最適化します。これにより、最終バンドルは使用されている辞書のみをインポートします。すべてのインポートは辞書の読み込み時の非同期処理を避けるために静的インポートのまま維持されます。
  • 注意: Intlayerは、useIntlayerのすべての呼び出しをimportModeオプションで定義されたモードに置き換え、getIntlayerをgetDictionaryに置き換えます。
  • 注意: このオプションは@intlayer/babelおよび@intlayer/swcプラグインに依存しています。
  • 注意: useIntlayerの呼び出し内で、すべてのキーが静的に宣言されていることを確認してください。例: useIntlayer('navbar')。

• importMode:

  • タイプ: 'static' | 'dynamic' | 'live'
  • デフォルト: 'static'
  • 説明: 辞書のインポート方法を制御します。
  • 例: 'dynamic'
  • 注意: 利用可能なモード:
    • "static": 辞書は静的にインポートされます。useIntlayerをuseDictionaryに置き換えます。
    • "dynamic": 辞書はSuspenseを使用して動的にインポートされます。useIntlayerをuseDictionaryDynamicに置き換えます。
  • "live": 辞書はライブ同期APIを使用して動的に取得されます。useIntlayerはuseDictionaryFetchに置き換えられます。
  • 注意: 動的インポートはSuspenseに依存しており、レンダリングパフォーマンスにわずかな影響を与える可能性があります。
  • 注意: 無効にすると、使用されていなくてもすべてのロケールが一度に読み込まれます。
  • 注意: このオプションは@intlayer/babelおよび@intlayer/swcプラグインに依存しています。
  • 注意: useIntlayer呼び出し内のすべてのキーが静的に宣言されていることを確認してください。例：useIntlayer('navbar')。
  • 注意: optimizeが無効の場合、このオプションは無視されます。
  • 注意: "live" に設定されている場合、リモートコンテンツを含み、かつ "live" フラグが設定された辞書のみがライブモードとして変換されます。他の辞書はフェッチクエリの数と読み込みパフォーマンスを最適化するために、動的モードとして動的にインポートされます。
  • 注意: ライブモードはライブ同期APIを使用して辞書を取得します。APIコールが失敗した場合、辞書は動的モードとして動的にインポートされます。
  • 注意: このオプションは getIntlayer、getDictionary、useDictionary、useDictionaryAsync、および useDictionaryDynamic 関数には影響しません。

• traversePattern:

  • 型: string[]
  • デフォルト: ['**/*.{js,ts,mjs,cjs,jsx,tsx,mjx,cjx}', '!**/node_modules/**']
  • 説明: 最適化中にどのファイルを走査するかを定義するパターンです。
    • 例: ['src/**/*.{ts,tsx}', '../ui-library/**/*.{ts,tsx}', '!**/node_modules/**']
  • 注意: 最適化を関連するコードファイルに限定し、ビルドパフォーマンスを向上させるために使用します。
  • 注意: optimize が無効の場合、このオプションは無視されます。
  • 注意: グロブパターンを使用してください。

ドキュメント履歴

• 説明: 最適化中にどのファイルをトラバースするかを定義するパターン。
• 例: ['src/**/*.{ts,tsx}', '../ui-library/**/*.{ts,tsx}', '!**/node_modules/**']
• 注意: 最適化を関連するコードファイルに限定し、ビルドパフォーマンスを向上させるために使用します。
• 注意: optimize が無効の場合、このオプションは無視されます。
• 注意: グロブパターンを使用してください。

ドキュメント履歴