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

package/docs/ja/packages/svelte-intlayer/usePathname.md

@@ -0,0 +1,103 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: usePathname 関数ドキュメント | svelte-intlayer
+description: svelte-intlayer パッケージの usePathname 関数の使用方法
+keywords:
+  - usePathname
+  - pathname
+  - locale
+  - Intlayer
+  - Internationalization
+  - Documentation
+  - Svelte
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - svelte-intlayer
+  - usePathname
+history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "usePathname ユーティリティを追加"
+  - version: 8.2.0
+    date: 2026-06-22
+    changes: "履歴の初期化"
+author: aymericzip
+---
+
+# Svelte 統合: `usePathname` ドキュメント
+
+`usePathname` 関数は、ロケールセグメントが削除された現在のブラウザのパス名を Svelte の `Readable<string>` ストアとして返します。これは、ロケールプレフィックスを手動で削除することなく、ロケールを考慮したナビゲーション（例えば、どのナビゲーション項目がアクティブかを判断するなど）を構築するのに役立ちます。
+
+## Svelte で `usePathname` をインポートする
+
+```typescript
+import { usePathname } from "svelte-intlayer";
+```
+
+## 概要
+
+`usePathname` は `window.location.pathname` から初期化される Svelte の読み取り可能なストア（readable store）を作成し、`getPathWithoutLocale` を介してロケールプレフィックスを削除し、ブラウザが `popstate` イベント（戻る/進むナビゲーション）を発生させるたびに新しい値を発行します。コンポーネント内では `$` ストア構文を使用してサブスクライブします。
+
+## 使用法
+
+```svelte fileName="src/components/NavItem.svelte"
+<script lang="ts">
+  import { usePathname } from "svelte-intlayer";
+
+  export let href: string;
+  export let label: string;
+
+  const pathname = usePathname();
+</script>
+
+<a {href} aria-current={$pathname === href ? "page" : undefined}>
+  {label}
+</a>
+```
+
+## 戻り値
+
+| タイプ             | 説明                                                                                                 |
+| ------------------ | ---------------------------------------------------------------------------------------------------- |
+| `Readable<string>` | ロケールプレフィックスを含まない現在のパス名を含む Svelte の読み取り可能なストア（Readable store）。 |
+
+## 動作
+
+- **ロケールの削除**: 先頭のロケールセグメントを削除します（例: `/ja/dashboard` → `/dashboard`）。
+- **リアクティブ**: `popstate` イベント（ブラウザの戻る/進むナビゲーション）のたびに新しい値を発行します。
+- **SSR セーフ**: `window` が利用できない場合は `""` を返します。
+- **クリーンアップ**: 最後のサブスクライバーがサブスクライブを解除すると、`popstate` リスナーは自動的に削除されます。
+
+## 例
+
+```svelte fileName="src/components/Sidebar.svelte"
+<script lang="ts">
+  import { usePathname } from "svelte-intlayer";
+
+  const links = [
+    { href: "/dashboard", label: "ダッシュボード" },
+    { href: "/settings", label: "設定" },
+  ];
+
+  const pathname = usePathname();
+</script>
+
+<nav>
+  {#each links as link}
+    <a
+      href={link.href}
+      style:font-weight={$pathname === link.href ? "bold" : "normal"}
+    >
+      {link.label}
+    </a>
+  {/each}
+</nav>
+```
+
+## 関連
+
+- [`useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/svelte-intlayer/useLocale.md) — 現在のロケール + ロケールスイッチャー
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/intlayer/getPathWithoutLocale.md) — このフックで使用される基礎的なユーティリティ

package/docs/ja/packages/vue-intlayer/exports.md

@@ -14,6 +14,9 @@ slugs:
   - vue-intlayer
   - exports
 history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "usePathnameユーティリティを追加"
   - version: 8.0.0
     date: 2026-01-21
     changes: "すべてのエクスポートのドキュメントを統一"
@@ -59,6 +62,7 @@ import "vue-intlayer";
 | `useDictionaryAsync`   | `useDictionary` と同様ですが、非同期の辞書を処理します。                                                                                | -                                                                                                                     |
 | `useDictionaryDynamic` | `useDictionary` と同様ですが、動的な辞書を処理します。                                                                                  | -                                                                                                                     |
 | `useLocale`            | 現在のロケールと、それを設定する関数を返します。                                                                                        | -                                                                                                                     |
+| `usePathname`          | ロケールセグメントが削除された現在のパス名 (pathname) を `ComputedRef<string>` として返します。`popstate` に反応します。                | [usePathname](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/vue-intlayer/usePathname.md)     |
 | `useRewriteURL`        | URL の書き換えを管理するクライアントサイドのコンポーザブル。ローカライズされた書き換えルールが存在する場合は自動的に URL を更新します。 | [useRewriteURL](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/vue-intlayer/useRewriteURL.md) |
 | `useIntl`              | 現在のロケールの Intl オブジェクトを返します。                                                                                          | -                                                                                                                     |
 | `useLoadDynamic`       | 動的辞書を読み込むためのコンポーザブル。                                                                                                | -                                                                                                                     |

package/docs/ja/packages/vue-intlayer/usePathname.md

@@ -0,0 +1,109 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: usePathname 関数のドキュメント | vue-intlayer
+description: vue-intlayer パッケージの usePathname 関数の使用方法について
+keywords:
+  - usePathname
+  - pathname
+  - locale
+  - Intlayer
+  - 国際化 (Internationalization)
+  - ドキュメント
+  - Vue
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - vue-intlayer
+  - usePathname
+history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "usePathnameユーティリティを追加"
+  - version: 8.2.0
+    date: 2026-06-22
+    changes: "履歴を初期化"
+author: aymericzip
+---
+
+# Vue インテグレーション: `usePathname` ドキュメント
+
+`usePathname` 関数は、ロケールセグメントが削除された現在のブラウザのパス名 (pathname) を Vue の `ComputedRef<string>` として返します。これは、ロケールプレフィックスを手動で削除することなく、ロケールを認識するナビゲーションを構築する（たとえば、どのナビゲーションアイテムがアクティブであるかを決定する）ために便利です。
+
+## Vue での `usePathname` のインポート
+
+```typescript
+import { usePathname } from "vue-intlayer";
+```
+
+## 概要
+
+`usePathname` は、`window.location.pathname` を読み取り、`getPathWithoutLocale` を介してロケールプレフィックスを削除し、ブラウザが `popstate` イベント（戻る/進むナビゲーション）を発生させるたびにその値を更新する Vue の算出参照 (computed ref) を作成します。取得した値は、Vue テンプレートやセットアップ関数で直接使用できます。
+
+## 使用方法
+
+```vue fileName="src/components/NavItem.vue"
+<script setup lang="ts">
+import { usePathname } from "vue-intlayer";
+
+const props = defineProps<{
+  href: string;
+  label: string;
+}>();
+
+const pathname = usePathname();
+</script>
+
+<template>
+  <a :href="href" :aria-current="pathname === href ? 'page' : undefined">
+    {{ label }}
+  </a>
+</template>
+```
+
+## 戻り値
+
+| タイプ                | 説明                                                                             |
+| --------------------- | -------------------------------------------------------------------------------- |
+| `ComputedRef<string>` | ロケールプレフィックスのない現在のパス名 (pathname) を含む Vue の Computed Ref。 |
+
+## 動作
+
+- **ロケールの削除 (Locale stripping)**: 先頭のロケールセグメントを削除します（例: `/ja/dashboard` → `/dashboard`）。
+- **リアクティブ**: `popstate` イベント（ブラウザの戻る / 進む操作）が発生するたびに値を更新します。
+- **SSR セーフ**: `window` が利用できない場合は `""` を返します。
+- **クリーンアップ (Cleanup)**: `popstate` リスナーは初期化時にグローバルに追加され、Vue のライフサイクル管理のおかげで、通常はコンポーネントごとに手動でクリーンアップする必要はありません。
+
+## 例
+
+```vue fileName="src/components/Sidebar.vue"
+<script setup lang="ts">
+import { usePathname } from "vue-intlayer";
+
+const links = [
+  { href: "/dashboard", label: "ダッシュボード" },
+  { href: "/settings", label: "設定" },
+];
+
+const pathname = usePathname();
+</script>
+
+<template>
+  <nav>
+    <a
+      v-for="link in links"
+      :key="link.href"
+      :href="link.href"
+      :style="{ fontWeight: pathname === link.href ? 'bold' : 'normal' }"
+    >
+      {{ link.label }}
+    </a>
+  </nav>
+</template>
+```
+
+## 関連事項
+
+- [`useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/vue-intlayer/useLocale.md) — 現在のロケール + ロケールスイッチャー
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/packages/intlayer/getPathWithoutLocale.md) — このフックで使用される基盤となるユーティリティ

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

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-12-13
+updatedAt: 2026-06-21
 title: Sync JSON プラグイン
 description: Intlayerの辞書をサードパーティのi18n JSONファイル（i18next、next-intl、react-intl、vue-i18nなど）と同期します。既存のi18nを維持しながら、Intlayerでメッセージの管理、翻訳、テストを行えます。
 keywords:
