Intlayer コンパイラー | i18n のための自動コンテンツ抽出

Intlayer コンパイラーとは？

Intlayer コンパイラーは、アプリケーションの国際化（i18n）プロセスを自動化するために設計された強力なツールです。ソースコード（JSX、TSX、Vue、Svelte）内のコンテンツ宣言をスキャンし、それらを抽出して必要な辞書ファイルを自動的に生成します。これにより、コンテンツをコンポーネントと共に配置したままにでき、Intlayer が辞書の管理と同期を担当します。

なぜ Intlayer コンパイラーを使うのか？

• 自動化: コンテンツを辞書に手動でコピー＆ペーストする手間を排除します。
• 高速化: 最適化されたコンテンツ抽出により、ビルドプロセスの高速化を実現します。
• 開発者体験: コンテンツ宣言を使用箇所にそのまま保持し、保守性を向上させます。

• ライブアップデート: 開発中に即時フィードバックを得られるホットモジュールリプレースメント（HMR）をサポートします。

• Speed: 最適化されたコンテンツ抽出により、ビルドプロセスの速度が維持されます。

• Developer Experience: コンテンツ宣言を使用される場所に保つことで、保守性を向上させます。

• ライブ更新: 開発中の即座なフィードバックのための Hot Module Replacement (HMR) をサポートしています。

より詳しい比較については、Compiler vs. Declarative i18n のブログ記事をご覧ください。

Intlayer コンパイラーを使わない理由

コンパイラーは優れた「そのまま動作する」体験を提供しますが、いくつかのトレードオフも導入します：

• ヒューリスティックの曖昧さ：コンパイラーは、ユーザー向けコンテンツとアプリケーションロジック（例：className="active"、ステータスコード、製品ID）を推測する必要があります。複雑なコードベースでは、これにより誤検出や見逃された文字列が発生し、手動での注釈と例外処理が必要になる場合があります。

• 静的抽出のみ：コンパイラーベースの抽出は静的解析に依存しています。実行時のみ存在する文字列（APIエラーコード、CMSフィールドなど）は、コンパイラー単独では発見または翻訳できないため、補完的なランタイムi18n戦略が必要です。

• 静的のみの抽出: コンパイラベースの抽出は静的分析に依存します。実行時にのみ存在する文字列（APIエラーコード、CMS フィールドなど）はコンパイラだけでは検出または翻訳できないため、補完的なランタイム i18n 戦略が必要です。

より深いアーキテクチャの比較については、ブログ記事Compiler vs. Declarative i18nを参照してください。

代替として、コンテンツの完全な制御を維持しながらi18nプロセスを自動化するために、Intlayerは自動抽出コマンド intlayer extract（CLIドキュメントを参照）またはIntlayer VS Code拡張機能の Intlayer: extract content to Dictionary コマンド（VS Code拡張機能ドキュメントを参照）も提供しています。

使い方

The quickest way to wire the compiler in is the interactive setup: run npx intlayer init --interactive and select Compiler. On Vite there is nothing to configure — the compiler is plugged in directly through the intlayerCompiler() plugin. On Next.js the command scaffolds the babel.config.js shown below. The non-interactive intlayer init leaves the compiler setup untouched.

npm install vite-intlayer

import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});

# Vue用
npm install @intlayer/vue-compiler

# Svelte用
npm install @intlayer/svelte-compiler

npm install @intlayer/babel

const {
  intlayerExtractBabelPlugin,
  intlayerOptimizeBabelPlugin,
  getExtractPluginOptions,
  getOptimizePluginOptions,
} = require("@intlayer/babel");

module.exports = {
  presets: ["next/babel"],
  plugins: [
    // コンポーネントからコンテンツを抽出して辞書に変換
    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
    // useIntlayer を直接辞書インポートに置き換えてインポートを最適化
    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
  ],
};

カスタム設定

コンパイラーの動作をカスタマイズするには、プロジェクトのルートにある intlayer.config.ts ファイルを更新します。

import { type IntlayerConfig, Locales } from "intlayer";

