@intlayer/docs 9.0.0-canary.6 → 9.0.0-canary.8

package/docs/ja/packages/vite-intlayer/intlayerMinify.md

@@ -0,0 +1,92 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: intlayerMinify Viteプラグインドキュメント | vite-intlayer
+description: コンパイルされたIntlayer辞書JSONファイルを圧縮（ミニファイ）し、必要に応じてコンテンツフィールド名を難読化してバンドルサイズを削減するViteプラグイン。
+keywords:
+  - intlayerMinify
+  - vite
+  - プラグイン
+  - 圧縮
+  - バンドルサイズ
+  - 辞書
+  - 国際化
+  - i18n
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerMinify
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "ドキュメント初期化"
+author: aymericzip
+---
+
+# intlayerMinify
+
+`intlayerMinify`は、本番ビルド（production build）時にコンパイルされた辞書JSONファイルを圧縮するViteプラグインです。不要な空白をすべて取り除き、`intlayerPrune`と組み合わせることで、コンテンツフィールド名を短いアルファベットのエイリアス（`a`、`b`、`c`、…）にオプションで変更し、バンドルサイズをさらに削減します。
+
+> [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/vite-intlayer/intlayer.md)を使用する場合、このプラグインはすでに自動的に含まれ、設定されています。プラグインのスタックをご自身で構成する場合にのみ、手動で登録する必要があります。
+
+## 使用方法
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayerMinify, intlayerPrune } from "vite-intlayer";
+import { createPruneContext } from "@intlayer/babel";
+
+const pruneContext = createPruneContext();
+
+export default defineConfig({
+  plugins: [
+    intlayerPrune(intlayerConfig, pruneContext),
+    intlayerMinify(intlayerConfig, pruneContext),
+  ],
+});
+```
+
+## 有効化の条件
+
+`intlayerMinify`は、以下の3つの条件がすべて満たされている場合に**のみ**有効になります：
+
+1. Viteコマンドが`build`である（`serve` / devではない）。
+2. `build.optimize`が`true`である（または`undefined`であり、ビルド時のデフォルトである`true`になる）。
+3. Intlayer設定で`build.minify`が`true`である。
+
+エディタは完全で人間が読める辞書コンテンツを必要とするため、`editor.enabled`が`true`の場合、プラグインは自動的に**無効**になります。
+
+## 圧縮される対象
+
+プラグインは、2つの辞書の場所（`intlayer.system`から解決される場所）をターゲットにします：
+
+- `dictionariesDir` — 静的な全言語共通の辞書（例：`.intlayer/dictionaries/*.json`）
+- `dynamicDictionariesDir` — 言語ごとの動的な辞書
+
+> フェッチモード辞書（`fetchDictionariesDir`）は、実行時に元のフィールド名を使用してリモートAPIから提供されるため、**決して**圧縮されません。フィールド名を変更すると、サーバーの応答とクライアント側のプロパティアクセスとの間に不一致が生じるためです。
+
+## フィールド名の難読化（プロパティの圧縮）
+
+`intlayerPrune`がコードベースを分析し、`pruneContext.dictionaryKeyToFieldRenameMap`にデータを入力すると、`intlayerMinify`はコンテンツフィールド名を短いエイリアスに変更します。例えば：
+
+```json
+// 変更前
+{ "key": "myDict", "content": { "title": "Hello", "description": "World" } }
+
+// 変更後（難読化あり）
+{ "key": "myDict", "content": { "a": "Hello", "b": "World" } }
+```
+
+対応するソースファイルのプロパティアクセスは、`intlayerOptimize`内のBabelパスによって変更されるため、実行時の動作は変わりません。
+
+Intlayerの内部フィールド（`nodeType`、`translation`など）の名前が変更されることはありません。
+
+## エッジケースの辞書
+
+`pruneContext.dictionariesWithEdgeCases`でフラグが立てられた辞書（クリーンアップ（prune）フェーズで検出された構造的な異常）は、破損したデータを配信するのを防ぐために完全にスキップされ、圧縮も難読化もされません。
+
+## 修飾子グループ（コレクション / バリアント / メタレコード）
+
+`qualifierTypes`配列を持つ辞書（コレクション、バリアント、メタレコード）について、プラグインは`qualifierTypes`配列と`meta`サイドマップをそのまま保持します。`content`エントリのフィールド名のみが難読化されます。実行時のセレクターマッチングに使用される複合キーが変更されることはありません。

package/docs/ja/packages/vite-intlayer/intlayerProxy.md

@@ -0,0 +1,172 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: intlayerProxy Viteプラグインドキュメント | vite-intlayer
+description: Viteの開発/プレビューサーバーおよび本番SSR用の言語ルーティングミドルウェア。言語検出、URLリダイレクト、および内部書き換えを処理します。
+keywords:
+  - intlayerProxy
+  - vite
+  - プラグイン
+  - ミドルウェア
+  - 言語
+  - ルーティング
+  - 国際化
+  - i18n
+  - SSR
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerProxy
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "configOptionsを単一のoptionsオブジェクトにマージ。proxyをintlayer()にバンドル"
+author: aymericzip
+---
+
+# intlayerProxy
+
+`intlayerProxy`は、開発サーバー、プレビューサーバー、および本番SSR（Nitro / TanStack Start）の**すべての環境**に対応する言語ルーティングミドルウェアを登録するViteプラグインです。
+
+> **Intlayer v9以降**、`intlayerProxy`は自動的にメインの[`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/vite-intlayer/intlayer.md)プラグインに含まれ、`routing.enableProxy: true`を介してデフォルトで有効になります。より低レベルな制御が必要な場合や、標準の`intlayer()`セットアップ以外で使用する場合にのみ、個別に登録する必要があります。
+
+## 使用方法
+
+### `intlayer()`の一部として（推奨、v9+）
+
+`intlayerProxy`を個別に登録する代わりに、メインプラグインに`proxy`オプションを渡します：
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
+});
+```
+
+### スタンドアロン（必要な場合）
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+## オプション
+
+```ts
+import type { IntlayerProxyPluginOptions } from "vite-intlayer";
+```
+
+すべてのオプションは任意であり、単一のオブジェクトとして渡されます：
+
+| オプション      | 型                                  | 説明                                                                                                                                                         |
+| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ignore`        | `(req: IncomingMessage) => boolean` | リクエストを言語ルーティングから除外する述語。リクエストをスキップするには`true`を返します（例：APIルート、ヘルスチェック）。                                |
+| `configOptions` | `GetConfigurationOptions`           | `getConfiguration()`に転送されるIntlayer設定のオーバーライド。プロキシに特定の設定ファイルを読み込ませたり、値を上書きしたりする必要がある場合に使用します。 |
+
+### 例
+
+```ts
+intlayerProxy({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+```
+
+## createIntlayerProxyHandler
+
+`createIntlayerProxyHandler`は、すべての言語ルーティングロジックを含む、特定のフレームワークに依存しないNode.jsの`(req, res, next)`スタンドアロンミドルウェアを作成します。ViteプラグインAPIが使用できない環境（例：純粋なNode.jsサーバーやカスタムNitroモジュール）で有用です。
+
+```ts
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+const handler = createIntlayerProxyHandler({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+
+// Express / Connect
+app.use(handler);
+```
+
+### 本番SSR（TanStack Start / h3を介した Nitro）
+
+```ts
+// server/middleware/intlayerProxy.ts
+import { fromNodeMiddleware } from "h3";
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+export default fromNodeMiddleware(
+  createIntlayerProxyHandler({
+    ignore: (req) => req.url?.startsWith("/api"),
+  })
+);
+```
+
+## ルーティングの動作
+
+ミドルウェアは、`next-intlayer`ミドルウェアのルーティングロジックを反映しており、すべてのIntlayerルーティングモードをサポートしています。
+
+### ルーティングモード
+
+| モード          | ブラウザに表示されるURL  | 動作                                                                                                                                |
+| --------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `prefix`        | `/ja/about`              | デフォルト。URLの言語プレフィックス。`prefix-all`が有効でない限り、デフォルト言語はプレフィックスなしのURLにリダイレクトします。    |
+| `prefix-all`    | `/en/about`, `/ja/about` | デフォルト言語を含むすべての言語が常にプレフィックス付きになります。                                                                |
+| `no-prefix`     | `/about`                 | URLに言語は含まれません。言語はCookieにのみ保存され、内部的にURLの書き換えが行われます。                                            |
+| `search-params` | `/about?locale=ja`       | クエリパラメータとして渡される言語。パラメータがない、または古い場合に、`locale`パラメータを追加/更新するためにリダイレクトします。 |
+
+### 検出の優先順位
+
+1. URLパスのプレフィックス（例：`/ja/about` → `ja`）。
+2. Cookie / localStorageの値（`intlayer-locale`）。
+3. `Accept-Language`ヘッダー。
+4. 設定ファイル内の`defaultLocale`。
+
+### 自動バイパス
+
+ミドルウェアは、言語処理を行うことなく、常に以下のリクエストをそのまま通します：
+
+- `ignore`述語に一致するリクエスト。
+- `/node_modules/**`
+- `/@**` – Viteの内部処理（`@vite/`、`@fs/`、`@id/`など）。
+- `/_**` – サーバーの内部処理（`__vite_ping`、`__manifest`など）。
+- パスがファイル拡張子で終わるリクエスト（静的アセット）。静的アセットのパスに言語プレフィックスが存在する場合（例：`/ja/logo.png`）、ファイルが正しく提供されるようにプレフィックスが削除されます。
+
+### ドメインルーティング
+
+Intlayer設定で`routing.domains`が構成されている場合、ミドルウェアはドメインをまたぐ言語ルーティングを処理します：
+
+- `domains.zh = "intlayer.zh"`のとき、`intlayer.org`上の`/zh/about`に対するリクエストは`https://intlayer.zh/about`にリダイレクトされます。
+- `intlayer.zh/about`へのリクエストは、`[locale]`ルートパラメータが入力されるように、内部的に`/zh/about`に書き換えられます。
+
+### リダイレクトループ防止
+
+ミドルウェアは、2秒のスライディングウィンドウ内で、`originalUrl → newUrl`のペアごとのリクエストに対するリダイレクト回数を追跡します。ウィンドウ内で10回を超えるリダイレクトが発生した場合、無限ループに陥るのを防ぐために、説明的なエラーを含む`500`応答を返します。
+
+## Nitro / 本番SSR（自動注入、v9+）
+
+`intlayerProxy`がViteプラグインとして使用される場合、`.nitro`プロパティを保持します。`nitro/vite`ビルドプラグインはこのプロパティを読み取り、`nitroConfig.modules`にプッシュします。これにより、`intlayerNitroHandler`が自動的にNitroサーバーミドルウェアとして登録されます。本番SSRのための手動設定は不要です。
+
+Nitroハンドラーは、h3 v2のWeb Fetch APIイベントモデルを使用しているため（`fromNodeMiddleware`ではない）、Node、Bun、Deno、エッジランタイムなど、すべてのNitroプリセットと互換性があります。
+
+## 非推奨のエイリアス
+
+| 非推奨のシグネチャ         | 代替品          |
+| -------------------------- | --------------- |
+| `intlayerMiddleware`       | `intlayerProxy` |
+| `intLayerMiddlewarePlugin` | `intlayerProxy` |

package/docs/ja/plugins/sync-json.md

@@ -108,7 +108,6 @@ const config: IntlayerConfig = {
      * ロケールディレクトリ内のJSONファイルに、出力と翻訳をロードして書き戻します
      */
     syncJSON({
-      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
       priority: 0,
       format: "i18next",

package/docs/ja/releases/v9.md

@@ -1,15 +1,14 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-23
+updatedAt: 2026-06-26
 title: Intlayer v9の新機能
-description: Intlayer v9の新機能をご覧ください。主要なi18nライブラリ向けのドロップイン互換性パッケージと、コレクション、バリアント、動的レコードのサポートを導入します。
+description: Intlayer v9の新機能をご覧ください。主要なi18nライブラリ向けのドロップイン互換性パッケージと、コレクション、バリアントのサポートを導入します。
 keywords:
   - Intlayer
   - Compatibility
   - Migration
   - Collections
   - Variants
-  - Dynamic Records
   - i18next
   - next-intl
   - vue-i18n
@@ -22,7 +21,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 +40,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 +101,7 @@ export default defineConfig({
 
 ---
 
-## 機能仕様：コレクション、バリアント、動的レコード
+## 機能仕様：コレクション、バリアント
 
 Intlayer v9は、静的なキーと値のオブジェクトを超えて拡張され、辞書がエンドツーエンドで完全に型付けされた動的なレイアウト構造を宣言できるようになりました。
 
@@ -144,6 +145,8 @@ const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: s
 
 A/Bテスト、季節限定ヘッダー、機能フラグ、またはカスタムランディングページを提供します。
 
+#### 文字列バリアント（例：A/Bテスト）
+
 ```ts fileName="hero.content.ts"
 import { t, type Dictionary } from "intlayer";
 
@@ -167,16 +170,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",
   },
@@ -229,7 +230,7 @@ export default defineConfig({
 });
 ```
 
-- **Compiler**: `compiler.enabled` が設定され、`compiler.output` パスが構成されている場合、自動的に有効化されます。`intlayerCompiler()` を個別に登録する必要はなくなりました。
+- **Compiler**: `compiler.enabled` が `true` に設定され、`compiler.output` パスが構成されている場合、自動的に有効化されます。`intlayerCompiler()` を個別に登録する必要はなくなりました。
 - **Proxy**: 新しい `routing.enableProxy` オプション（デフォルトは `true`）に基づいて自動的に有効化されます。開発、プレビュー、本番 SSR でロケール検出・リダイレクト・書き換えミドルウェアを配線します。`intlayerProxy()` を個別に登録する必要はなくなりました。
 
 ### `routing.enableProxy` オプション
@@ -252,17 +253,61 @@ export default config;
 
 ---
 
+## コンパイラはデフォルトで無効
+
+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` プロバイダには含まれていないポリフィルを提供します。
+
+---
+
 ## v8からの移行に関する注意点
 
 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)
 - [設定リファレンス](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/configuration.md)

package/docs/ko/compiler.md

@@ -81,12 +81,15 @@ npm install vite-intlayer
 
 ```ts fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayer(),
-    intlayerCompiler(), // 컴파일러 플러그인 추가
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```

package/docs/ko/custom_domains.md

@@ -172,10 +172,16 @@ GET intlayer.zh/about
 
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayerProxy()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 

package/docs/ko/custom_url_rewrites.md

@@ -342,10 +342,16 @@ SolidJS, Vue, Svelte의 경우, 개발 중 리라이트를 `intlayerProxy` Vite
 
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayerProxy()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 

package/docs/ko/dynamic_dictionaries/index.md

@@ -1,13 +1,12 @@
 ---
 createdAt: 2026-06-12
-updatedAt: 2026-06-12
+updatedAt: 2026-06-26
 title: 동적 사전
-description: 유연하고 런타임 구동 방식의 i18n 콘텐츠를 구축하기 위한 Intlayer의 세 가지 동적 사전 기능 — 컬렉션, 변형, 동적 레코드 — 개요.
+description: Intlayer의 동적 사전 기능(컬렉션 및 변형) 개요 — 유연하고 런타임 기반의 i18n 콘텐츠를 구축하기 위한 것입니다.
 keywords:
   - 동적 사전
   - 컬렉션
   - 변형
-  - 동적 레코드
   - Intlayer
   - 국제화
 slugs:
@@ -18,31 +17,38 @@ history:
   - version: 9.0.0
     date: 2026-06-12
     changes: "동적 사전 기능 출시"
+  - version: 9.1.0
+    date: 2026-06-26
+    changes: "동적 레코드를 변형으로 통합 — 이제 `variant`는 문자열 또는 객체를 허용합니다"
 author: aymericzip
 ---
 
 # 동적 사전
 
-Intlayer는 키당 하나의 정적 사전을 정의하는 것을 넘어선 콘텐츠를 표현하기 위한 세 가지 메커니즘을 지원합니다. 각각은 콘텐츠 파일 내의 **최상위 메타데이터 필드**를 통해 선언되며, 래퍼 함수는 필요하지 않습니다.
+Intlayer는 키당 단일 정적 사전을 넘어서는 콘텐츠를 표현하기 위한 두 가지 메커니즘을 지원합니다. 각각은 콘텐츠 파일의 **최상위 메타데이터 필드**를 통해 선언되며, 래퍼 함수가 필요하지 않습니다.
 
-| 기능                                                                                                                 | 메타데이터 필드   | `useIntlayer`에서의 선택기 |
-| -------------------------------------------------------------------------------------------------------------------- | ----------------- | -------------------------- |
-| [컬렉션](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/collections.md)          | `item: N`         | `{ item: N }`              |
-| [변형](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/variants.md)               | `variant: "name"` | `{ variant: "name" }`      |
-| [동적 레코드](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/dynamic_content.md) | `meta: { id, … }` | `{ id, … }`                |
+| 기능                                                                                                        | 메타데이터 필드                           | `useIntlayer`의 셀렉터                            |
+| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------- |
+| [컬렉션](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/collections.md) | `item: N`                                 | `{ item: N }`                                     |
+| [변형](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/variants.md)      | `variant: "name"` _또는_ `variant: { … }` | `{ variant: "name" }` _또는_ `{ variant: { … } }` |
 
-세 메커니즘 모두 로케일 인수와 결합하며, `importMode`를 통한 선택적 / 지연 로딩을 지원합니다.
+둘 다 locale 인수와 결합되며 `importMode`를 통한 선택적 / 지연 로딩을 지원합니다.
 
-## 언제 무엇을 사용해야 하는가
+## 무엇을 언제 사용할지
 
-- **컬렉션** — 별도의 파일로 관리되는 정렬된 항목 목록(FAQ 항목, 블로그 게시물, 상품 등).
-- **변형** — A/B 테스트, 시즌별 배너 또는 기능 플래그(feature flags)를 위한 이름이 지정된 대체 콘텐츠.
-- **동적 레코드** — 불투명한 ID를 사용하여 런타임에 검색되는 콘텐츠(CMS 레코드, 사용자별 텍스트 등).
+- **컬렉션** — 별도의 파일에서 관리되는 정렬된 항목 목록(FAQ 항목, 블로그 게시물, 제품).
+- **변형** — 이름이 지정되었거나 구조화된 콘텐츠 대안:
+  - A/B 테스트, 시즌 배너 또는 기능 플래그를 위한 **문자열** 변형;
+  - CMS 레코드, 사용자별 콘텐츠, 또는 필드 집합으로 주소가 지정되는 모든 콘텐츠를 위한 **객체** 변형(이전의 "동적 레코드").
 
-## 선택기 우선순위 해결
+> 이전 버전은 레코드 키 기반 콘텐츠를 위해 별도의 `meta` 필드를 제공했습니다. 이는 `variant`로 통합되었습니다. `meta`를 사용하는 대신 `variant`에 **객체**를 전달하세요.
 
-하나의 사전에 여러 선택기가 있는 경우 해결 순서는 다음과 같습니다:
+## 셀렉터 모호성 해소
+
+키는 두 차원을 동시에 선언할 수 있습니다(예: 각 항목에 변형이 있는 컬렉션). 이는 다음 순서로 해결됩니다:
 
 ```
-variant → meta → item
+variant → item
 ```
+
+따라서 variant × item 키에서 `{ variant: "promo" }`는 모든 promo 항목을 배열로 반환하고, `{ item: 2 }`를 추가하면 단일 항목으로 좁혀집니다.