@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.11

package/docs/ja/self_hosting.md

@@ -0,0 +1,349 @@
+---
+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)

package/docs/ko/CI_CD.md

@@ -26,6 +26,10 @@ author: aymericzip
 
 Intlayer는 콘텐츠 선언 파일에 대한 번역을 자동으로 생성할 수 있도록 합니다. 워크플로우에 따라 이를 달성하는 여러 가지 방법이 있습니다.
 
+## 목차
+
+<TOC/>
+
 ## CMS 사용하기
 
 Intlayer를 사용하면 로컬에서는 단일 로케일만 선언하고 모든 번역은 CMS를 통해 원격으로 관리하는 워크플로우를 채택할 수 있습니다. 이를 통해 콘텐츠와 번역이 코드베이스와 완전히 분리되어 콘텐츠 편집자에게 더 많은 유연성을 제공하며, 핫 콘텐츠 리로딩이 가능해져(변경 사항 적용을 위해 애플리케이션을 다시 빌드할 필요 없음) 편리합니다.

package/docs/ko/autoFill.md

@@ -28,6 +28,53 @@ history:
 author: aymericzip
 ---
 
+# 콘텐츠 선언 파일 번역 채우기
+
+**CI에서 콘텐츠 선언 파일 자동 채우기**는 개발 워크플로우를 가속화하는 방법입니다.
+
+## 동작 이해하기
+
+`fill` 명령은 두 가지 모드를 포함합니다:
+
+- **Complete**: 각 로케일에 대해 누락된 모든 콘텐츠를 자동으로 채우고 현재 파일을 편집하거나, 지정된 경우 다른 파일을 편집합니다. 즉, complete 모드는 이미 번역된 경우 기존 콘텐츠의 번역을 건너뜁니다.
+- **Review**: 각 로케일에 대해 **모든** 콘텐츠를 자동으로 채우고 특정 파일에 대해 생성하거나, 지정된 경우 다른 파일을 생성합니다.
+
+`fill` 명령은 모든 로케일 콘텐츠 선언 파일을 처리합니다. 즉, CMS의 원격 콘텐츠는 처리하지 않습니다. CMS는 자체 번역 관리를 포함합니다.
+`@intlayer/sync-json-plugin`과 같은 플러그인을 사용하는 경우, Intlayer는 JSON 파일을 로케일 콘텐츠 선언 파일로 변환합니다. 즉, `fill` 명령으로 처리됩니다.
+
+새로 생성된 파일에는 사전 메타데이터로 `filled` 지시사항이 포함됩니다. 이 지시사항은 Intlayer가 파일이 자동으로 채워졌는지 여부를 알고, 존재하는 경우 이 파일을 다시 번역하지 않도록 건너뛰는 데 사용됩니다.
+
+Intlayer는 자동 채우기를 위해 다음 지시사항도 고려합니다:
+
+- `.content.{ts|js|json}` → `fill` 지시사항
+- 구성 파일 `.intlayer.config.ts` → `dictionary.fill` 지시사항
+- 그 외의 경우 기본값으로 `true`로 설정됨
+
+로케일별 콘텐츠 선언 파일의 경우, `true` 지시사항은 `./{{fileName}}.fill.content.json`으로 대체됩니다. 이는 로케일별 콘텐츠 선언 파일이 추가 지역화된 콘텐츠를 받을 수 없기 때문입니다. 따라서 기존 파일을 덮어쓰지 않기 위해 새 파일을 생성합니다.
+
+## Default Behavior
+
+기본적으로 `fill`은 전역적으로 `true`로 설정되어 있으며, 이는 Intlayer가 모든 콘텐츠 파일을 자동으로 채우고 파일 자체를 편집한다는 의미입니다. 이 동작은 여러 방법으로 사용자 정의할 수 있습니다:
+
+### 글로벌 구성 옵션
+
+1. **`fill: true` (기본값)** - 모든 로케일을 자동으로 채우고 현재 파일을 편집합니다
+2. **`fill: false`** - 이 콘텐츠 파일에 대한 자동 채우기를 비활성화합니다
+3. **`fill: "./relative/path/to/file"`** - 현재 파일을 편집하지 않고 현재 파일의 위치를 기반으로 해석되는 상대 경로를 가리켜 지정된 파일을 만들거나 업데이트합니다
+4. **`fill: "/absolute/path/to/file"`** - 현재 파일을 편집하지 않고 기본 디렉토리의 위치를 기반으로 해석되는 상대 경로를 가리켜 지정된 파일을 만들거나 업데이트합니다 (구성 파일 `.intlayer.config.ts`의 `baseDir` 필드)
+5. **`fill: "C:\\absolute\path\to\file"`** - 현재 파일을 편집하지 않고 운영 체제를 기반으로 해석되는 절대 경로를 가리켜 지정된 파일을 만들거나 업데이트합니다
+6. **`fill: { [key in Locales]?: string }`** - 각 로케일에 대해 지정된 파일을 만들거나 업데이트합니다
+
+### v7 동작 변경 사항
+
+v7에서는 `fill` 명령 동작이 업데이트되었습니다:
+
+- **`fill: true`** - 현재 파일을 모든 로케일의 채워진 콘텐츠로 다시 작성합니다
+- **`fill: "path/to/file"`** - 현재 파일을 수정하지 않고 지정된 파일을 채웁니다
+- **`fill: false`** - 자동 채우기를 완전히 비활성화합니다
+
+다른 파일에 쓰기 위해 경로 옵션을 사용할 때, fill 메커니즘은 콘텐츠 선언 파일 간의 _master-slave_ 관계를 통해 작동합니다. 메인(master) 파일이 소스 오브 트루스 역할을 하며, 업데이트될 때 Intlayer는 경로로 지정된 파생(filled) 선언 파일에 자동으로 그 변경 사항을 적용합니다.
+
 # 자동 채우기 콘텐츠 선언 파일 번역
 
 **자동 채우기 콘텐츠 선언 파일**은 개발 워크플로우를 가속화하는 방법입니다.