@@ -24,6 +24,9 @@ slugs:
   - sync-json
 youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
 history:
+  - version: 9.0.0
+    date: 2026-06-21
+    changes: "splitKeys オプションを追加（next-intl / react-intl の単一ファイルレイアウト向けに、トップレベルの名前空間キーごとに1つの辞書）"
   - version: 7.5.0
     date: 2025-12-13
     changes: "ICUおよびi18next形式のサポートを追加"
@@ -62,7 +65,63 @@ pnpm add -D @intlayer/sync-json-plugin
 npm i -D @intlayer/sync-json-plugin
 ```
 
-## クイックスタート
+## Plugins
+
+このパッケージは2つのプラグインを提供します：
+
+- `loadJSON`: JSONファイルをIntlayer辞書にロードします。
+  - このプラグインは、ソースからJSONファイルをロードし、Intlayer辞書にロードするために使用されます。コードベース全体をスキャンし、特定のJSONファイルを検索できます。
+    このプラグインは以下の場合に使用できます。
+    - JSONのロードに特定の場所を課すi18nライブラリ（例：`next-intl`、`i18next`、`react-intl`、`vue-i18n`など）を使用しているが、コンテンツ宣言をコードベースの好きな場所に配置したい場合。
+    - リモートソース（例：CMS、APIなど）からメッセージをフェッチし、JSONファイルにメッセージを保存したい場合。
+
+  > 内部的には、このプラグインはコードベース全体をスキャンし、特定のJSONファイルを検索してIntlayer辞書にロードします。
+  > このプラグインは出力と翻訳をJSONファイルに書き戻さないことに注意してください。
+
+- `syncJSON`: JSONファイルをIntlayer辞書と同期します。
+  - このプラグインは、JSONファイルをIntlayer辞書と同期するために使用されます。指定された場所をスキャンし、特定のJSONファイルのパターンに一致するJSONをロードできます。このプラグインは、別のi18nライブラリを使用しながらIntlayerの利点を得たい場合に便利です。
+
+## 両方のプラグインを使用する
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON, syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // 現在のJSONファイルをIntlayerの辞書と同期させる
+  plugins: [
+    /**
+     * src内のパターン {key}.i18n json に一致するすべてのJSONファイルをロードします
+     */
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      locale: Locales.ENGLISH,
+      priority: 1, // これらのJSONファイルが `./locales/en/${key}.json` のファイルよりも優先されるようにします
+      format: "intlayer", // JSONコンテンツのフォーマット
+    }),
+    /**
+     * ロケールディレクトリ内のJSONファイルに、出力と翻訳をロードして書き戻します
+     */
+    syncJSON({
+      format: "i18next",
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      priority: 0,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
+```
+
+## `syncJSON` plugin
+
+### クイックスタート
 
 `intlayer.config.ts`にプラグインを追加し、既存のJSON構造を指定します。
 
