著者:
    作成:2026-06-14最終更新:2026-06-29

    Intlayer v9の新機能

    Intlayer v9へようこそ！このメジャーリリースは、主要なi18nライブラリ（react-i18next、next-intl、vue-i18nなど）向けの互換アダプターパッケージにより、Intlayerへの移行パスを簡素化し、コレクション、バリアントといったリッチなコンテンツ構造のサポートを追加することで、大きな節目となります。

    目次

    互換アダプターパッケージ

    人気のi18nライブラリからIntlayerへの移行がこれまで以上に簡単になりました。標準のi18nライブラリとまったく同じ公開APIを公開しつつ、すべての翻訳作業をIntlayerにランタイムで委譲する5つの互換パッケージを作成しました。

    厳密な型付けで同じ公開APIを公開

    インポートを置き換えるだけで、最小限のコード変更でIntlayerのすべての利点（実際の辞書に対するコンパイル時の型安全性を含む）を得ることができます。

    • @intlayer/i18next
    • @intlayer/react-i18next
    • @intlayer/next-intl
    • @intlayer/react-intl
    • @intlayer/next-i18next
    • @intlayer/vue-i18n
    • @intlayer/lingui

    例えば、次のように変更するだけです。

    ts
    import { useTranslation } from "react-i18next";

    を次のように変更します。

    ts
    import { useTranslation } from "@intlayer/react-i18next";

    これにより、キーはIntlayer辞書に対して厳密に型付けされ、IDEで完全なドットパスのオートコンプリートが提供されます！

    バンドラーエイリアスプラグイン (Vite, Next.js, Turbopack)

    すべてのインポートステートメントを手動で書き換えることなく移行できるように、各互換アダプターパッケージには、/pluginサブパスの下にカスタムバンドラープラグイン（ViteまたはNext.js）が含まれています。

    これらのプラグインは、ビルド時に既存のインポート（例：react-i18nextやnext-intl）を自動的に@intlayer/*の同等物に書き換えます。

    Next.js (Webpack / Turbopack) の例

    withIntlayerの代わりに、互換プラグインでNext.jsの設定をラップします。

    next.config.ts
    import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";import type { NextConfig } from "next";const withIntlayer = createNextI18nPlugin();const nextConfig: NextConfig = {};export default withIntlayer(nextConfig);

    Vite (React, Vue, Solid, Svelte) の例

    vite.config.ts
    import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";export default defineConfig({  plugins: [vueI18nVitePlugin()],});

    共通化されたランタイムリゾルバー

    すべての互換アダプターは、単一の高度に最適化されたランタイムパーサーである@intlayer/core/messageFormatを介して翻訳解決をルーティングするようになりました。

    • メッセージ補間: 標準の{{var}}（空白とドットパス）、ICU形式の引数（{v, number, percent}など）、および裸の{var}テンプレートを解決します。
    • メッセージノードリゾルバー: ネストされたノードを解決します：insert()、plural()（CLDR複数形ルール）、enu()（列挙）、gender()、HTMLタグ、配列、および呼び出し可能な関数ノード。
    • トークン化されたタグパーサー: インラインXML/HTMLタグと番号付きタグ（例：<1>children</1>)をサポートし、リッチテキストレンダリングをすぐに利用できるようにします。

    機能仕様：コレクション、バリアント

    Intlayer v9は、静的なキーと値のオブジェクトを超えて拡張され、辞書がエンドツーエンドで完全に型付けされた動的なレイアウト構造を宣言できるようになりました。

    1. コレクション

    CMSで管理される順序付きアイテムのリスト（例：FAQ、製品、ブログリスト）を定義します。

    faq.1.content.ts
    import { t, type Dictionary } from "intlayer";export default {  key: "faq",  item: 1,  content: {    question: t({ en: "What is Intlayer?", fr: "Qu'est-ce qu'Intlayer ?" }),    answer: t({ en: "An i18n toolkit.", fr: "Une boîte à outils i18n." }),  },} satisfies Dictionary;
    faq.2.content.ts
    import { t, type Dictionary } from "intlayer";export default {  key: "faq",  item: 2,  content: {    question: t({ en: "Is it free?", fr: "Est-ce gratuit ?" }),    answer: t({ en: "Yes, open-source.", fr: "Oui, open-source." }),  },} satisfies Dictionary;

    使用法：

    ts
    // Fetch all items as an arrayconst allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]// Fetch a single item by indexconst faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }

    2. バリアント

    A/Bテスト、季節限定ヘッダー、機能フラグ、またはカスタムランディングページを提供します。

    文字列バリアント（例：A/Bテスト）

    hero.content.ts
    import { t, type Dictionary } from "intlayer";export default {  key: "hero-banner",  variant: "default",  content: {    control: t({ ja: "ようこそ", en: "Welcome", fr: "Bienvenue" }),    black_friday: t({      ja: "今すぐ購入",      en: "Shop now",      fr: "Acheter maintenant",    }),  },} satisfies Dictionary;

    使用法：

    ts
    const banner = useIntlayer("hero-banner", { variant: "black_friday" });

    オブジェクトバリアント（例：動的レコード）

    product.content.ts
    import { t, type Dictionary } from "intlayer";export default {  key: "product-copy",  variant: {    id: "prod_123",    category: "books",  },  content: {    title: t({ ja: "クリーンコード", en: "Clean Code", fr: "Code Propre" }),  },} satisfies Dictionary;

    使用法：

    ts
    // Fetches only the requested item dynamically (requires Suspense)const product = useIntlayer("product-copy", {  variant: { id: "prod_123", category: "books" },});

    Vite Plugin: バンドルされたコンパイラとプロキシ

    intlayer() Vite プラグインは、コンパイラとロケールルーティングプロキシを直接バンドルするようになったため、ほとんどのプロジェクトは vite.config.ts に単一のプラグインのみが必要です：

    vite.config.ts
    import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";export default defineConfig({  plugins: [intlayer()],});
    • Compiler: compiler.enabled が true に設定され、compiler.output パスが構成されている場合、自動的に有効化されます。intlayerCompiler() を個別に登録する必要はなくなりました。
    • Proxy: 新しい routing.enableProxy オプション（デフォルトは true）に基づいて自動的に有効化されます。開発、プレビュー、本番 SSR でロケール検出・リダイレクト・書き換えミドルウェアを配線します。intlayerProxy() を個別に登録する必要はなくなりました。

    routing.enableProxy オプション

    新しい routing.enableProxy オプションは、locale-routing プロキシがプラグインされているかどうかを制御します。デフォルトは true です。locale ルーティングを自分で処理したい場合は、これを無効にしてください:

    intlayer.config.ts
    import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  routing: {    enableProxy: false, // デフォルト: true  },};export default config;

    スタンドアロンの intlayerCompiler() と intlayerProxy() プラグインは、高度なセットアップ用にエクスポートされたままです。これらを intlayer() と一緒に登録しても安全です — 各プラグインは自動的に重複排除され、1 回だけ実行されます。

    コンパイラはデフォルトで無効

    Intlayer v9 以降、コンパイラはデフォルトで無効になっています（compiler.enabled のデフォルト値は false になりました）。.content.ts ファイルのビルド時抽出を有効にするには、設定で compiler.enabled: true を指定します。

    intlayer.config.ts
    import type { IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  compiler: {    enabled: true, // デフォルト: false — v9 以降、コンパイラを有効にするために必要    output: ({ fileName }) => `./${fileName}.content.ts`,  },};export default config;

    コンパイラが無効の場合、Intlayer はビルド時の抽出ステップをスキップし、すでに宣言済みの辞書に依存します。バンドラープラグイン（@intlayer/swc、@intlayer/babel、または intlayer() Vite プラグイン）にコンテンツを自動的に抽出させたい場合にのみ有効にしてください。

    React Native: 単一パッケージでのインポート

    React Native または Expo アプリでは、react-intlayer と react-native-intlayer の両方を使い分ける必要がなくなりました。react-native-intlayer パッケージは現在、react-intlayer の完全な API を再エクスポートしており（フック、ユーティリティ、および /format、/html、/markdown サブパス）、その IntlayerProvider は自動的に React Native のポリフィルを適用します。

    すべての機能を単一の react-native-intlayer パッケージからインポートしてください：

    tsx
    import {  IntlayerProvider,  useIntlayer,  useLocale,} from "react-native-intlayer";
    bash
    npm install intlayer react-native-intlayer
    react-intlayer からのインポートも引き続き機能しますが、React Native の推奨される単一エントリポイントは react-native-intlayer になりました。このプロバイダは、Web 指向の react-intlayer プロバイダには含まれていないポリフィルを提供します。

    CMS SDK: Intlayer をヘッドレスコンテンツデータベースとして使う

    Intlayer v9 は、CMS をプログラムから操作するためのクリーンで自動認証される SDK を @intlayer/api に同梱しています。プロジェクトの取得、辞書の取得、そして自分のサーバー・スクリプト・CI からのプッシュや更新が可能です。認証（OAuth2 client_credentials）は自動的に処理・更新されます。

    SDK は 2 つの独立したインポート に分かれており、実際に使用するドメインだけがバンドルに含まれます。

    1. createIntlayerCMS — 資格情報と管理されるトークンを保持する軽量な 認証器（ドメインクライアントは同梱されません）。
    2. dictionaryEndpoint、projectEndpoint、… — ドメインごとの エンドポイントバインダー。それぞれ独自のサブパスからインポートします。
    cms.ts
    import { createIntlayerCMS } from "@intlayer/api";import { dictionaryEndpoint } from "@intlayer/api/dictionary";// 設定は任意です。資格情報は INTLAYER_CLIENT_ID /// INTLAYER_CLIENT_SECRET（`@intlayer/config/built` により解決）にフォールバックします。const cms = createIntlayerCMS();// 読み取りconst { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();// 書き込み — CMS をデータベースのように使うawait dictionaryEndpoint(cms).pushDictionaries([myDictionary]);
    セキュリティ: CMS の資格情報はコンテンツへの書き込みアクセスを許可します。認証器は必ず サーバーサイド でのみ作成し、clientId / clientSecret をブラウザーに送らないでください。

    v8からの移行に関する注意点

    v8からアップグレードする場合、v9には破壊的変更は含まれていません。ただし、主な変更点は次のとおりです。

    • コンパイラはデフォルトで無効: compiler.enabled のデフォルト値は false になりました。.content.ts ファイルのビルド時抽出に依存している場合は、intlayer.config.ts で compiler.enabled: true を設定してください。
    • ロケールと方言: 外部i18n依存関係を使用している場合、設定またはバンドラーセットアップにそれぞれの互換アダプタープラグインを追加して、インポートを自動的に書き換えるようにします。
    • カスタムセレクター: useIntlayerを呼び出す際、2番目のパラメーターは{ locale, item, variant }を含むオプションオブジェクトのために予約されるようになりました。以前にロケール文字列を直接渡していた場合でも引き続き可能ですが、高度な選択にはオプションオブジェクトの使用が推奨されます。

    役立つリンク

    Language Server Protocol
    v8