@@ -88,6 +135,40 @@ Intlayer는 메인 파일에 아직 선언되지 않은 모든 로케일을 채
 
 그 후, 두 선언 파일은 단일 사전으로 병합되어 표준 `useIntlayer("example")` 훅(react) / 컴포저블(vue)을 통해 접근할 수 있습니다.
 
+## 글로벌 설정
+
+`intlayer.config.ts` 파일에서 글로벌 자동 채우기 설정을 구성할 수 있습니다.
+
+```ts fileName="intlayer.config.ts"
+import { type IntlayerConfig, Locales } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+  },
+  dictionary: {
+    // 모든 사전에 대해 누락된 번역 자동 생성
+    fill: "./{{fileName}}Filled.content.ts",
+    //
+    // fill: "/messages/{{locale}}/{{key}}/{{fileName}}.content.json",
+    //
+    // fill: true, // "./{{fileName}}.content.json"을 사용하는 것처럼 모든 사전에 대해 누락된 번역 자동 생성
+    //
+    // fill: {
+    //   en: "./{{fileName}}.en.content.json",
+    //   fr: "./{{fileName}}.fr.content.json",
+    //   es: "./{{fileName}}.es.content.json",
+    // },
+  },
+};
+
+export default config;
+```
+
+content 파일의 `fill` 필드를 사용하여 사전별로 세부 조정할 수 있습니다. Intlayer는 먼저 사전별 구성을 고려한 후 글로벌 구성으로 돌아갑니다.
+
 ## 자동 채워진 파일 형식
 
 자동 채워진 선언 파일에 권장되는 형식은 **JSON**으로, 형식 제약을 피하는 데 도움이 됩니다. 그러나 Intlayer는 `.ts`, `.js`, `.mjs`, `.cjs` 및 기타 형식도 지원합니다.

package/docs/ko/benchmark/solid.md