@@ -81,6 +140,7 @@ const config: IntlayerConfig = {
     syncJSON({
       // ロケールごと、名前空間ごとのレイアウト（例：next-intl、名前空間付きのi18next）
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "icu",
     }),
   ],
 };
@@ -91,14 +151,27 @@ export default config;
 代替案：ロケールごとに単一ファイル（i18next/react-intlのセットアップで一般的）：
 
 ```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale }) => `./locales/${locale}.json`,
-  }),
-];
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      format: "i18next",
+      source: ({ locale }) => `./locales/${locale}.json`,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
 ```
 
-### 動作の仕組み
+#### 動作の仕組み
 
 - 読み込み：プラグインは`source`ビルダーからJSONファイルを検出し、それらをIntlayerの辞書として読み込みます。
 - 書き込み：ビルドと補完の後、ローカライズされたJSONを同じパスに書き戻します（フォーマットの問題を避けるために末尾に改行を追加）。
@@ -112,6 +185,7 @@ syncJSON({
   location?: string, // オプションのラベル、デフォルト: "plugin"
   priority?: number, // コンフリクト解決のためのオプションの優先度、デフォルト: 0
   format?: 'intlayer' | 'icu' | 'i18next', // オプションのフォーマッター、Intlayerランタイム互換性のために使用
+  splitKeys?: boolean, // オプション、単一ファイルをトップレベルキーごとに1つの辞書に分割（自動検出）
 });
 ```
 
@@ -136,11 +210,43 @@ syncJSON({
 }),
 ```
 
