@intlayer/docs 9.4.0-canary.0 → 9.4.1

package/docs/ja/readme.md

@@ -225,8 +225,8 @@ Intlayer の包括的なドキュメントを探索し、Intlayer の使い始
   <li><a href="https://intlayer.org/doc/environment/vite-and-vue" rel=''>Vite + Vue</a></li>
   <li><a href="https://intlayer.org/doc/environment/nuxt-and-vue" rel=''>Vite + Nuxt</a></li>
   <li><a href="https://intlayer.org/doc/environment/vite-and-solid" rel=''>Vite + Solid</a></li>
-  <li><a href="https://intlayer.org/doc/environment/angular" rel=''>Angular</a></li>
-  <li>
+  <li><a href="https://intlayer.org/doc/environment/solid-start" rel=''>Solid Start</a></li>
+  <li><a href="https://intlayer.org/doc/environment/angular" rel=''>Angular</a></li>  <li>
      <a href="https://intlayer.org/doc/environment/express" rel=''>バックエンド</a>
      <ul>
       <li><a href="https://intlayer.org/doc/environment/express" rel=''>Express</a></li>
@@ -234,6 +234,7 @@ Intlayer の包括的なドキュメントを探索し、Intlayer の使い始
       <li><a href="https://intlayer.org/doc/environment/fastify" rel=''>Fastify</a></li>
       <li><a href="https://intlayer.org/doc/environment/adonisjs" rel=''>AdonisJS</a></li>
       <li><a href="https://intlayer.org/doc/environment/hono" rel=''>Hono</a></li>
+      <li><a href="https://intlayer.org/doc/environment/elysia" rel=''>Elysia</a></li>
     </ul>
   </li>
 </ul>

package/docs/ja/releases/v6.md

@@ -118,6 +118,8 @@ export default config;
 
 コンテンツファイルの `autoFill` フィールドを使用して、辞書ごとに微調整を行うことも可能です。詳細は `doc/autoFill` および `doc/dictionary/content_file` を参照してください。
 
+`autoFill`フィールドを使用して、コンテンツファイル内の辞書ごとに微調整することもできます。Intlayerはまず辞書ごとの設定を考慮し、その後グローバル設定にフォールバックします。完全なリファレンスは[Auto-fill](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/autoFill.md)と[Content file reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/dictionary/content_file.md)を参照してください。
+
 ---
 
 ## fill コマンド: より安全なデフォルト設定
