@intlayer/docs 9.0.0-canary.2 → 9.0.0-canary.21

package/docs/ja/releases/v9.md

@@ -1,15 +1,15 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-14
+updatedAt: 2026-07-08
 title: Intlayer v9の新機能
-description: Intlayer v9の新機能をご覧ください。主要なi18nライブラリ向けのドロップイン互換性パッケージと、コレクション、バリアント、動的レコードのサポートを導入します。
+description: Intlayer v9の新機能をご覧ください。主要なi18nライブラリ向けのドロップイン互換性パッケージと、コレクション、バリアントのサポートを導入します。
 keywords:
   - Intlayer
   - Compatibility
   - Migration
   - Collections
   - Variants
-  - Dynamic Records
+  - CMS SDK
   - i18next
   - next-intl
   - vue-i18n
@@ -22,7 +22,7 @@ author: aymericzip
 
 # Intlayer v9の新機能
 
-Intlayer v9へようこそ！このメジャーリリースは、主要なi18nライブラリ（`react-i18next`、`next-intl`、`vue-i18n`など）向けの**互換アダプターパッケージ**により、Intlayerへの移行パスを簡素化し、**コレクション**、**バリアント**、**動的レコード**といったリッチなコンテンツ構造のサポートを追加することで、大きな節目となります。
+Intlayer v9へようこそ！このメジャーリリースは、主要なi18nライブラリ（`react-i18next`、`next-intl`、`vue-i18n`など）向けの**互換アダプターパッケージ**により、Intlayerへの移行パスを簡素化し、**コレクション**、**バリアント**といったリッチなコンテンツ構造のサポートを追加することで、大きな節目となります。
 
 ## 目次
 
@@ -41,8 +41,10 @@ Intlayer v9へようこそ！このメジャーリリースは、主要なi18n
 - `@intlayer/i18next`
 - `@intlayer/react-i18next`
 - `@intlayer/next-intl`
+- `@intlayer/react-intl`
 - `@intlayer/next-i18next`
 - `@intlayer/vue-i18n`
+- `@intlayer/lingui`
 
 例えば、次のように変更するだけです。
 