-## 複数の JSON ソースと優先度
+#### `splitKeys` (boolean)
+
+**ファーストレベルのキーが名前空間である**単一のJSONファイルを、ファイル全体を保持する単一の辞書ではなく、トップレベルキーごとに1つの辞書にするかどうかを制御します。
+
+これは、`next-intl`や`react-intl`のようなライブラリの名前空間モデルと一致します。これらのライブラリでは、1つの`messages/{locale}.json`ファイルが、そのファーストレベルのキーによって複数の名前空間をグループ化し、それぞれが独立してアドレス指定されます（例：`useTranslations('Hero')`は`Hero`辞書に解決されます）。
+
+- `undefined` (デフォルト): **自動検出** — `source`パターンに`{key}`セグメントがない場合（1つのファイルがすべての名前空間を保持する場合）にファイルが分割され、それ以外の場合（キーごとに1つのファイル）は単一の辞書として保持されます。
+- `true`: 常に各トップレベルキーを独自の辞書に分割します。
+- `false`: 分割しません。ファイル全体が単一の辞書になります。
+
+単一の`messages/{locale}.json`ファイルが与えられた場合：
+
+```json fileName="messages/en.json"
+{
+  "Hero": { "title": "Full-stack developer" },
+  "Nav": { "work": "Work", "about": "About" },
+  "About": { "lead": "I build apps end to end." }
+}
+```
+
+```ts fileName="intlayer.config.ts"
+syncJSON({
+  format: "icu",
+  source: ({ locale }) => `./messages/${locale}.json`,
+  // splitKeys: true, // パターンに`{key}`セグメントがないため、暗黙的に有効
+}),
+```
+
+これにより、`Hero`、`Nav`、`About`の3つの辞書が生成され、`useTranslations('Hero')` (next-intl) が正しく解決されます。書き戻し時には、すべての名前空間が同じロケールごとのファイルに再結合されます。
+
+> `source`に明示的な`{key}`セグメントを保持している場合（例：`./locales/${locale}/${key}.json`）、各ファイルはすでに1つの名前空間であるため、分割はデフォルトで無効になります。
+
+### 複数の JSON ソースと優先度
 
 複数の `syncJSON` プラグインを追加して異なる JSON ソースを同期することができます。これは、複数の i18n ライブラリや異なる JSON 構造をプロジェクトで使用している場合に便利です。
 