@@ -118,6 +118,28 @@ i18n 누수 문제를 빠르게 파악하기 위해 [여기](https://intlayer.or
 - **Scoped static**: 복잡한 추가 네트워크 요청 없이 코드 구조를 유지(논리적 분리).
 - **Scoped dynamic**: 코드 분할 및 성능을 위한 최선의 접근 방식. 현재 뷰와 활성 로케일에 필요한 것만 로드하여 메모리 사용을 최소화함.
 
+### 측정 내용:
+
+각 스택에 대해 실제 브라우저에서 동일한 다국어 앱을 실행한 후 실제로 전송된 내용과 소요 시간을 기록했습니다. 크기는 **일반적인 웹 압축 후**에 보고되었습니다. 이는 원본 소스 수보다 사람들이 다운로드하는 내용에 더 가깝기 때문입니다.
+
+- **국제화 라이브러리 크기**: 번들링, 트리 셰이킹 및 축소 후 i18n 라이브러리의 크기는 빈 컴포넌트의 제공자 + 훅/프리미티브 코드의 크기입니다. 여기에는 번역 파일 로딩이 포함되지 않습니다. 콘텐츠가 들어오기 전에 라이브러리가 얼마나 비싼지 답변합니다.
+
+- **페이지당 JavaScript**: 각 벤치마크 경로의 경우, 그 방문 시 브라우저가 가져오는 스크립트의 양은 스위트의 페이지 전체에서 평균화됩니다(보고서가 롤업하는 로케일 전체). 무거운 페이지는 느린 페이지입니다.
+
+- **다른 로케일의 누수**: 감사된 페이지에 실수로 로드되는 다른 언어의 동일 페이지 콘텐츠입니다. 이 콘텐츠는 불필요하며 피해야 합니다. (예: `/en/about` 페이지 번들의 `/fr/about` 페이지 콘텐츠)
+
+- **다른 경로의 누수**: **다른 화면**의 경우 동일한 개념입니다. 한 페이지만 열었을 때 해당 사본이 함께 로드되는지 여부입니다. (예: `/en/contact` 페이지 번들의 `/en/about` 페이지 콘텐츠). 높은 점수는 약한 분할이나 과도하게 광범위한 번들을 의미합니다.
+
+- **평균 컴포넌트 번들 크기**: 일반적인 UI 조각은 하나의 거대한 앱 번호 내에 숨기는 대신 **한 번에 하나씩** 측정됩니다. 국제화가 일반적인 컴포넌트를 조용히 부풀리는지 여부를 보여줍니다. 예를 들어, 컴포넌트가 다시 렌더링되면 메모리에서 모든 데이터를 로드합니다. 거대한 JSON을 컴포넌트에 연결하는 것은 컴포넌트의 성능을 느리게 할 사용하지 않은 데이터의 큰 저장소를 연결하는 것과 같습니다.
+
+- **언어 전환 반응성**: 앱의 고유한 제어 기능을 사용하여 언어를 전환하고 페이지가 명확하게 전환될 때까지 걸리는 시간을 기록합니다. 이는 방문자가 알아차릴 미시적 단계가 아닌 것입니다.
+
+- **언어 변경 후 렌더링 작업**: 더 좁은 후속 작업입니다. 전환이 진행 중일 때 새로운 언어로 다시 칠하는 데 인터페이스가 소비한 노력입니다. "느껴지는" 시간과 프레임워크 비용이 다를 때 유용합니다.
+
+- **초기 페이지 로드 시간**: 네비게이션에서 브라우저가 테스트한 시나리오에 대해 페이지가 완전히 로드되었다고 간주할 때까지의 시간입니다. 콜드 스타트를 비교하는 데 좋습니다.
+
+- **하이드레이션 시간**: 앱이 노출하는 경우, 클라이언트가 서버 HTML을 실제로 클릭할 수 있는 것으로 변환하는 데 소비하는 시간입니다. 표의 대시는 해당 구현이 이 벤치마크에서 신뢰할 수 있는 하이드레이션 수치를 제공하지 않았음을 의미합니다.
+
 ## GitHub 스타
 
 GitHub 스타는 프로젝트의 인기, 커뮤니티 신뢰 및 장기적인 관련성을 나타내는 강력한 지표입니다. 기술적 품질을 직접적으로 측정하는 것은 아니지만, 얼마나 많은 개발자가 프로젝트가 유용하다고 생각하고 진행 상황을 팔로우하며 채택할 가능성이 있는지를 반영합니다. 프로젝트의 가치를 평가할 때 스타는 대안 간의 견인력을 비교하는 데 도움이 되며 생태계 성장에 대한 통찰력을 제공합니다.

package/docs/ko/benchmark/svelte.md

@@ -116,6 +116,28 @@ i18n 누수 문제를 빠르게 파악하기 위해 [여기](https://intlayer.or
 - **Scoped static**: 복잡한 추가 네트워크 요청 없이 코드 구조를 유지(논리적 분리).
 - **Scoped dynamic**: 코드 분할 및 성능을 위한 최선의 접근 방식. 현재 뷰와 활성 로케일에 필요한 것만 로드하여 메모리 사용을 최소화함.
 
+### 측정한 항목:
+
+동일한 다국어 앱을 모든 스택에서 실제 브라우저로 실행하고, 실제로 전송된 내용과 소요 시간을 기록했습니다. 크기는 **일반적인 웹 압축 후** 보고되며, 이는 원본 소스 크기보다 사용자가 실제로 다운로드하는 내용에 더 가깝습니다.
+
+- **국제화 라이브러리 크기**: 번들링, 트리 쉐이킹 및 최소화 후, i18n 라이브러리의 크기는 빈 컴포넌트의 providers + stores 코드 크기입니다. 번역 파일 로딩은 포함되지 않습니다. 콘텐츠가 포함되기 전 라이브러리의 비용이 어느 정도인지 나타냅니다.
+
+- **페이지당 JavaScript**: 각 벤치마크 경로에 대해 해당 방문에서 브라우저가 가져오는 스크립트의 양입니다. 이는 스위트의 페이지들과 리포트가 롤업하는 로케일들 전체에서 평균화됩니다. 무거운 페이지는 느린 페이지입니다.
+
+- **다른 로케일에서의 누수**: 감사된 페이지에서 실수로 로드될 수 있는 다른 언어의 동일한 페이지 콘텐츠입니다. 이 콘텐츠는 불필요하며 피해야 합니다. (예: `/en/about` 페이지 번들에서 `/fr/about` 페이지 콘텐츠)
+
+- **다른 경로에서의 누수**: **다른 화면**의 경우도 마찬가지입니다. 한 페이지만 열었을 때 해당 복사본이 함께 로드되는지 여부입니다. (예: `/en/contact` 페이지 번들에서 `/en/about` 페이지 콘텐츠). 높은 점수는 약한 분할 또는 과도하게 광범위한 번들을 시사합니다.
+
+- **평균 컴포넌트 번들 크기**: 하나의 거대한 앱 번호 내에 숨겨지지 않고 **한 번에 하나씩** 측정된 일반적인 UI 조각들입니다. 국제화가 일상적인 컴포넌트를 어느 정도 증가시키는지 보여줍니다. 예를 들어, 컴포넌트가 다시 렌더링되면 메모리에서 모든 데이터를 로드합니다. 거대한 JSON을 컴포넌트에 연결하는 것은 컴포넌트의 성능을 느리게 할 거대한 미사용 데이터 저장소를 연결하는 것과 같습니다.
+
+- **언어 전환 반응성**: 앱의 자체 컨트롤을 사용하여 언어를 전환하고 페이지가 명확하게 전환될 때까지의 시간을 측정합니다. 이는 방문자가 눈으로 보게 되는 시간이지, 랩 마이크로 스텝이 아닙니다.
+
+- **언어 변경 후 렌더링 작업**: 더 좁은 후속 조치입니다. 전환이 진행 중인 상태에서 새 언어를 위해 인터페이스가 다시 칠하는 데 소요된 노력의 정도입니다. "느껴지는" 시간과 프레임워크 비용이 다를 때 유용합니다.
+
+- **초기 페이지 로드 시간**: 테스트한 시나리오에 대해 브라우저가 페이지를 완전히 로드된 것으로 간주할 때까지의 시간입니다. 콜드 시작을 비교하는 데 유용합니다.
+
+- **Hydration 시간**: 앱이 노출할 때, 클라이언트가 서버 HTML을 실제로 클릭할 수 있는 것으로 변환하는 데 소요되는 시간입니다. 표의 대시는 해당 구현이 이 벤치마크에서 신뢰할 수 있는 hydration 수치를 제공하지 않음을 의미합니다.
+
 ## GitHub 스타
 
 GitHub 스타는 프로젝트의 인기, 커뮤니티 신뢰 및 장기적인 관련성을 나타내는 강력한 지표입니다. 기술적 품질을 직접적으로 측정하는 것은 아니지만, 얼마나 많은 개발자가 프로젝트가 유용하다고 생각하고 진행 상황을 팔로우하며 채택할 가능성이 있는지를 반영합니다. 프로젝트의 가치를 평가할 때 스타는 대안 간의 견인력을 비교하는 데 도움이 되며 생태계 성장에 대한 통찰력을 제공합니다.

package/docs/ko/benchmark/tanstack.md

@@ -124,6 +124,28 @@ i18n 누수 문제를 빠르게 파악하기 위해 [여기](https://intlayer.or
 - **Scoped static**: 복잡한 추가 네트워크 요청 없이 코드 구조를 유지(논리적 분리).
 - **Scoped dynamic**: 코드 분할 및 성능을 위한 최선의 접근 방식. 현재 뷰와 활성 로케일에 필요한 것만 로드하여 메모리 사용을 최소화함.
 
+### 측정 항목:
+
+모든 스택에 대해 실제 브라우저에서 동일한 다국어 앱을 실행하고, 실제로 전송되는 내용과 소요 시간을 기록했습니다. 크기는 **일반적인 웹 압축 후**에 보고되며, 이는 원본 소스 크기보다 사용자가 다운로드하는 내용에 더 가깝습니다.
+
+- **Internationalization 라이브러리 크기**: 번들링, 트리-셰이킹 및 최소화 후, i18n 라이브러리의 크기는 프로바이더(예: `NextIntlClientProvider`) + 훅(예: `useTranslations`) 코드의 크기를 빈 컴포넌트에서 측정한 것입니다. 번역 파일 로딩은 포함되지 않습니다. 콘텐츠가 들어오기 전에 라이브러리가 얼마나 비용이 드는지를 답합니다.
+
+- **페이지당 JavaScript**: 각 벤치마크 경로에 대해 방문 시 브라우저가 가져오는 스크립트의 양으로, 스위트의 페이지 전체에서 평균화됩니다(리포트가 롤업하는 경우 로케일 전체에서). 무거운 페이지는 느린 페이지입니다.
+
+- **다른 로케일에서의 유출**: 감사된 페이지에 실수로 로드될 수 있는 다른 언어의 동일한 페이지 콘텐츠입니다. 이 콘텐츠는 불필요하며 피해야 합니다. (예: `/en/about` 페이지 번들에서 `/fr/about` 페이지 콘텐츠)
+
+- **다른 경로에서의 유출**: **다른 화면**의 콘텐츠가 한 페이지만 열었을 때 함께 로드되는지 여부에 대한 동일한 개념입니다. (예: `/en/contact` 페이지 번들에서 `/en/about` 페이지 콘텐츠). 높은 점수는 약한 분할 또는 과도하게 넓은 번들을 시사합니다.
+
+- **평균 컴포넌트 번들 크기**: 일반적인 UI 조각들은 한 번에 하나씩 측정되며, 거대한 앱 번호 안에 숨겨지지 않습니다. internationalization이 일상적인 컴포넌트를 조용히 부풀리는지 여부를 보여줍니다. 예를 들어, 컴포넌트가 다시 렌더링되면 메모리에서 모든 데이터를 로드하게 됩니다. 거대한 JSON을 컴포넌트에 연결하는 것은 컴포넌트의 성능을 저하시킬 수 있는 사용되지 않은 데이터의 큰 저장소에 연결하는 것과 같습니다.
+
+- **언어 전환 반응성**: 앱의 자체 컨트롤을 사용하여 언어를 전환하고 페이지가 명확하게 전환될 때까지의 소요 시간을 측정합니다. 방문자가 알 수 있는 수준이며, 실험실 마이크로 단계가 아닙니다.
+
+- **언어 변경 후 렌더링 작업**: 더 좁은 후속 작업으로, 전환이 진행 중일 때 새 언어를 다시 칠하기 위해 인터페이스가 소비한 노력입니다. "느껴지는" 시간과 프레임워크 비용이 다를 때 유용합니다.
+
+- **초기 페이지 로드 시간**: 탐색에서 브라우저가 테스트한 시나리오에 대해 페이지가 완전히 로드되었다고 간주할 때까지의 시간입니다. 콜드 스타트를 비교하는 데 좋습니다.
+
+- **수화 시간**: 앱이 노출할 때, 클라이언트가 서버 HTML을 실제로 클릭할 수 있는 것으로 변환하는 데 소비하는 시간입니다. 테이블의 대시는 해당 구현이 이 벤치마크에서 신뢰할 수 있는 수화 수치를 제공하지 않았음을 의미합니다.
+
 ## GitHub 스타
 
 GitHub 스타는 프로젝트의 인기, 커뮤니티 신뢰 및 장기적인 관련성을 나타내는 강력한 지표입니다. 기술적 품질을 직접적으로 측정하는 것은 아니지만, 얼마나 많은 개발자가 프로젝트가 유용하다고 생각하고 진행 상황을 팔로우하며 채택할 가능성이 있는지를 반영합니다. 프로젝트의 가치를 평가할 때 스타는 대안 간의 견인력을 비교하는 데 도움이 되며 생태계 성장에 대한 통찰력을 제공합니다.

package/docs/ko/cli/ci.md

@@ -140,6 +140,28 @@ steps:
     run: npx intlayer ci fill
 ```
 
+## Scaffolded GitHub Actions
+
+`intlayer init`을 실행하면, Intlayer가 package manager(npm, yarn, pnpm, 또는 bun)를 감지하고 `.github/workflows/` 디렉토리 아래에 해당 package manager와 일치하는 명령어를 포함한 두 개의 GitHub Actions 워크플로우를 생성합니다:
+
+- **`intlayer-fill.yml`** — 모든 pull request에서 dictionaries를 빌드하고 `intlayer fill --git-diff --mode complete`을 실행하여 변경된 dictionaries에 대한 누락된 번역을 생성한 후, 결과를 PR 브랜치에 커밋합니다.
+- **`intlayer-test.yml`** — 모든 pull request에서 dictionaries를 빌드하고 `intlayer test`를 실행하여, 필수 locales에 번역이 누락된 경우 체크를 실패합니다.
+
+기존 워크플로우 파일은 절대 덮어씌워지지 않습니다. scaffolding을 완전히 건너뛰려면, 다음을 실행합니다:
+
+```bash
+npx intlayer init --no-github-actions
+```
+
+### fill 워크플로우에 AI 접근 제공
+
+스캐폴드된 `intlayer-fill.yml`은 AI 접근이 필요합니다. 두 가지 옵션을 사용할 수 있습니다(워크플로우의 `env` 블록에서 구성):
+
+1. **자신의 AI provider 키** — 리포지토리 설정(Settings → Secrets and variables → Actions)에서 `AI_API_KEY` secret을 추가합니다. 워크플로우는 `--provider`, `--model`, `--api-key`를 통해 이를 전달합니다.
+2. **Intlayer CMS 접근 키** — `INTLAYER_CLIENT_ID` 및 `INTLAYER_CLIENT_SECRET` secret을 추가하고 `intlayer.config` `editor` 섹션에 연결합니다. CMS 접근 키는 Intlayer backend을 통해 AI 접근을 제공합니다.
+
+`intlayer-test.yml` 워크플로우는 AI 접근이 필요하지 않습니다.
+
 ## 오류 처리
 
 - `INTLAYER_PROJECT_CREDENTIALS`가 설정되지 않은 경우, 명령어는 오류로 종료됩니다.