@intlayer/docs 9.0.0-canary.9 → 9.0.1

package/docs/ja/self_hosting.md

@@ -0,0 +1,350 @@
+---
+createdAt: 2026-06-30
+updatedAt: 2026-06-30
+title: Intlayerのセルフホスティング
+description: 単一のコマンドでIntlayerの完全なインスタンスを独自のインフラストラクチャ上で実行できます。Intlayer Cloudアカウントは不要です。
+keywords:
+  - セルフホスティング
+  - Docker
+  - Docker Compose
+  - Intlayer
+  - CMS
+  - インストール
+  - インフラストラクチャ
+slugs:
+  - doc
+  - self-hosting
+author: aymericzip
+---
+
+# Intlayerのセルフホスティング
+
+Intlayerは、Intlayer Cloudアカウントを必要とせず、独自のインフラストラクチャ上で完全に実行できます。単一のコマンドで、本番環境に対応したスタックを起動します。
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+インストーラーは `docker-compose.yml` と `.env` をダウンロードし、必要なシークレットを自動生成して、すべてのコンテナを `docker compose up -d` で起動します。
+
+## 目次
+
+<TOC/>
+
+---
+
+## アーキテクチャ
+
+```
+                ┌─────────────────────────────┐
+ browser ──────▶ │  app  (TanStack Start)  :3000│ ──┐
+                └─────────────────────────────┘   │ VITE_BACKEND_URL
+                ┌─────────────────────────────┐   │
+                │  backend (Fastify/Bun)  :3100│ ◀─┘
+                └──────────────┬──────────────┘
+          ┌──────────┬─────────┼──────────┬───────────┐
+          ▼          ▼         ▼          ▼           ▼
+     mongo:27017  redis:6379  minio:9000  mailpit:1025  Chromium
+     (1ノードRS)             (S3 API)     (SMTP)        (インイメージ)
+                             minio:9001   mailpit:8025
+                             (コンソール) (ウェブUI)
+```
+
+Chromium (Puppeteerのスクリーンショット生成に使用) はバックエンドイメージ内にバンドルされており、別のコンテナは必要ありません。
+
+---
+
+## 前提条件
+
+- **Docker** ≥ 24 および **Docker Compose** ≥ v2。いずれかが不足している場合、インストーラーはインストールリンクを表示して終了します。
+- ホスト上でポート `3000`、`3100`、`8025`、`9000`、`9001` が利用可能であること。
+- LinuxまたはmacOSホスト（またはWindows上のWSL2）。
+
+---
+
+## クイックスタート
+
+```sh
+curl -fsSL https://intlayer.org/install.sh | sh
+```
+
+インストーラーの動作:
+
+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アカウントを作成してください。
+
+---
+
+## サービス
+
+| サービス    | イメージ                             | ホストポート                     | 目的                                                         |
+| ----------- | ------------------------------------ | -------------------------------- | ------------------------------------------------------------ |
+| **app**     | `apps/app/Dockerfile` からビルド     | `3000`                           | TanStack Start ダッシュボード (CMS UI)                       |
+| **backend** | `apps/backend/Dockerfile` からビルド | `3100`                           | Fastify REST API (`/health` エンドポイント)                  |
+| **mongo**   | `mongo:7`                            | 内部                             | シングルノードレプリカセット (`rs0`)                         |
+| **redis**   | `redis:7-alpine`                     | 内部                             | ジョブキュー (BullMQ) とキャッシュ (ioredis)                 |
+| **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` から直接読み込まれるため、ブラウザから到達可能である必要があります。
+
+---
+
+## 環境変数
+
+インストーラーはすぐに使用できる `.env` を生成します。以下の表は、すべての変数について説明しています。
+
+### 必須 (自動生成またはプロンプトによる入力)
+
+| 変数                   | 例                                              | 説明                                                  |
+| ---------------------- | ----------------------------------------------- | ----------------------------------------------------- |
+| `NODE_ENV`             | `production`                                    | ランタイム環境                                        |
+| `PORT`                 | `3100`                                          | バックエンドのリスニングポート                        |
+| `BACKEND_URL`          | `http://localhost:3100`                         | バックエンドAPIの公開URL                              |
+| `APP_URL`              | `http://localhost:3000`                         | ダッシュボードの公開URL                               |
+| `DOMAIN`               | `localhost`                                     | クッキードメイン                                      |
+| `MONGODB_URI`          | `mongodb://mongo:27017/intlayer?replicaSet=rs0` | MongoDBの完全な接続URI                                |
+| `REDIS_URL`            | `redis://redis:6379`                            | Redisの接続URL                                        |
+| `BETTER_AUTH_SECRET`   | _(生成済み)_                                    | セッション署名用の32バイトのシークレット              |
+| `MAIL_PROVIDER`        | `smtp`                                          | メールトランスポート: `smtp` または `resend`          |
+| `MAIL_SMTP_HOST`       | `mailpit`                                       | SMTPホスト名 (Mailpitコンテナ名)                      |
+| `MAIL_SMTP_PORT`       | `1025`                                          | SMTPポート                                            |
+| `MAIL_FROM`            | `Intlayer <no-reply@localhost>`                 | 送信元アドレス                                        |
+| `S3_ENDPOINT`          | `http://minio:9000`                             | S3互換エンドポイント                                  |
+| `S3_PUBLIC_URL`        | `http://localhost:9000/intlayer`                | ブラウザによるアセット読み込み用の公開URL             |
+| `S3_BUCKET_NAME`       | `intlayer`                                      | バケット名                                            |
+| `S3_ACCESS_KEY_ID`     | _(生成済み)_                                    | MinIOアクセスキー                                     |
+| `S3_SECRET_ACCESS_KEY` | _(生成済み)_                                    | MinIOシークレットキー                                 |
+| `VITE_BACKEND_URL`     | `http://localhost:3100`                         | ビルド時にダッシュボードに組み込まれるバックエンドURL |
+| `VITE_DOMAIN`          | `localhost`                                     | ビルド時にダッシュボードに組み込まれるドメイン        |
+
+### オプション (存在しない場合でも機能は正常に劣化します)
+
+| 変数                                                     | 機能                                                                       |
+| -------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `OPENAI_API_KEY`                                         | AIアシストによる翻訳とコンテンツ監査                                       |
+| `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, `STRIPE_*` | 請求とサブスクリプション管理                                               |
+| `RESEND_API_KEY`                                         | Resendを介したトランザクションメール (設定されている場合、Mailpitを上書き) |
+| `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`               | GitHub OAuthログイン                                                       |
+| `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`               | Google OAuthログイン                                                       |
+| `GITLAB_CLIENT_ID`, `GITLAB_CLIENT_SECRET`               | GitLab OAuthログイン                                                       |
+| `MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET`         | Microsoft OAuthログイン                                                    |
+| `LINKEDIN_CLIENT_ID`, `LINKEDIN_CLIENT_SECRET`           | LinkedIn OAuthログイン                                                     |
+| `ATLASSIAN_CLIENT_ID`, `ATLASSIAN_CLIENT_SECRET`         | Atlassian OAuthログイン                                                    |
+
+---
+
+## Intlayerプロジェクトの接続
+
+スタックが稼働したら、`intlayer.org` の代わりに自己ホスト型のバックエンドとダッシュボードを指すようにプロジェクトを設定します。
+
+### プロジェクト設定
+
+```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,
+
+    /**
+     * 自己ホスト型CMSダッシュボードのURL。
+     * デフォルト: https://app.intlayer.org
+     */
+    cmsURL: process.env.INTLAYER_CMS_URL, // 例: http://localhost:3000
+
+    /**
+     * 自己ホスト型バックエンドAPIのURL。
+     * デフォルト: https://back.intlayer.org
+     */
+    backendURL: process.env.INTLAYER_BACKEND_URL, // 例: http://localhost:3100
+  },
+};
+
+export default config;
+```
+
+プロジェクトの `.env` で環境変数を設定します。
+
+```sh
+INTLAYER_CMS_URL=http://localhost:3000
+INTLAYER_BACKEND_URL=http://localhost:3100
+INTLAYER_CLIENT_ID=<your-client-id>
+INTLAYER_CLIENT_SECRET=<your-client-secret>
+```
+
+自己ホスト型ダッシュボードの **Projects → Access keys** (`http://localhost:3000/projects`) でアクセス認証情報を作成します。
+
+### `@intlayer/api` SDK
+
+`@intlayer/api` SDKをプログラムで利用する場合は、`backendURL` を明示的に渡します。
+
+```typescript fileName="cms.ts" codeFormat="typescript"
+import { createIntlayerCMS } from "@intlayer/api";
+import { dictionaryEndpoint } from "@intlayer/api/dictionary";
+
+const cms = createIntlayerCMS({
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    backendURL: process.env.INTLAYER_BACKEND_URL, // http://localhost:3100
+  },
+});
+
+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
+```
+
+---
+
+## バックアップと復元
+
+すべての永続データは、3つの名前付きDockerボリュームに保存されます。
+
+### バックアップ
+
+```sh
+docker run --rm \
+  -v intlayer_mongo-data:/data \
+  -v "$(pwd)":/backup \
+  busybox tar czf /backup/mongo-data.tar.gz /data
+
+docker run --rm \
+  -v intlayer_redis-data:/data \
+  -v "$(pwd)":/backup \
+  busybox tar czf /backup/redis-data.tar.gz /data
+
+docker run --rm \
+  -v intlayer_minio-data:/data \
+  -v "$(pwd)":/backup \
+  busybox tar czf /backup/minio-data.tar.gz /data
+```
+
+### 復元
+
+```sh
+docker run --rm \
+  -v intlayer_mongo-data:/data \
+  -v "$(pwd)":/backup \
+  busybox tar xzf /backup/mongo-data.tar.gz -C /
+
+# redis-data と minio-data についても同様に繰り返します
+```
+
+---
+
+## リバースプロキシの使用 (Nginx / Caddy)
+
+本番環境のデプロイでは、appコンテナとbackendコンテナを直接公開するのではなく、リバースプロキシをそれらの前に配置します。
+
+### Nginxの例
+
+```nginx
+server {
+    listen 80;
+    server_name cms.example.com;
+
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+
+server {
+    listen 80;
+    server_name api.example.com;
+
+    location / {
+        proxy_pass http://localhost:3100;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+公開ドメインに合わせて、以下の `.env` 変数を更新してください。
+
+```sh
+BACKEND_URL=https://api.example.com
+APP_URL=https://cms.example.com
+DOMAIN=example.com
+VITE_BACKEND_URL=https://api.example.com
+VITE_DOMAIN=example.com
+```
+
+> `VITE_*` 変数はビルド時にダッシュボードイメージに組み込まれます。イメージがビルドされた後に変更した場合、`app` イメージをリビルドするか (`docker compose build app`)、ランタイム設定インジェクションを使用する必要があります。
+
+---
+
+## トラブルシューティング
+
+### 最初の起動時にバックエンドがクラッシュループする
+
+バックエンドが起動する前に、MongoDBとRedisが正常である必要があります。composeファイルは `condition: service_healthy` とともに `depends_on` を使用しています。バックエンドの再起動が繰り返される場合は、`mongo` と `redis` のヘルスチェックがパスしているか確認してください。
+
+```sh
+docker compose ps
+docker compose logs mongo
+docker compose logs redis
+```
+
+### ダッシュボードがAPIに到達できない
+
+`VITE_BACKEND_URL` が、バックエンドが**ブラウザ**から到達可能なURL (Dockerネットワークではなく) と一致していることを確認してください。バックエンドポートを変更したり、リバースプロキシを追加した場合は、ダッシュボードイメージをリビルドしてください。
+
+```sh
+docker compose build app
+docker compose up -d app
+```
+
+### メールが送信されない
+
+デフォルトでは、すべての送信メールはMailpitによって捕捉されます。送信されたメッセージを確認するには、`http://localhost:8025` を開いてください。実際のメールを送信するには、`.env` で `MAIL_PROVIDER=resend` と `RESEND_API_KEY=<your-key>` を設定し、バックエンドを再起動します。
+
+```sh
+docker compose restart backend
+```
+
+### MinIOバケットが見つからない
+
+`minio-init` ワンショットサービスが実行されなかった場合 (またはMinIOが準備できる前に実行された場合) は、手動でバケットを作成してください。
+
+```sh
+docker compose run --rm minio-init
+```
+
+---
+
+## 役立つリンク
+
+- [Intlayer 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)
+- [CMS SDK — `@intlayer/api`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/intlayer_CMS.md#programmatic-access-with-the-intlayerapi-sdk)
+- [Docker Image (aymercizip/intlayer-selfhost)](https://hub.docker.com/repository/docker/aymercizip/intlayer-selfhost/general)

package/docs/ko/bundle_optimization.md

@@ -231,6 +231,9 @@ Next.js는 빌드 시 SWC를 사용하므로 optimize(가져오기 재작성)
 
 > Next.js에서 SWC 플러그인이 아직 실험 단계이므로 이 플러그인은 기본적으로 설치되지 않습니다. 향후 변경될 수 있습니다.
 
+<Tabs>
+ <Tab value="npm">
+
 ```bash packageManager="npm"
 npm install -D @intlayer/swc
 ```
@@ -247,6 +250,19 @@ pnpm add -D @intlayer/swc
 bun add -d @intlayer/swc
 ```
 
+ </Tab>
+ <Tab value="Crates.io (rust)">
+
+```toml fileName="Cargo.toml"
+[dependencies]
+intlayer-swc-plugin = "*"
+```
+
+[View on Crates.io](https://crates.io/crates/intlayer-swc-plugin)
+
+ </Tab>
+</Tabs>
+
 설치되면 Intlayer가 플러그인을 자동으로 감지하여 사용합니다.
 
 **purge 및 minify** 패스(필드 제거 및 필드 이름 변경)의 경우 `@intlayer/babel`을 함께 설치하고 Babel 플러그인을 추가합니다. Next.js는 변환을 위해 SWC를 사용하지만 플러그인 구성을 위해 `babel.config.js`를 계속 평가하므로 Babel 플러그인은 SWC 이전의 사전 패스(pre-pass)로 실행됩니다.

package/docs/ko/cli/index.md

@@ -125,7 +125,7 @@ Intlayer는 여러 설정 파일 형식을 허용합니다:
 
 ### 인증
 
-- **[로그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/login.md)** - Intlayer CMS에 인증하고 액세스 자격 증명을 가져옵니다.
+- **[로그인](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/login.md)** - Intlayer CMS에 인증하고 액세스 자격 증명을 가져옵니다.
 
 ### 핵심 명령어
 

package/docs/ko/cli/scan.md

@@ -150,10 +150,10 @@ await scan("https://example.com", {
 });
 ```
 
-더 낮은 수준의 액세스를 위해 `@intlayer/chokidar/scan`의 `scanWebsite`는 구조화된 `ScanResult` 객체를 반환합니다:
+더 낮은 수준의 액세스를 위해 `@intlayer/engine/scan`의 `scanWebsite`는 구조화된 `ScanResult` 객체를 반환합니다:
 
 ```ts
-import { scanWebsite } from "@intlayer/chokidar/scan";
+import { scanWebsite } from "@intlayer/engine/scan";
 
 const result = await scanWebsite("https://example.com", { deep: false });
 console.log(result.score, result.totalPageSize, result.events);

package/docs/ko/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-06-23
+updatedAt: 2026-07-11
 title: 구성 (Configuration)
 description: 애플리케이션에 Intlayer를 구성하는 방법을 알아보세요. 필요에 따라 Intlayer를 맞춤설정하는 데 사용할 수 있는 다양한 설정과 옵션을 이해하세요.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.0.0
+    date: 2026-07-11
+    changes: "`analytics` 구성 추가"
   - version: 9.0.0
     date: 2026-06-24
     changes: "Add `enableProxy` option to the routing configuration"
@@ -355,6 +358,30 @@ const config: IntlayerConfig = {
     liveSync: true,
   },
 
+  /**
+   * 애널리틱스(analytics) 구성.
+   */
+  analytics: {
+    /**
+     * 애널리틱스 수집 활성화 여부(페이지 뷰, 콘텐츠 노출, A/B 이벤트).
+     * 귀속(attribution)을 위해 `editor.clientId`가 설정되어 있어야 합니다.
+     * 기본값: false
+     */
+    enabled: true,
+
+    /**
+     * 백엔드로 자동 일괄 전송하는 간격(밀리초).
+     * 기본값: 20000
+     */
+    flushInterval: 20000,
+
+    /**
+     * 기록할 세션의 비율, 0(없음)에서 1(전체) 사이.
+     * 기본값: 1
+     */
+    sampleRate: 1,
+  },
+
   /**
    * AI 기반 번역 및 생성 설정.
    */
@@ -668,6 +695,20 @@ export default config;
 
 ---
 
+### 애널리틱스 구성 (Analytics)
+
+Intlayer 애널리틱스와 관련된 설정을 정의합니다: 사용자에게 실제로 표시되는 콘텐츠(페이지 뷰, 콘텐츠 노출)를 수집하고 콘텐츠에 대한 A/B 테스트를 지원합니다.
+
+애널리틱스는 철저히 옵트인(opt-in) 방식입니다: `analytics.enabled`가 명시적으로 `true`로 설정되고 **그리고** 귀속을 위한 프로젝트 키(`editor.clientId`)가 구성되지 않는 한 아무것도 수집되지 않습니다. 비활성화된 경우(기본값), 전체 애널리틱스 통합은 애플리케이션 번들에서 데드 코드 제거(dead-code elimination)됩니다.
+
+| 필드            | 설명                                                                | 타입      | 기본값  | 예시    | 참고                                                                                                                                  |
+| --------------- | ------------------------------------------------------------------- | --------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`       | 애널리틱스 수집을 활성화합니다(페이지 뷰, 콘텐츠 노출, A/B 이벤트). | `boolean` | `false` | `true`  | 귀속을 위해 `editor.clientId`가 설정되어 있어야 합니다. 설정되지 않으면 `enabled`가 `true`여도 애널리틱스는 비활성 상태로 유지됩니다. |
+| `flushInterval` | 백엔드로 자동 일괄 전송하는 간격(밀리초).                           | `number`  | `20000` | `10000` |                                                                                                                                       |
+| `sampleRate`    | 기록할 세션의 비율, `0`(없음)에서 `1`(전체) 사이.                   | `number`  | `1`     | `0.5`   | 샘플링은 세션별로 결정적이므로, 기록된 세션은 자신의 모든 이벤트를 보고합니다(부분 퍼널 없음).                                        |
+
+---
+
 ### 라우팅 구성 (Routing)
 
 URL 구조, 로케일 저장 및 미들웨어 처리를 포함하여 라우팅 동작을 제어하기 위한 설정입니다.

package/docs/ko/how_works_intlayer.md

@@ -217,9 +217,9 @@ Express를 기반으로 한 서버는 시각적 편집기 요청을 수신하고
 
 `@intlayer/dictionaries-entry`, `@intlayer/unmerged-dictionaries-entry` 및 `@intlayer/dynamic-dictionaries-entry` 패키지는 Intlayer 사전의 진입 경로를 반환합니다. 브라우저에서 파일 시스템을 검색하는 것이 불가능하기 때문에, Webpack이나 Rollup과 같은 번들러를 사용하여 사전의 진입 경로를 가져오는 것은 불가능합니다. 이 패키지들은 별칭(alias)으로 설계되어 Vite, Webpack, Turbopack 등 다양한 번들러에서 번들링 최적화를 가능하게 합니다.
 
-### @intlayer/chokidar
+### @intlayer/engine
 
-`@intlayer/chokidar` 패키지는 콘텐츠 파일을 모니터링하고 수정될 때마다 변경된 사전을 재생성하는 데 사용됩니다.
+`@intlayer/engine` 패키지는 콘텐츠 파일을 모니터링하고 수정될 때마다 변경된 사전을 재생성하는 데 사용됩니다.
 
 ### @intlayer/editor