-### 優先度システム
+#### 優先度システム
 
 複数のプラグインが同じ辞書キーを対象とする場合、`priority` パラメータがどのプラグインが優先されるかを決定します:
 
@@ -189,73 +295,140 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-### コンフリクト解決
+## Load JSON plugin
 
-同じ翻訳キーが複数のJSONソースに存在する場合：
+### クイックスタート
 
-1. 最も優先度の高いプラグインが最終的な値を決定します
-2. 優先度の低いソースは、欠落しているキーのフォールバックとして使用されます
-3. これにより、レガシー翻訳を維持しつつ、新しい構造へ段階的に移行できます
+`intlayer.config.ts`にプラグインを追加して、既存のJSONファイルをIntlayer辞書として取り込みます。このプラグインは読み取り専用です（ディスクへの書き込みは行いません）：
 
-## 統合
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
 
-以下は一般的なマッピング例です。ランタイムは変更せず、プラグインのみを追加してください。
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
 
-### i18next
+  plugins: [
+    // ソースツリー内のどこにでも配置されたJSONメッセージを取り込む
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      // プラグインインスタンスごとに単一のロケールをロード（設定のdefaultLocaleにデフォルト設定）
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
 
-典型的なファイル構成: `./public/locales/{locale}/{namespace}.json` または `./locales/{locale}/{namespace}.json`。
+export default config;
+```
+
+代替案：ロケールごとのレイアウト、読み取り専用（選択されたロケールのみがロードされます）：
 
 ```ts fileName="intlayer.config.ts"
-import { syncJSON } from "@intlayer/sync-json-plugin";
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
 
-export default {
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
   plugins: [
-    syncJSON({
-      format: "i18next",
+    loadJSON({
+      // このパターンからはLocales.FRENCHのファイルのみがロードされます
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      locale: Locales.FRENCH,
     }),
   ],
 };
+
+export default config;
 ```
 
-### next-intl
+### 動作の仕組み
 
-ロケールごとのJSONメッセージ（多くの場合 `./messages/{locale}.json`）または名前空間ごと。
+- 検出：`source`ビルダーからグロブを構築し、一致するJSONファイルを収集します。
+- 取り込み：各JSONファイルを提供された`locale`を持つIntlayer辞書としてロードします。
+- 読み取り専用：出力ファイルの書き込みやフォーマットは行いません。ラウンドトリップ同期が必要な場合は`syncJSON`を使用してください。
+- 自動補完対応：`fill`パターンを定義し、`intlayer content fill`がCLI経由で不足しているキーを埋めることができます。
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,
-  }),
-];
+### API
+
+```ts
+loadJSON({
+  // JSONへのパスを構築します。構造にロケールセグメントがない場合、`locale`はオプションです
+  source: ({ key, locale }) => string,
+
+  // このプラグインインスタンスによってロードされる辞書のターゲットロケール
+  // デフォルトは configuration.internationalization.defaultLocale
+  locale?: Locale,
+
+  // ソースを識別するためのオプションのラベル
+  location?: string, // デフォルト: "plugin"
+
+  // 他のソースとのコンフリクト解決に使用される優先度
+  priority?: number, // デフォルト: 0
+
+  // JSONコンテンツのオプションのフォーマッター
+  format?: 'intlayer' | 'icu' | 'i18next', // デフォルト: 'intlayer'
+
+  // 単一ファイルをトップレベルキーごとに1つの辞書に分割（自動検出）
+  splitKeys?: boolean,
+});
 ```
 
-参照: `docs/ja/intlayer_with_next-intl.md`。
+#### `format` ('intlayer' | 'icu' | 'i18next')
 
-### react-intl
+JSONファイルをロードする際に辞書コンテンツに使用するフォーマッターを指定します。これにより、さまざまなi18nライブラリと互換性のある異なるメッセージフォーマット構文を使用できます。
 
-ロケールごとに単一のJSONが一般的:
+- `'intlayer'`: デフォルトのIntlayerフォーマッター（デフォルト）。
+- `'icu'`: ICUメッセージフォーマットを使用します（react-intl、vue-i18nなどのライブラリと互換性があります）。
+- `'i18next'`: i18nextメッセージフォーマットを使用します（i18next、next-i18next、Solid-i18nextと互換性があります）。
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale }) => `./locales/${locale}.json`,
-  }),
-];
+**例：**
+
+```ts
+loadJSON({
+  source: ({ key }) => `./src/**/${key}.i18n.json`,
+  locale: Locales.ENGLISH,
+  format: "icu", // 互換性のためにICUフォーマットを使用
+}),
 ```
 
-### vue-i18n
+#### `splitKeys` (boolean)
 
-ロケールごと、またはネームスペースごとに単一ファイルを使用する場合：
+[`syncJSON`](#splitkeys-boolean) と同じ動作です。単一のJSONファイルがファーストレベルのキーによって複数の名前空間をグループ化する場合、各トップレベルキーが独自の辞書になります。
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,
-  }),
-];
+- `undefined` (デフォルト): **自動検出** — `source`パターンに`{key}`セグメントがない場合に分割され、それ以外の場合は単一の辞書になります。
+- `true` / `false`: 分割を強制または無効にします。
+
+```ts
+loadJSON({
+  source: ({ locale }) => `./messages/${locale}.json`,
+  format: "icu",
+  // splitKeys auto-enabled: `Hero`、`Nav`、`About`などがそれぞれ辞書になります
+}),
 ```
 
+### Behavior and conventions
+
+- `source`マスクにロケールプレースホルダーが含まれている場合、選択された`locale`のファイルのみが取り込まれます。
+- マスクに`{key}`セグメントがない場合、ファイルの各トップレベルキーがデフォルトで独自の辞書になります（[`splitKeys`](#splitkeys-boolean)を参照）。代わりにファイル全体を単一の`index`辞書として読み込むには、`splitKeys: false`を設定します。
+- キーは、`source`ビルダーの`{key}`プレースホルダーを置換することでファイルパスから派生します。
+- プラグインは検出されたファイルのみを使用し、不足しているロケールやキーを捏造することはありません。
+- `fill`パスは`source`から推測され、CLI経由で不足している値を更新するために使用されます（オプトインした場合）。
+
+## Conflict resolution
+
+同じ翻訳キーが複数のJSONソースに存在する場合：
+
+1. 最も優先度の高いプラグインが最終的な値を決定します
+2. 優先度の低いソースは、欠落しているキーのフォールバックとして使用されます
+3. これにより、レガシー翻訳を維持しつつ、新しい構造へ段階的に移行できます
+
 ## CLI
 
 同期されたJSONファイルは他の `.content` ファイルとして扱われます。つまり、すべてのintlayerコマンドが同期されたJSONファイルに対して利用可能です。以下を含みます：
@@ -268,7 +441,7 @@ plugins: [
 
 See [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/cli/index.md) for more details.
 
-## 制限事項（現状）
+## Limitations (current)
 
 - サードパーティライブラリを対象とする場合、挿入や複数形/ICUのサポートはありません。
 - 非Intlayerランタイム向けのビジュアルエディタはまだ利用できません。

package/docs/ko/intlayer_with_adonisjs.md

@@ -59,24 +59,40 @@ See [Application Template](https://github.com/aymericzip/intlayer-adonis-templat
 
 `adonis-intlayer`를 사용하려면 npm을 사용하여 패키지를 설치하십시오.
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> `--interactive` 플래그는 선택 사항입니다. AI 에이전트인 경우 `intlayer-cli init`를 사용하세요.
+
+> 이 명령은 환경을 감지하고 필요한 패키지를 설치합니다. 예를 들어:
+
 ```bash packageManager="npm"
 npm install intlayer adonis-intlayer
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer adonis-intlayer
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer adonis-intlayer
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer adonis-intlayer
-bun x intlayer init
 ```
 
 ### 설정