@@ -100,7 +102,7 @@ export default defineConfig({
 
 ---
 
-## 機能仕様：コレクション、バリアント、動的レコード
+## 機能仕様：コレクション、バリアント
 
 Intlayer v9は、静的なキーと値のオブジェクトを超えて拡張され、辞書がエンドツーエンドで完全に型付けされた動的なレイアウト構造を宣言できるようになりました。
 
@@ -108,42 +110,48 @@ Intlayer v9は、静的なキーと値のオブジェクトを超えて拡張さ
 
 CMSで管理される順序付きアイテムのリスト（例：FAQ、製品、ブログリスト）を定義します。
 
-```ts fileName="faq.content.ts"
+```ts fileName="faq.1.content.ts"
 import { t, type Dictionary } from "intlayer";
 
 export default {
   key: "faq",
-  content: [
-    {
-      question: t({
-        ja: "Intlayerとは何ですか？",
-        en: "What is Intlayer?",
-        fr: "Qu'est-ce qu'Intlayer ?",
-      }),
-      answer: t({
-        ja: "i18nツールキットです。",
-        en: "An i18n toolkit.",
-        fr: "Une boîte àツール i18n.",
-      }),
-    },
-  ],
+  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;
+```
+
+```ts fileName="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
+// Fetch all items as an array
 const allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]
 
-// Fetch single item by index
-const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: string }
+// Fetch a single item by index
+const faq = useIntlayer("faq", { item: 2 }); // -> { question: string, answer: string }
 ```
 
 ### 2. バリアント
 
 A/Bテスト、季節限定ヘッダー、機能フラグ、またはカスタムランディングページを提供します。
 
+#### 文字列バリアント（例：A/Bテスト）
+
 ```ts fileName="hero.content.ts"
 import { t, type Dictionary } from "intlayer";
 
@@ -167,16 +175,14 @@ export default {
 const banner = useIntlayer("hero-banner", { variant: "black_friday" });
 ```
 
-### 3. 動的レコード
-
-クエリIDを介してランタイムで動的にエントリがロードされる辞書を定義します。
+#### オブジェクトバリアント（例：動的レコード）
 
 ```ts fileName="product.content.ts"
 import { t, type Dictionary } from "intlayer";
 
 export default {
   key: "product-copy",
-  meta: {
+  variant: {
     id: "prod_123",
     category: "books",
   },
@@ -191,28 +197,159 @@ export default {
 ```ts
 // Fetches only the requested item dynamically (requires Suspense)
 const product = useIntlayer("product-copy", {
-  id: "prod_123",
-  category: "books",
+  variant: { id: "prod_123", category: "books" },
 });
 ```
 
 ---
 
-## 動的ロードとバンドルサイズの最適化
+## `@intlayer/analytics`: コンテンツ露出の計測と A/B テスト
+
+新しいオプションパッケージ [`@intlayer/analytics`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md) は、実際にどのコンテンツが訪問者に表示されているかを教えてくれます。そして **Collections & Variants** の輪を完成させ、コンテンツの A/B テストとバリアントごとのコンバージョン計測を可能にします。
+
+- **プロバイダーレベルの計測**: `IntlayerProvider`（React / Next.js / React Native）は、初回読み込み、ルート変更、ロケール変更時に自動で `page_view` イベントを記録します。
+- **ノードレベルの計測**: `useIntlayer` が解決されるたびに `content_exposure` イベントが送信されます — どの辞書キー、キーパス、ロケール、そして（該当する場合は）どの A/B **バリアント** が表示されたか。フラッシュ間隔内の同一ノードへの重複露出は 1 件に集約されます。
+- **決定論的な A/B 割り当て**: `getVariant(experimentKey, variants)` はサーバーへの往復なしでセッションにバリアントを割り当てるため、初回描画前のちらつきがありません。
+- **`useConversion()`**: セッションが見たバリアントに対して、ゴール（登録、クリック、購入など）を紐づけます。
+- **未インストール時のコストはゼロ**: `@intlayer/editor` と同じ tree-shakeable パターンを採用 — `try/catch` でラップした動的 `import()` に加え、ビルド時の環境変数（`INTLAYER_ANALYTICS_ENABLED`）により、利用しないアプリでは統合全体がデッドコード除去されます。
+- **新しい設定スキーマなし**: 既存の `editor.backendURL`（送信先エンドポイント / セルフホスティング）と `editor.clientId`（プロジェクトキー、兼有効化スイッチ）を再利用します。
+- **プライバシーへの配慮**: セッションの匿名ハッシュ化（SHA-256、生の ID は保存しない）、IP は保存せず、国単位の大まかな位置情報のみ、リクエストはおよそ 20 秒ごとにバッチ送信されます。
+- **ダッシュボード**: 新しい **Analytics** ページ（プロジェクト選択後にサイドバーへ表示）で、アクティブユーザー数、本日のユーザー数、過去 7/30/90 日のユーザー数、訪問者推移グラフ、ロケール別・地域別の内訳を確認できます。
+
+```tsx fileName="CTAButton.tsx" codeFormat="tsx"
+import { useConversion } from "react-intlayer";
+
+const CTAButton = () => {
+  const trackConversion = useConversion();
+
+  return (
+    <button
+      onClick={() =>
+        trackConversion({
+          experimentKey: "homepage-hero",
+          variant: "black_friday",
+          goal: "cta_click",
+        })
+      }
+    >
+      Get started
+    </button>
+  );
+};
+```
 
-バンドルを極めて小さく保つため、Intlayer v9は動的な遅延ロードをサポートしています。
+```bash packageManager="npm"
+npm install @intlayer/analytics
+```
 
-設定で、`importMode`を`'dynamic'`または`'fetch'`に設定します。
+現在 React、Next.js、React Native（`react-intlayer` 経由）で利用可能です。他のフレームワークバインディング（Vue、Svelte、Angular など）は、`@intlayer/editor` と同じ展開パターンに沿って計画されています。完全なガイドは [Analytics ドキュメント](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md) を参照してください。
+
+---
+
+## Vite Plugin: バンドルされたコンパイラとプロキシ
+
+`intlayer()` Vite プラグインは、**コンパイラ**と**ロケールルーティングプロキシ**を直接バンドルするようになったため、ほとんどのプロジェクトは `vite.config.ts` に単一のプラグインのみが必要です：
+
+```ts fileName="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 ルーティングを自分で処理したい場合は、これを無効にしてください:
 
 ```ts fileName="intlayer.config.ts"
-export default {
-  dictionary: {
-    importMode: "dynamic", // "static" | "dynamic" | "fetch"
+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` を指定します。
+
+```ts fileName="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`、… — ドメインごとの **エンドポイントバインダー**。それぞれ独自のサブパスからインポートします。
+
+```ts fileName="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]);
 ```
 
-ビルド時、`@intlayer/swc`と`@intlayer/babel`はファイルをスキャンし、`useIntlayer` / `getIntlayer`の呼び出しをツリーシェイク可能なラッパー（`useDictionary` / `useDictionaryDynamic`）に置き換えます。選択されたコレクションアイテム、バリアント、またはロケールに必要なコンテンツのみがロードされ、本番バンドルに未使用の翻訳が含まれるのを防ぎます。
+> セキュリティ: CMS の資格情報はコンテンツへの書き込みアクセスを許可します。認証器は必ず **サーバーサイド** でのみ作成し、`clientId` / `clientSecret` をブラウザーに送らないでください。
 
 ---
 
@@ -220,13 +357,16 @@ export default {
 
 v8からアップグレードする場合、v9には破壊的変更は含まれていません。ただし、主な変更点は次のとおりです。
 
+- **コンパイラはデフォルトで無効**: `compiler.enabled` のデフォルト値は `false` になりました。`.content.ts` ファイルのビルド時抽出に依存している場合は、`intlayer.config.ts` で `compiler.enabled: true` を設定してください。
 - **ロケールと方言**: 外部i18n依存関係を使用している場合、設定またはバンドラーセットアップにそれぞれの互換アダプタープラグインを追加して、インポートを自動的に書き換えるようにします。
-- **カスタムセレクター**: `useIntlayer`を呼び出す際、2番目のパラメーターは`{ locale, item, variant, id }`を含むオプションオブジェクトのために予約されるようになりました。以前にロケール文字列を直接渡していた場合でも引き続き可能ですが、高度な選択にはオプションオブジェクトの使用が推奨されます。
+- **カスタムセレクター**: `useIntlayer`を呼び出す際、2番目のパラメーターは`{ locale, item, variant }`を含むオプションオブジェクトのために予約されるようになりました。以前にロケール文字列を直接渡していた場合でも引き続き可能ですが、高度な選択にはオプションオブジェクトの使用が推奨されます。
 
 ---
 
 ## 役立つリンク
 
 - [互換アダプターパッケージガイド](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/compat/index.md)
-- [動的辞書 - コレクション、バリアント、動的レコード](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/dynamic_dictionaries/index.md)
+- [動的辞書 - コレクション、バリアント](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/dynamic_dictionaries/index.md)
+- [Analytics（分析） - コンテンツ露出の計測とA/Bテスト](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md)
 - [設定リファレンス](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/configuration.md)
+- [CMS SDK - @intlayer/api によるプログラムからのアクセス](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/intlayer_CMS.md)

package/docs/ja/roadmap.md

@@ -29,6 +29,12 @@ Intlayerは、アプリケーション全体でコンテンツを宣言、管理
 
 ---
 
+## 目次
+
+<TOC/>
+
+---
+
 ## 現在の機能
 
 ### 1. コンテンツ宣言