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

Intlayer コンパイラーとは？

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

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

• 自動化: コンテンツを辞書に手動でコピー＆ペーストする手間を排除します。
• 高速化: 最適化されたコンテンツ抽出により、ビルドプロセスの高速化を実現します。
• 開発者体験: コンテンツ宣言を使用箇所にそのまま保持し、保守性を向上させます。
• ライブアップデート: 開発中に即時フィードバックを得られるホットモジュールリプレースメント（HMR）をサポートします。

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

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

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

• ヒューリスティックの曖昧さ：コンパイラーは、ユーザー向けコンテンツとアプリケーションロジック（例：className="active"、ステータスコード、製品ID）を推測する必要があります。複雑なコードベースでは、これにより誤検出や見逃された文字列が発生し、手動での注釈と例外処理が必要になる場合があります。
• 静的抽出のみ：コンパイラーベースの抽出は静的解析に依存しています。実行時のみ存在する文字列（APIエラーコード、CMSフィールドなど）は、コンパイラー単独では発見または翻訳できないため、補完的なランタイムi18n戦略が必要です。

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

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

使い方

npm install vite-intlayer

import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // コンパイラープラグインを追加 ],});

# 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ドキュメント を参照してください。