const config: IntlayerConfig = {
  compiler: {
    /**
     * コンパイラーを有効にするかどうかを示します。
     * 開発中のコンパイラーをスキップして起動時間を短縮するには、'build-only'に設定します。
     */
    enabled: true,

    /**
     * 出力ファイルのパスを定義します。 `outputDir` を置き換えます。
     *
     * - `./` で始まるパスは、コンポーネントディレクトリを基準に解決されます。
     * - `/` で始まるパスは、プロジェクトのルート (`baseDir`) を基準に解決されます。
     *
     * - パスに `{{locale}}` 変数を含めると、言語ごとに分離された辞書の生成が有効になります。
     *
     * 例:
     * ```ts
     * {
     *   // コンポーネントの隣に多言語対応の .content.ts ファイルを作成
     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,
     *
     *   // output: './{{fileName}}{{extension}}', // 文字列テンプレートを使用した同等の記述
     * }
     * ```
     *
     * ```ts
     * {
     *   // プロジェクトのルートに言語ごとに集約された JSON ファイルを作成
     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,
     *
     *   // output: '/locales/{{locale}}/{{key}}.content.json', // 文字列テンプレートを使用した同等の記述
     * }
     * ```
     *
     * 変数リスト:
     *   - `fileName`: ファイル名。
     *   - `key`: コンテンツのキー。
     *   - `locale`: コンテンツのロケール。
     *   - `extension`: ファイル拡張子。
     *   - `componentFileName`: コンポーネントファイル名。
     *   - `componentExtension`: コンポーネント拡張子。
     *   - `format`: 辞書の形式。
     *   - `componentFormat`: コンポーネント辞書の形式。
     *   - `componentDirPath`: コンポーネントのディレクトリパス。
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * 変換後にコンポーネントを保存するかどうかを示します。
     * これにより、コンパイラーを1回だけ実行してアプリを変換し、その後削除することができます。
     */
    saveComponents: false,

    /**
     * 生成されたファイルにコンテンツのみを挿入します。ロケールごとの i18next または ICU MessageFormat JSON 出力に有用です。
     *
     * - `output: ({ locale, key }) => `./locale/${locale}/${key}.json`,`
     */
    noMetadata: false,

    /**
     * 辞書キーのプレフィックス
     */
    dictionaryKeyPrefix: "", // 抽出された辞書キーにオプションのプレフィックスを追加
  },
};

export default config;

コンパイラー設定リファレンス

以下のプロパティは、intlayer.config.tsファイルのcompilerブロックで設定できます。

• enabled:

  • タイプ: boolean | 'build-only'
  • デフォルト: true
  • 説明: コンパイラーを有効にするかどうかを示します。

• dictionaryKeyPrefix:

  • タイプ: string
  • デフォルト: ''
  • 説明: 抽出された辞書キーのプレフィックス。

• transformPattern:

  • タイプ: string | string[]
  • デフォルト: ['**/*.{js,ts,mjs,cjs,jsx,tsx,vue,svelte}', '!**/node_modules/**']
  • 説明: (非推奨: 代わりに build.traversePattern を使用) 最適化のためにコードをトラバースするパターン。

• excludePattern:

  • タイプ: string | string[]
  • デフォルト: ['**/node_modules/**']
  • 説明: (非推奨: 代わりに build.traversePattern を使用) 最適化から除外するパターン。

• output:

  • 型: FilePathPattern
  • デフォルト: ({ key }) => 'compiler/${key}.content.json'
  • 説明: 出力ファイルのパスを定義します。 outputDir を置き換えます。 {{locale}}、 {{key}}、 {{fileName}}、 {{extension}}、 {{format}}、 {{dirPath}}、 {{componentFileName}}、 {{componentExtension}}、 {{componentFormat}} などの動的変数を処理します。 'my/{{var}}/path' 形式の文字列または関数として設定できます。
  • 注: ./**/* パスはコンポーネントを基準に解決されます。 /**/* パスは Intlayer の baseDir を基準に解決されます。
  • 注: パスにロケールが定義されている場合、辞書はロケールごとに生成されます。
  • 例: output: ({ locale, key }) => 'compiler/${locale}/${key}.json'

• noMetadata:

  • タイプ: boolean
  • デフォルト: false
  • 説明: メタデータをファイルに保存するかどうかを示します。trueの場合、コンパイラーは辞書のメタデータ（キー、コンテンツラッパー）を保存しません。
  • 注: loadJSONプラグインを使用する場合に便利です。
  • 例: trueの場合: json { "key": "value" } falseの場合: json { "key": "value", "content": { "key": "value" } }

• saveComponents:

  • タイプ: boolean
  • デフォルト: false
  • 説明: 変換後にコンポーネントを保存するかどうかを示します。

欠落した翻訳を埋める

Intlayerは、欠落した翻訳を埋めるためのCLIツールを提供しています。intlayerコマンドを使用して、コード内の欠落した翻訳をテストし、埋めることができます。

npx intlayer test         # 欠落した翻訳があるかテストする

npx intlayer fill         # 欠落した翻訳を埋める

抽出

Intlayerは、コードからコンテンツを抽出するためのCLIツールを提供しています。intlayer extractコマンドを使用して、コードからコンテンツを抽出できます。

npx intlayer extract

詳細については、CLIドキュメント を参照してください。