@@ -175,6 +177,20 @@ CIの例は[CI/CD](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja
 
 ---
 
+MCP サーバーを新しい機能に対応するように更新しました。
+
+- 自動入力
+- 欠落している翻訳のテスト
+- ライブアップデート
+- ロギング
+- 検証
+- マイグレーションノート
+- ドキュメンテーション
+
+> MCP server は Intlayer を使用するプロジェクトの自動化に役立ちます。自動生成されたコードの欠落している翻訳をテストします。config を理解し、IDE に Intlayer のドキュメントを組み込むのに役立ちます。
+
+---
+
 ## パフォーマンス: 10倍高速化
 
 - ローカルおよびリモート辞書の並列解決
@@ -296,8 +312,6 @@ bun x intlayer live --with 'vite preview'
 
 完全なガイダンスについては、[CMSとライブ同期](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/intlayer_CMS.md)および[設定](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/configuration.md)を参照してください。
 
----
-
 ## Turbopackでファイルを監視するための並列プロセス
 
 `next dev --turbopack`コマンドを使用してNext.js 14以上でTurbopackを開発サーバーとして使用する場合、辞書の変更はデフォルトでは自動的に検出されません。

package/docs/ja/self_hosting.md

@@ -19,6 +19,8 @@ author: aymericzip
 
 # Intlayerのセルフホスティング
 
+Intlayerはあなた自身のインフラストラクチャ上で実行できます。Intlayer Cloudアカウントは必要ありません。単一のオールインワンDockerイメージは、ダッシュボード、API、および必要なローカルデータストア（RedisとMinIO）をバンドルし、[s6-overlay](https://github.com/just-containers/s6-overlay)によって監視されています。
+
 Intlayerは、Intlayer Cloudアカウントを必要とせず、独自のインフラストラクチャ上で完全に実行できます。単一のコマンドで、本番環境に対応したスタックを起動します。
 
 ```sh
@@ -27,6 +29,8 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 インストーラーは `docker-compose.yml` と `.env` をダウンロードし、必要なシークレットを自動生成して、すべてのコンテナを `docker compose up -d` で起動します。
 
+唯一の外部依存関係は **MongoDB** です。バックエンドは提供する MongoDB **Atlas** クラスターに接続します。その他すべてはコンテナ内で実行されます。
+
 ## 目次
 
 <TOC/>
@@ -60,23 +64,77 @@ Chromium (Puppeteerのスクリーンショット生成に使用) はバック
 - ホスト上でポート `3000`、`3100`、`8025`、`9000`、`9001` が利用可能であること。
 - LinuxまたはmacOSホスト（またはWindows上のWSL2）。
 
+その他すべて — Bun、Redis、MinIO、Chromium — はイメージ内に含まれています。
+
 ---
 
 ## クイックスタート
 
+### 1. インストーラーを実行する
+
 ```sh
 curl -fsSL https://intlayer.org/install.sh | sh
 ```
 
-インストーラーの動作:
+Docker がインストールされており実行中であることを確認し、既に生成された `BETTER_AUTH_SECRET` と `S3_SECRET_ACCESS_KEY` を含む `./intlayer.env` を書き込み、イメージをプルします。コンテナを起動しません — バックエンドはデータベース認証情報がないとブートできません。
+
+インストーラーを再実行しても安全です。既存の `intlayer.env` は上書きされないため、アップグレードパスとしても機能します。
+
+### 2. 認証情報を入力する
+
+`intlayer.env` を開き、`TODO` でマークされている値を入力してください：
+
+```sh fileName="intlayer.env"
+DB_ID=<atlas-user>
+DB_MDP=<atlas-password>
+DB_CLUSTER=<cluster>.xxxxx.mongodb.net
+RESEND_API_KEY=<your-resend-key>
+```
+
+ファイルには、オプション機能のためのコメントアウトされたブロックも含まれています — [SMTP mailer](#global-mailer)、`OPENAI_API_KEY`、および OAuth プロバイダー。必要なものをコメント解除してください。
+
+> ファイルは `docker run --env-file` によって読み込まれ、クォートを削除せず、`=` の後のすべてを値として扱います。クォートなしの値を書き、コメントは独立した行に保つようにしてください。
+
+### 3. コンテナを起動する
+
+インストーラーが完了時に出力するコマンドは次の通りです:
+
+```sh
+docker run -d --name intlayer \
+  --restart unless-stopped \
+  -p 3000:3000 \
+  -p 3100:3100 \
+  -p 9000:9000 \
+  -p 9001:9001 \
+  -v intlayer-data:/data \
+  --env-file ./intlayer.env \
+  ghcr.io/aymericzip/intlayer-selfhost:latest
+```
+
+その後、**http://localhost:3000** を開きます。初回起動時はデータストアが初期化されるため、1 分ほど待ってください。
+
+> ダッシュボードは `localhost` で提供されます。[制限事項](#limitations)を参照してください。公開されているイメージではカスタムドメインはサポートされていません。
 
-1.  `docker` と `docker compose` が存在するかどうかを確認します。
-2.  `docker-compose.yml` と `.env.example` を `./intlayer/` にダウンロードします。
-3.  `.env` が存在しない場合、例をコピーし、`BETTER_AUTH_SECRET`、`S3_ACCESS_KEY_ID`、`S3_SECRET_ACCESS_KEY` 用に `openssl rand` を介してランダムなシークレットを生成します。
-4.  `docker compose pull` + `docker compose up -d` を実行します。
-5.  URLを表示します: ダッシュボード `:3000`、API `:3100`、メールUI `:8025`、MinIOコンソール `:9001`。
+### インストーラー設定
 
-スタックが起動したら、**http://localhost:3000** を開き、最初のIntlayerアカウントを作成してください。
+インストーラーは環境変数をいくつか読み込みます。`sh` にパイプされるため、`curl` ではなくシェルに環境変数を渡してください:
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | INTLAYER_ENV_FILE=./config/intlayer.env sh
+```
+
+| 変数                      | デフォルト                                    | 説明                                       |
+| ------------------------- | --------------------------------------------- | ------------------------------------------ |
+| `INTLAYER_IMAGE`          | `ghcr.io/aymericzip/intlayer-selfhost:latest` | プルするイメージ                           |
+| `INTLAYER_ENV_FILE`       | `./intlayer.env`                              | env ファイルの書き込み先                   |
+| `INTLAYER_CONTAINER_NAME` | `intlayer`                                    | コンテナー名                               |
+| `INTLAYER_DATA_VOLUME`    | `intlayer-data`                               | `/data` にマウントされた名前付きボリューム |
+| `INTLAYER_APP_PORT`       | `3000`                                        | ダッシュボードのホストポート               |
+| `INTLAYER_API_PORT`       | `3100`                                        | API のホストポート                         |
+| `INTLAYER_S3_PORT`        | `9000`                                        | MinIO S3 API のホストポート                |
+| `INTLAYER_CONSOLE_PORT`   | `9001`                                        | MinIO コンソールのホストポート             |
+
+> 4 つのポート変数は、`docker run` コマンドで出力されるマッピングの**ホスト**側のみを変更します。公開されたイメージには、`http://localhost:3000`、`http://localhost:3100`、`http://localhost:9000` がビルド時にダッシュボード bundle にコンパイルされているため、これらをリマップするとブラウザーが古いポートを指し続けます。独自のイメージをビルドしていない限り、デフォルトを保持してください — [制限事項](#limitations)を参照してください。
 
 ---
 
@@ -103,8 +161,6 @@ curl -fsSL https://intlayer.org/install.sh | sh
 | **minio**   | `minio/minio`                        | `9000` (S3), `9001` (コンソール) | アバターとスクリーンショット用のS3互換オブジェクトストレージ |
 | **mailpit** | `axllent/mailpit`                    | `1025` (SMTP), `8025` (ウェブUI) | ローカルトランザクションメールシンク                         |
 
-内部ポート (mongo, redis) は、デフォルトではホストに公開されません。
-
 > MinIOポート `9000` は、アップロードされたアセット (アバター、スクリーンショット) が `S3_PUBLIC_URL=http://localhost:9000/intlayer` から直接読み込まれるため、ブラウザから到達可能である必要があります。
 
 ---
@@ -160,8 +216,6 @@ curl -fsSL https://intlayer.org/install.sh | sh
 | `LINKEDIN_CLIENT_ID`, `LINKEDIN_CLIENT_SECRET`           | LinkedIn OAuthログイン                                                     |
 | `ATLASSIAN_CLIENT_ID`, `ATLASSIAN_CLIENT_SECRET`         | Atlassian OAuthログイン                                                    |
 
----
-
 ### グローバルメーラー
 
 デフォルトでは、すべてのトランザクションメールは `RESEND_API_KEY` を使用して Resend 経由で送信されます。セルフホストされたデプロイメントでは、パスワードリセットやマジックリンクなどの非組織メールを含む**すべての**メールを、環境変数で設定されたグローバルメーラー経由でルーティングできます。
@@ -247,16 +301,8 @@ const { data: dictionaries } = await dictionaryEndpoint(cms).getDictionaries();
 
 ## アップグレード
 
-既存のデプロイメントでインストーラーを再実行すると、ローリングアップグレードが実行されます。
-
-```sh
-curl -fsSL https://intlayer.org/install.sh | sh
-```
-
 これにより、最新のイメージがプルされ、`docker compose pull && docker compose up -d` でコンテナが再起動されます。既存のボリューム (`mongo-data`、`redis-data`、`minio-data`) は保持され、データ損失はありません。
 
-`./intlayer/` ディレクトリ内で手動でアップグレードするには:
-
 ```sh
 docker compose pull
 docker compose up -d
@@ -320,14 +366,12 @@ docker compose logs mongo
 docker compose logs redis
 ```
 
+ログの上部付近で `MongoDB connection error` を探してください。
+
 ### メールが送信されない
 
 デフォルトでは、すべての送信メールはMailpitによって捕捉されます。送信されたメッセージを確認するには、`http://localhost:8025` を開いてください。実際のメールを送信するには、`.env` で `MAIL_PROVIDER=resend` と `RESEND_API_KEY=<your-key>` を設定し、バックエンドを再起動します。
 
-```sh
-docker compose restart backend
-```
-
 ### MinIOバケットが見つからない
 
 `minio-init` ワンショットサービスが実行されなかった場合 (またはMinIOが準備できる前に実行された場合) は、手動でバケットを作成してください。

package/docs/ko/analytics.md

@@ -123,17 +123,6 @@ export default config;
 
 `@intlayer/analytics`를 제거하는 것은 `enabled: false`와 동일한 효과를 냅니다. 전체 필드 목록은 [구성 레퍼런스](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)를 참고하세요.
 
-## 프레임워크 지원
-
-Analytics는 `react-intlayer`의 공유된 `IntlayerProvider`와 연결되어 있으므로, 이 Provider가 사용되는 곳이라면 어디서든 바로 사용할 수 있습니다:
-
-| 프레임워크                                               | 상태                                                                                                  |
-| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| React                                                    | ✅ 지원됨                                                                                             |
-| Next.js (`next-intlayer`)                                | ✅ 지원됨 (`react-intlayer`를 통해)                                                                   |
-| React Native / Expo (`react-native-intlayer`)            | ✅ 지원됨 (`react-intlayer`를 통해)                                                                   |
-| Vue, Svelte, Angular, Solid, Preact, Lit, Astro, Vanilla | 🚧 계획됨 — `@intlayer/editor` 배포 패턴을 따르는 동일한 클라이언트, 프로바이더 레벨 바인딩 제공 예정 |
-
 ## 사용법
 
 ### 자동 프로바이더 레벨 추적
@@ -177,6 +166,34 @@ const CTAButton = () => {
 
 ### 클라이언트 측에서 변형 해결(Resolving a variant)
 
+  </Tab>
+</Tabs>
+
+가중치는 선택 사항입니다. 각 변형에 대해 하나씩 전달하여 분할을 조정할 수 있습니다. 예: `useExperiment("homepage-hero", ["default", "black_friday"], [9, 1])`.
+
+자식은 일치하는 사전의 [Variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/variants.md)를 읽습니다:
+
+```tsx fileName="HeroBanner.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export const HeroBanner = ({ variant }: { variant: string }) => {
+  const { headline, cta } = useIntlayer("hero-banner", { variant });
+
+  return (
+    <section>
+      <h1>{headline}</h1>
+      <a>{cta}</a>
+    </section>
+  );
+};
+```
+
+> **자식** 컴포넌트에서 variant를 읽는 것이 React 외부에서 작동하게 하는 원리입니다: Vue, Svelte, Solid, Angular에서는 `useIntlayer`에 전달된 selector가 컴포넌트 설정 시점에 캡처되므로, 읽기는 variant가 알려진 후에만 마운트되는 컴포넌트에서 발생해야 합니다.
+
+실험이 단일 사전이 아닌 전체 페이지를 포함하는 경우, 변형을 대신 제공자에게 끌어올려야 합니다 — [Ambient variant](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/variants.md#ambient-variant)를 참조하세요. 그러면 아래의 모든 `useIntlayer`는 호출 사이트 변경 없이 이에 대해 해결됩니다.
+
+컴포넌트 외부에서 raw assignment가 필요하면 client에 직접 접근하세요:
+
 ```tsx fileName="useHeroVariant.ts" codeFormat="tsx"
 import { getGlobalAnalyticsClient } from "@intlayer/analytics/client";
 
@@ -187,6 +204,8 @@ const variant = client?.getVariant("homepage-hero", [
 ]);
 ```
 
+> `getVariant`는 할당만 수행하며, 노출을 기록하지 않습니다. 대신 `useExperiment()`을 사용하세요. 그렇지 않으면 전환율의 분모가 없습니다.
+
 ## 프라이버시 & 성능
 
 - **설계상 익명(Anonymous by design)**: 세션은 회전하는(rotating) ID로 식별되며, 백엔드는 해당 ID의 **SHA-256 해시**만 저장합니다 — 원시 ID나 IP 주소는 절대 저장하지 않습니다.
@@ -236,6 +255,8 @@ const cms = createIntlayerCMS();
 const { data: audience } = await analyticsEndpoint(cms).getAudience(30);
 ```
 
+> **서버 측에서만 사용.** `createIntlayerCMS()`는 `clientId` + `clientSecret`으로 인증하며, 이 시크릿은 브라우저에서 절대 사용 불가능합니다 — 이 코드가 브라우저에서 실행되면 인증되지 않은 요청을 발급합니다. 라우트 핸들러, 서버 액션 또는 스크립트에 유지하세요.
+
 ## 유용한 링크
 
 - [Dynamic Dictionaries - Collections & Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dynamic_dictionaries/index.md)

package/docs/ko/benchmark/tanstack.md

@@ -194,6 +194,8 @@ GitHub 스타는 프로젝트의 인기, 커뮤니티 신뢰 및 장기적인
 
 `Tolgee`는 앞에서 언급한 많은 문제들을 해결합니다. 비슷한 접근 방식을 가진 다른 도구들보다 시작하기 더 어렵다고 느꼈습니다. 타입 안전성을 제공하지 않아 컴파일 시점에 누락된 키를 찾는 것도 매우 어렵습니다. 누락된 키 감지 기능을 추가하기 위해 Tolgee의 API를 나의 API로 래핑해야 했습니다.
 
+이 패키지는 상당히 무거운 편입니다 (~11.1kb, 이는 `react-intlayer`의 2배 이상입니다).
+
 TanStack Start에서도 반응성 문제가 있었습니다: 로케일 변경 시 프로바이더를 강제 재렌더링하고 로케일 변경 이벤트를 구독하여 다른 언어로의 로딩이 올바르게 작동하도록 해야 했습니다.
 
 **(use-intl)** (`use-intl@4.9.1`):
@@ -208,6 +210,8 @@ TanStack Start에서는 Next.js 전용 함정(`setRequestLocale`, 정적 렌더
 
 여전히 `t('a.b.c')` 위에 구축된 스택과 동일한 주요 단점을 공유합니다: 최적화는 가능하지만 시간이 매우 많이 소요되며, 대규모 프로젝트는 나쁜 관행(네임스페이스 + 동적 로딩 + 타입)에 빠질 위험이 있습니다.
 
+이 패키지는 특히 무겁습니다 (~17.3kb, 이는 `react-intlayer`의 약 3.5배입니다).
+
 메시지 형식도 다릅니다: `use-intl`은 ICU MessageFormat을 사용하는 반면, `i18next`는 자체 형식을 사용하므로 이들을 섞어서 사용하면 도구 기술이나 마이그레이션이 복잡해집니다.
 
 **(Lingui)** (`@lingui/core@5.3.0`):
@@ -218,6 +222,8 @@ TanStack Start에서는 Next.js 전용 함정(`setRequestLocale`, 정적 렌더
 
 `react-intl`은 Format.js 팀의 성능 중심 구현입니다. DX는 여전히 장황합니다: `const intl = useIntl()` + `intl.formatMessage({ id: "xx.xx" })`는 복잡성과 추가 JavaScript 작업을 가중시키고 글로벌 i18n 인스턴스를 React 트리의 많은 노드에 묶어둡니다.
 
+패키지도 무겁습니다(~14.4kb, 이는 `react-intlayer`의 약 3배 정도).
+
 ### 4 - 추천 사항
 
 이 TanStack Start 벤치마크에는 `next-translate`(Next.js 플러그인 + `getStaticProps`)에 상응하는 직접적인 대안이 없습니다. 성숙한 에코시스템과 `t()` API를 진정으로 원하는 팀에게는 `react-i18next`와 `use-intl`이 "합리적인" 선택으로 남겠지만, 누수를 피하기 위해 최적화하는 데 많은 시간을 투자할 것을 각오해야 합니다.

package/docs/ko/cli/ci.md

@@ -128,6 +128,8 @@ bun x intlayer ci fill --verbose --mode complete
 
 ### CI/CD 파이프라인에서 사용
 
+`intlayer init`을 실행하면 즉시 사용 가능한 두 가지 GitHub Actions workflow를 생성합니다 ([Scaffolded GitHub Actions](#scaffolded-github-actions) 참조). 아래 예제는 monorepo에서 `ci` 명령어를 사용한 동등한 설정을 보여주며, 여기서 자격증명은 `INTLAYER_PROJECT_CREDENTIALS`에서 프로젝트별로 주입됩니다.
+
 CI/CD 구성(예: GitHub Actions, GitLab CI)에서 `INTLAYER_PROJECT_CREDENTIALS`를 비밀 값으로 설정합니다:
 
 ```yaml

package/docs/ko/cli/doc-review.md

@@ -91,8 +91,16 @@ bun x intlayer doc review
 
 - **`--log`**: 로그 전용 모드. AI로 번역하지 않고, 대신 다른 에이전트가 번역을 생성할 수 있도록 기본 및 대상 로케일에 대해 주의가 필요한 블록(줄 번호 및 내용 포함)을 기록합니다.
 
+- **`apply`**: Translate diverging blocks and provide the complete updated file in Korean (ko)
+- **`report`**: Log blocks needing attention with line numbers and content (no AI translation)
+- **`synthesis`**: Skip per-block output and provide only a final recap of up-to-date vs. documents needing edits
+
   > 예시: `npx intlayer doc review --log`
 
+> 예시: `npx intlayer doc review --mode synthesis`
+
+어떤 모드이든, 실행은 기본 문서와 일치하는 문서와 편집할 블록이 남아 있는 문서를 나열하는 종합 보고서로 끝납니다.
+
 **출력 옵션:**
 
 - **`--locales [locales...]`**: 문서를 검토할 대상 로케일입니다.

package/docs/ko/cli/fill.md

@@ -39,14 +39,6 @@ bun x intlayer fill
 
 이 명령어는 누락된 번역, 구조적 불일치 또는 타입 불일치와 같은 잠재적인 문제를 찾기 위해 콘텐츠 선언 파일을 분석합니다. 문제가 발견되면, **intlayer fill**은 사전을 일관되고 완전하게 유지하기 위해 업데이트를 제안하거나 적용합니다.
 
-주요 사항:
-
-- AI 모델의 컨텍스트 창 제한 내에서 유지하기 위해 큰 JSON 파일을 청크로 분할합니다.
-- 출력 형식이 잘못된 경우 번역을 재시도합니다.
-- 번역 정확도를 향상시키기 위해 애플리케이션 및 파일별 컨텍스트를 통합합니다.
-- 기존 번역을 덮어쓰지 않아 기존 번역을 보존합니다.
-- 큐 시스템을 사용하여 파일, 청크 및 로케일을 병렬로 처리하여 속도를 높입니다.
-
 ## 주요 포인트:
 
 - 대규모 JSON 파일을 청크로 분할하여 AI 모델의 컨텍스트 윈도우 제한 내에 유지합니다.

package/docs/ko/cli/index.md

@@ -127,6 +127,8 @@ Intlayer는 여러 설정 파일 형식을 허용합니다:
 
 - **[로그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/login.md)** - Intlayer CMS에 인증하고 액세스 자격 증명을 가져옵니다.
 
+> `intlayer login`은 모든 자격 있는 명령어가 사용하는 **액세스 키**(`clientId` / `clientSecret`)를 발급합니다. 시크릿은 서버 측 자격증명이며 클라이언트 번들에 도달하지 않습니다 — [액세스 키 안전 유지](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/login.md#keeping-the-access-key-safe)를 참조하세요.
+
 ### 핵심 명령어
 
 - **[딕셔너리 빌드 (Build)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/build.md)** - 콘텐츠 선언 파일에서 딕셔너리를 빌드합니다.

package/docs/ko/cli/login.md

@@ -122,6 +122,34 @@ INTLAYER_CLIENT_SECRET=your_client_secret
 }
 ```
 
+## 접근 키 안전하게 유지하기
+
+`intlayer login`은 **접근 키**를 발급합니다: 모든 인증된 명령어(`push`, `pull`, `fill`, `configuration push`, `live`, …)가 인증할 때 사용하는 `clientId` / `clientSecret` 쌍입니다.
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+};
+
+export default config;
+```
+
+> **`clientSecret`은 서버 측 자격 증명입니다.** 프로젝트 범위의 전체 API 접근 권한을 부여합니다 — 사전, 프로젝트 및 조직을 읽고 쓸 수 있습니다. `.env`(git에서 무시됨) 또는 CI 비밀 저장소에 보관하고, 절대 구성 파일에 직접 작성하지 마세요.
+
+Intlayer는 이를 단지 문서화하는 것이 아니라 강제합니다:
+
+- `clientSecret`은 **번들러가 인라인하는 구성에서 제거**되므로 어떤 프레임워크 통합을 사용하든 브라우저 번들에 도달할 수 없습니다. 이는 런타임에 환경에서 서버 측에서만 읽힙니다.
+- `clientId`는 다릅니다: 이는 **공개** 프로젝트 키이며 안전하게 배포할 수 있으며, [`@intlayer/analytics`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/analytics.md#how-events-are-authenticated)에서 수명이 짧은 수집 전용 토큰을 얻기 위해 사용됩니다.
+
+`clientId`를 주석 처리하는 것만으로도 환경 변수가 여전히 정의되어 있을 때도 모든 인증된 동작 — 원격 사전 가져오기, CMS 접근, 분석 — 을 비활성화하기에 충분합니다.
+
+CI 파이프라인의 경우, 자격 증명을 유지하는 대신 단일 실행 기간 동안 주입하는 [`ci` 명령어](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/ci.md)를 선호하세요.
+
 ## 수동 구성
 
 브라우저가 자동으로 열리지 않는 경우, 터미널에 표시된 URL을 수동으로 방문할 수 있습니다.

package/docs/ko/cli/push.md

@@ -104,21 +104,6 @@ bun x intlayer dictionary push
 - **`--git-diff-current`**: git diff의 현재 참조를 지정합니다 (기본값 `HEAD`).
 - **`--uncommitted`**: 커밋되지 않은 변경 사항을 포함합니다.
 - **`--unpushed`**: 푸시되지 않은 변경 사항을 포함합니다.
-- **`--untracked`**: 추적되지 않은 파일을 포함합니다.
-
-- **`--build`**: 푸시 전에 사전을 빌드하여 콘텐츠가 최신 상태인지 확인합니다. true는 빌드를 강제 실행하고, false는 빌드를 건너뛰며, undefined는 빌드 캐시를 사용하도록 허용합니다.
-
-**로그 옵션:**
-
-- **`--verbose`**: 디버깅을 위한 자세한 로깅을 활성화합니다. (기본값은 CLI에서 true)
-
-**Git 옵션:**
-
-- **`--git-diff`**: 기본 브랜치(기본값: `origin/main`)와 현재 브랜치(기본값: `HEAD`) 간의 변경 사항이 포함된 사전에만 실행합니다.
-- **`--git-diff-base`**: git diff의 기준 참조를 지정합니다. (기본값: `origin/main`)
-- **`--git-diff-current`**: git diff의 현재 참조를 지정합니다. (기본값: `HEAD`)
-- **`--uncommitted`**: 커밋되지 않은 변경 사항을 포함합니다.
-- **`--unpushed`**: 푸시되지 않은 변경 사항을 포함합니다.
 - **`--untracked`**: 추적되지 않은 파일을 포함합니다.
 
   > 예시: `npx intlayer dictionary push --git-diff --git-diff-base origin/main --git-diff-current HEAD`

package/docs/ko/compat/next-i18next.md

@@ -22,6 +22,8 @@ author: aymericzip
 
 # next-i18next에서 Intlayer로 마이그레이션
 
+완전하고 상세한 단계별 튜토리얼을 보려면 전체 [next-i18next 마이그레이션 가이드](../migration_from_next-i18next_to_intlayer.md)를 참고하세요.
+
 Intlayer는 모든 Next.js Pages Router 및 App Router 구현을 투명하게 처리합니다. adapter를 사용하면 코드를 전혀 다시 작성하지 않고 `next-i18next` 구현을 마이그레이션할 수 있습니다.
 
 ## 해야 할 일

package/docs/ko/compiler.md

@@ -40,6 +40,12 @@ author: aymericzip
 
 ## Intlayer 컴파일러를 사용하는 이유
 
+- **자동화**: 사전에 콘텐츠를 수동으로 복사-붙여넣기하는 작업을 제거합니다.
+
+- **Speed**: 최적화된 콘텐츠 추출로 빌드 프로세스를 빠르게 유지합니다.
+
+- **개발자 경험**: 콘텐츠 선언을 사용 위치에 가깝게 유지하여 유지보수성을 개선합니다.
+
 - **자동화**: 콘텐츠를 사전에 수동으로 복사하여 붙여넣는 작업을 제거합니다.
 - **속도**: 빌드 프로세스가 빠르게 유지되도록 최적화된 콘텐츠 추출을 제공합니다.
 - **개발자 경험**: 콘텐츠 선언을 사용되는 위치에 그대로 유지하여 유지보수성을 향상시킵니다.
@@ -54,6 +60,8 @@ author: aymericzip
 - **휴리스틱 모호성**: 컴파일러는 사용자 지향 콘텐츠와 애플리케이션 로직(예: `className="active"`, 상태 코드, 제품 ID)을 추측해야 합니다. 복잡한 코드베이스에서는 이것이 오탐지 또는 누락된 문자열로 이어질 수 있으며, 수동 주석 및 예외 처리가 필요합니다.
 - **정적 추출만**: 컴파일러 기반 추출은 정적 분석에 의존합니다. 런타임에만 존재하는 문자열(API 오류 코드, CMS 필드 등)은 컴파일러만으로는 발견하거나 번역할 수 없으므로 여전히 보완적인 런타임 i18n 전략이 필요합니다.
 
+- **정적 전용 추출**: 컴파일러 기반 추출은 정적 분석에 의존합니다. 런타임에만 존재하는 문자열(API 오류 코드, CMS 필드 등)은 컴파일러만으로는 발견하거나 번역할 수 없으므로, 여전히 보완적인 런타임 i18n 전략이 필요합니다.
+
 더 깊은 아키텍처 비교를 위해서는 블로그 게시물 [Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ko/compiler_vs_declarative_i18n.md)을 참조하세요.
 
 대안으로, 콘텐츠에 대한 완전한 제어를 유지하면서 i18n 프로세스를 자동화하기 위해 Intlayer는 자동 추출 명령 `intlayer extract`([CLI 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/extract.md) 참조) 또는 Intlayer VS Code 확장의 `Intlayer: extract content to Dictionary` 명령([VS Code 확장 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/vs_code_extension.md) 참조)도 제공합니다.
@@ -94,6 +102,8 @@ export default defineConfig({
 });
 ```
 
+> 독립형 `intlayerCompiler()` 플러그인은 고급 설정을 위해 여전히 내보내집니다. `intlayer()`와 함께 등록하는 것은 안전합니다 — 컴파일러는 자신을 중복 제거하고 한 번만 실행됩니다.
+
 See complete tutorial: [Intlayer Compiler with Vite+React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_with_vite+react_compiler.md)
 
 #### 프레임워크 지원
@@ -104,6 +114,10 @@ Vite 플러그인은 다양한 파일 유형을 자동으로 감지하고 처리
 - **Vue**: `@intlayer/vue-compiler`가 필요합니다.
 - **Svelte**: `@intlayer/svelte-compiler`가 필요합니다.
 
+- **Vue**: `@intlayer/vue-compiler`가 필요합니다.
+
+- **Svelte**: `@intlayer/svelte-compiler`가 필요합니다.
+
 사용하는 프레임워크에 맞는 컴파일러 패키지를 반드시 설치하세요:
 
 ```bash

package/docs/ko/configuration.md

@@ -732,8 +732,6 @@ export default config;
 | `liveSyncPort`               | Live Sync 서버 포트.                                                                                                                                              | `number`                          | `4000`                              | `4000`                                                                                          |                                                                                                                                                                                                                      |
 | `liveSyncURL`                | Live Sync 서버 URL.                                                                                                                                               | `string`                          | `'http://localhost:{liveSyncPort}'` | `'https://example.com'`                                                                         | 기본적으로 localhost를 가리키며, 원격 Live Sync 서버로 변경할 수 있습니다.                                                                                                                                           |
 
----
-
 ### 애널리틱스 구성 (Analytics)
 
 Intlayer 애널리틱스와 관련된 설정을 정의합니다: 사용자에게 실제로 표시되는 콘텐츠(페이지 뷰, 콘텐츠 노출)를 수집하고 콘텐츠에 대한 A/B 테스트를 지원합니다.
@@ -983,8 +981,15 @@ Intlayer의 내부 경로 및 출력 결과와 관련된 설정입니다. 이러
 
 ### 딕셔너리 구성 (Dictionary)
 
+사전 작업을 제어하는 설정입니다. 자동 채우기 동작 및 컨텐츠 생성을 포함합니다.
+
 자동 채우기 동작 및 콘텐츠 생성을 포함하여 딕셔너리 작업을 제어하기 위한 옵션입니다.
 
+1. **기본값**: 콘텐츠 선언 파일을 생성할 때 기본값 정의
+2. **폴백 동작**: 특정 필드가 정의되지 않을 때 폴백 값을 제공하여 사전 작업 동작을 전역적으로 정의할 수 있음
+
+content declaration 파일 및 configuration 값이 어떻게 적용되는지에 대한 자세한 내용은 [Content File Documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/dictionary/content_file.md)을 참조하세요.
+
 | 필드                        | 설명                                                                                                                                                   | 타입                                                                                                            | 기본값       | 예시                                                                                        | 참고                                                                                                                                                                                                                                                                                                                                                                           |
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `fill`                      | 자동 채우기(AI 번역) 출력 파일 생성을 제어합니다.                                                                                                      | `boolean` &#124; <br/> `FilePathPattern` &#124; <br/> `Partial<Record<Locale, boolean &#124; FilePathPattern>>` | `true`       | `{ en: '/locales/en/{{key}}.json', fr: ({ key }) => '/locales/fr/${key}.json', es: false }` | • `true`: 기본 경로(소스와 동일한 파일).<br/>• `false`: 비활성화.<br/>• 문자열/함수 패턴은 로케일별 생성을 허용합니다.<br/>• 로케일별 객체: 각 로케일이 자체 패턴을 가지며 `false`는 해당 로케일을 제외합니다.<br/>• `{{locale}}`을 포함하면 로케일별 생성이 가능합니다.<br/>• 딕셔너리 수준의 `fill` 설정은 항상 이 글로벌 설정보다 우선합니다.                               |
@@ -1024,8 +1029,6 @@ Intlayer 로그 출력 맞춤설정을 위한 설정입니다.
 | `mode`   | 로거 모드를 지정합니다.    | `'default'` &#124; <br/> `'verbose'` &#124; <br/> `'disabled'` | `'default'`     | `'verbose'`      | • `'verbose'`: 디버깅을 위해 더 많은 정보를 기록합니다.<br/>• `'disabled'`: 모든 로깅을 비활성화합니다. |
 | `prefix` | 모든 로그 메시지의 접두사. | `string`                                                       | `'[intlayer] '` | `'[my prefix] '` |                                                                                                         |
 
----
-
 ### AI 구성 (AI)
 
 프로바이더, 모델 및 API 키를 포함하여 Intlayer 내의 AI 기능을 관리하기 위한 설정입니다.
@@ -1065,8 +1068,6 @@ Intlayer는 최대의 유연성을 보장하기 위해 다양한 AI 프로바이
 | `baseURL`            | AI API에 대한 기본 URL.                                                                                          | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                             | 없음        | `'https://api.openai.com/v1'` <br/> `'http://localhost:5000'` | 로컬 또는 맞춤형 AI API 엔드포인트를 가리킬 수 있습니다.                                                                                                                                   |
 | `dataSerialization`  | AI 기능에 대한 데이터 직렬화 형식.                                                                               | `'json'` &#124; <br/> `'toon'`                                                                                                                                                                                                                                                                                                                                                                                                                       | `undefined` | `'toon'`                                                      | • `'json'`: 기본값, 안정적임; 더 많은 토큰 소비.<br/>• `'toon'`: 더 적은 토큰 소모, 덜 안정적임.<br/>• 모델에 로직 실행을 위한 추가 파라미터(추론 노력(reasoning effort) 등)를 전달합니다. |
 
----
-
 ### 빌드 구성 (Build)
 
 Intlayer가 애플리케이션의 국제화를 최적화하고 컴파일하는 방법을 제어하기 위한 설정입니다.
@@ -1104,8 +1105,6 @@ Intlayer가 애플리케이션의 국제화를 최적화하고 컴파일하는
 | `noMetadata`          | `true`인 경우 컴파일러는 출력물에서 딕셔너리 메타데이터(key, content wrapper)를 제거합니다.                                                                                                                                                                                                                   | `boolean`                                                                                                       | `false`     | `false` → `{"key":"my-key","content":{"key":"value"}}` <br/> `true` → `{"key":"value"}`                                                                  | • 로케일별 i18next 또는 ICU MessageFormat JSON 출력에 유용합니다.<br/>• `loadJSON` 플러그인과 잘 작동합니다.                                                                                              |
 | `dictionaryKeyPrefix` | 딕셔너리 키 접두사                                                                                                                                                                                                                                                                                            | `string`                                                                                                        | `''`        |                                                                                                                                                          | 추출된 딕셔너리 키에 선택적 접두사를 추가합니다.                                                                                                                                                          |
 
----
-
 ### 사용자 정의 스키마 (Custom Schemas)
 
 | 필드      | 설명                                                                     | 타입                        |

package/docs/ko/custom_domains.md

@@ -138,6 +138,38 @@ getMultilingualUrls("/about", { currentDomain: "intlayer.org" });
 
 이러한 절대 URL은 SEO를 위한 `<link rel="alternate" hreflang="...">` 태그에서 바로 사용할 수 있습니다.
 
+## 타입 추론
+
+`routing.domains`은 생성된 모듈 확장(module augmentation)으로 직렬화되므로,
+`getLocalizedUrl`과 `getLocalizedPath`는 도메인 라우팅된 로캘이 해석하는 정확한
+URL로 반환 타입을 좁혀줍니다 — 접두사 억제(prefix suppression)를 포함하여.
+
+```ts
+// routing: { mode: 'prefix-no-default', domains: { en: 'intlayer.org', zh: 'intlayer.zh' } }
+
+getLocalizedUrl("/about", "zh");
+//     ^? "https://intlayer.zh/about" | "/about"
+
+getLocalizedPath("/about", "zh");
+//     ^? "/about"   (origin이 없고, /zh/ 접두사도 없음)
+```
+
+URL 타입은 함수가 반환할 수 있는 두 값의 **합집합**입니다: 로캘의 도메인에서의
+절대 URL과 렌더링되는 페이지가 이미 해당 도메인에 있을 때 반환하는 상대 URL입니다.
+`getLocalizedPath`는 이러한 모호함이 없습니다 — origin을 내보내지 않으므로 —
+단일 리터럴로 유지됩니다.
+
+도메인을 공유하는 로캘은 타입에서도 일반적인 접두사를 유지합니다:
+
+```ts
+getLocalizedUrl("/about", "fr");
+//     ^? "https://intlayer.org/fr/about" | "/fr/about"
+```
+
+> `routing.domains`을 변경한 후 타입을 재생성하세요 (`npx intlayer build` 또는
+> 모든 dev server 실행) — 좁혀지는 타입은 설정 파일 자체가 아니라 생성된
+> `__RoutingRegistry`에서 나옵니다.
+
 ## 프록시 동작
 
 ### Next.js
@@ -170,6 +202,8 @@ GET intlayer.zh/about
 
 `intlayerProxy` Vite 플러그인은 개발 중에 동일한 로직을 적용합니다.
 
+> Intlayer v9부터 `intlayerProxy()`는 `intlayer()` 플러그인에 직접 번들로 포함되어 있으며 `routing.enableProxy` 옵션(`true`이 기본값)을 통해 기본적으로 활성화됩니다. 아래와 같이 별도로 등록하는 것은 이제 선택 사항이며, 이전 버전과의 호환성과 플러그인 순서를 제어해야 하는 설정을 위해 유지됩니다. `routing.enableProxy: false`로 설정하여 옵트아웃할 수 있습니다. [v9 릴리즈 노트](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/releases/v9.md)를 참조하세요.
+
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
 import { intlayer } from "vite-intlayer";