@intlayer/docs 7.3.0 → 7.3.1

package/docs/ja/bundle_optimization.md

@@ -0,0 +1,180 @@
+---
+createdAt: 2025-11-25
+updatedAt: 2025-11-25
+title: i18n バンドルサイズとパフォーマンスの最適化
+description: 国際化（i18n）コンテンツを最適化してアプリケーションのバンドルサイズを削減します。Intlayerを使った辞書のツリーシェイキングと遅延読み込みの活用方法を学びましょう。
+keywords:
+  - バンドル最適化
+  - コンテンツ自動化
+  - 動的コンテンツ
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - bundle-optimization
+history:
+  - version: 6.0.0
+    date: 2025-11-25
+    changes: 初期履歴
+---
+
+# i18n バンドルサイズとパフォーマンスの最適化
+
+従来のJSONファイルに依存するi18nソリューションで最も一般的な課題の一つは、コンテンツサイズの管理です。開発者が手動でコンテンツをネームスペースに分割しない場合、ユーザーは単一のページを閲覧するためだけに、すべてのページや場合によってはすべての言語の翻訳をダウンロードしてしまうことがよくあります。
+
+例えば、10ページが10言語に翻訳されたアプリケーションでは、ユーザーは実際に必要な**1ページ**（現在の言語の現在のページ）だけでよいにもかかわらず、100ページ分のコンテンツをダウンロードすることになりかねません。これにより、帯域幅の無駄遣いと読み込み時間の遅延が発生します。
+
+> これを検出するには、`rollup-plugin-visualizer`（vite）、`@next/bundle-analyzer`（next.js）、`webpack-bundle-analyzer`（React CRA / Angular / など）といったバンドルアナライザーを使用できます。
+
+**Intlayerはビルド時の最適化によってこの問題を解決します。** コードを解析して、各コンポーネントで実際に使用されている辞書を検出し、必要なコンテンツのみをバンドルに再注入します。
+
+## 目次
+
+<TOC />
+
+## 仕組み
+
+Intlayerは**コンポーネント単位のアプローチ**を採用しています。グローバルなJSONファイルとは異なり、コンテンツはコンポーネントのそばまたは内部に定義されます。ビルドプロセス中にIntlayerは以下を行います：
+
+1.  コードを**解析**して`useIntlayer`の呼び出しを見つけます。
+2.  対応する辞書コンテンツを**構築**します。
+3.  設定に基づいて`useIntlayer`の呼び出しを最適化されたコードに**置き換え**ます。
+
+これにより以下が保証されます：
+
+- コンポーネントがインポートされていなければ、そのコンテンツはバンドルに含まれません（デッドコード削除）。
+- コンポーネントがレイジーロードされる場合、そのコンテンツもレイジーロードされます。
+
+## プラットフォーム別セットアップ
+
+### Next.js
+
+Next.js はビルドに SWC を使用しているため、変換を処理するために `@intlayer/swc` プラグインが必要です。
+
+> このプラグインは、Next.js における SWC プラグインがまだ実験的なため、デフォルトでインストールされています。将来的に変更される可能性があります。
+
+### Vite
+
+Vite は `vite-intlayer` の依存として含まれている `@intlayer/babel` プラグインを使用します。最適化はデフォルトで有効になっています。
+
+### Webpack
+
+Webpack で Intlayer のバンドル最適化を有効にするには、適切な Babel (`@intlayer/babel`) または SWC (`@intlayer/swc`) プラグインをインストールして設定する必要があります。
+
+### Expo / Lynx
+
+このプラットフォームではバンドル最適化は**まだ利用できません**。将来のリリースでサポートが追加される予定です。
+
+## 設定
+
+Intlayerがバンドルを最適化する方法は、`intlayer.config.ts`の`build`プロパティで制御できます。
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  build: {
+    optimize: true,
+    importMode: "static", // または 'dynamic'
+    traversePattern: ["**/*.{js,ts,mjs,cjs,jsx,tsx}", "!**/node_modules/**"],
+  },
+};
+
+export default config;
+```
+
+> `optimize`のデフォルトオプションを維持することが、ほとんどの場合で推奨されます。
+
+> 詳細はドキュメントの設定をご覧ください: [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/configuration.md)
+
+### ビルドオプション
+
+`build`構成オブジェクトの下で利用可能なオプションは以下の通りです：
+
+| プロパティ            | 型                              | デフォルト                      | 説明                                                                                                                                                                                                         |
+| :-------------------- | :------------------------------ | :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`optimize`**        | `boolean`                       | `undefined`                     | ビルド最適化を有効にするかどうかを制御します。`true` の場合、Intlayer は辞書呼び出しを最適化されたインジェクトに置き換えます。`false` の場合、最適化は無効になります。通常は本番環境で `true` に設定します。 |
+| **`importMode`**      | `'static' , 'dynamic' , 'live'` | `'static'`                      | 辞書の読み込み方法を決定します（詳細は以下を参照）。                                                                                                                                                         |
+| **`traversePattern`** | `string[]`                      | `['**/*.{js,ts,jsx,tsx}', ...]` | Intlayerが最適化のためにスキャンするファイルを定義するグロブパターン。関連のないファイルを除外し、ビルドを高速化するために使用します。                                                                       |
+| **`outputFormat`**    | `'esm', 'cjs'`                  | `'esm', 'cjs'`                  | ビルドされた辞書の出力フォーマットを制御します。                                                                                                                                                             |
+
+## インポートモード
+
+`importMode`設定は、辞書の内容がコンポーネントにどのように注入されるかを決定します。
+
+### 1. スタティックモード（`default`）
+
+静的モードでは、Intlayerは `useIntlayer` を `useDictionary` に置き換え、辞書を直接JavaScriptバンドルに注入します。
+
+- **利点:** 即時レンダリング（同期的）、ハイドレーション時の追加ネットワークリクエストなし。
+- **欠点:** バンドルにはその特定のコンポーネントに対する**すべての**利用可能な言語の翻訳が含まれます。
+- **最適用途:** シングルページアプリケーション（SPA）。
+
+**変換後のコード例:**
+
+```tsx
+// あなたのコード
+const content = useIntlayer("my-key");
+
+// 最適化されたコード（静的）
+const content = useDictionary({
+  key: "my-key",
+  content: {
+    nodeType: "translation",
+    translation: {
+      en: "My title",
+      fr: "Mon titre",
+    },
+  },
+});
+```
+
+### 2. 動的モード
+
+動的モードでは、Intlayerは`useIntlayer`を`useDictionaryAsync`に置き換えます。これは`import()`（Suspenseのような仕組み）を使用して、現在のロケールのJSONを遅延ロードします。
+
+- **利点:** **ロケール単位のツリーシェイキング。** 英語版を閲覧しているユーザーは英語の辞書のみをダウンロードし、フランス語の辞書は一切ロードされません。
+- **欠点:** ハイドレーション時にコンポーネントごとにネットワークリクエスト（アセット取得）が発生します。
+- **最適な用途:** 大きなテキストブロック、記事、多言語対応でバンドルサイズが重要なアプリケーション。
+
+**変換後のコード例:**
+
+```tsx
+// あなたのコード
+const content = useIntlayer("my-key");
+
+// 最適化されたコード（動的）
+const content = useDictionaryAsync({
+  en: () =>
+    import(".intlayer/dynamic_dictionary/en.json").then((mod) => mod.default),
+  fr: () =>
+    import(".intlayer/dynamic_dictionary/fr.json").then((mod) => mod.default),
+});
+```
+
+> `importMode: 'dynamic'` を使用する場合、1ページに `useIntlayer` を使ったコンポーネントが100個あると、ブラウザは100回の個別フェッチを試みます。この「リクエストの滝」を避けるために、コンテンツをより少ない `.content` ファイル（例：ページセクションごとに1つの辞書）にまとめ、アトムコンポーネントごとに分けるのは避けてください。
+
+> 現時点で、`importMode: 'dynamic'` は Vue と Svelte で完全にはサポートされていません。これらのフレームワークでは、今後のアップデートまで `importMode: 'static'` の使用を推奨します。
+
+### 3. ライブモード
+
+動的モードと同様に動作しますが、最初にIntlayer Live Sync APIから辞書を取得しようとします。API呼び出しが失敗した場合やコンテンツがライブ更新用にマークされていない場合は、動的インポートにフォールバックします。
+
+> 詳細はCMSドキュメントをご覧ください: [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ja/intlayer_CMS.md)
+
+## まとめ: 静的モード vs 動的モード
+
+| 機能                       | 静的モード                               | 動的モード                            |
+| :------------------------- | :--------------------------------------- | :------------------------------------ |
+| **JSバンドルサイズ**       | 大きい（コンポーネントの全言語を含む）   | 最小（コードのみ、コンテンツなし）    |
+| **初期読み込み**           | 即時（コンテンツはバンドル内に含まれる） | わずかな遅延（JSONを取得）            |
+| **ネットワークリクエスト** | 追加リクエストなし                       | 辞書ごとに1リクエスト                 |
+| **ツリーシェイキング**     | コンポーネントレベル                     | コンポーネントレベル + ロケールレベル |
+| **最適な使用例**           | UIコンポーネント、小規模アプリ           | テキスト量が多いページ、多言語対応    |

package/docs/ja/vs_code_extension.md

@@ -42,6 +42,10 @@ history:
 
 ## 機能
 
+![コンテンツを抽出](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_extract_content.gif?raw=true)
+
+- **コンテンツを抽出** – React / Vue / Svelte コンポーネントからコンテンツを抽出します
+
 ![辞書を埋める](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_fill_active_dictionary.gif?raw=true)
 
 - **インスタントナビゲーション** – `useIntlayer` キーをクリックすると、正しいコンテンツファイルに素早くジャンプします。

package/docs/ko/bundle_optimization.md

@@ -0,0 +1,180 @@
+---
+createdAt: 2025-11-25
+updatedAt: 2025-11-25
+title: i18n 번들 크기 및 성능 최적화
+description: 국제화(i18n) 콘텐츠를 최적화하여 애플리케이션 번들 크기를 줄이세요. Intlayer를 사용하여 사전의 트리 쉐이킹과 지연 로딩을 활용하는 방법을 알아보세요.
+keywords:
+  - 번들 최적화
+  - 콘텐츠 자동화
+  - 동적 콘텐츠
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - bundle-optimization
+history:
+  - version: 6.0.0
+    date: 2025-11-25
+    changes: 초기 기록
+---
+
+# i18n 번들 크기 및 성능 최적화
+
+전통적인 JSON 파일 기반 i18n 솔루션에서 가장 흔한 문제 중 하나는 콘텐츠 크기 관리입니다. 개발자가 수동으로 콘텐츠를 네임스페이스로 분리하지 않으면, 사용자는 단일 페이지를 보기 위해서도 모든 페이지와 잠재적으로 모든 언어에 대한 번역을 다운로드하게 되는 경우가 많습니다.
+
+예를 들어, 10개의 페이지가 10개 언어로 번역된 애플리케이션의 경우, 사용자는 실제로 필요한 **한 개**의 페이지(현재 언어의 현재 페이지)만 필요함에도 불구하고 100개의 페이지 콘텐츠를 다운로드하게 될 수 있습니다. 이는 대역폭 낭비와 느린 로드 시간으로 이어집니다.
+
+> 이를 감지하기 위해 `rollup-plugin-visualizer`(vite), `@next/bundle-analyzer`(next.js), 또는 `webpack-bundle-analyzer`(React CRA / Angular 등)와 같은 번들 분석기를 사용할 수 있습니다.
+
+**Intlayer는 빌드 타임 최적화를 통해 이 문제를 해결합니다.** Intlayer는 코드 분석을 통해 각 컴포넌트에서 실제로 사용되는 사전을 감지하고, 필요한 콘텐츠만 번들에 다시 주입합니다.
+
+## 목차
+
+<TOC />
+
+## 작동 방식
+
+Intlayer는 **컴포넌트별 접근 방식**을 사용합니다. 전역 JSON 파일과 달리, 콘텐츠가 컴포넌트 옆이나 내부에 정의됩니다. 빌드 과정에서 Intlayer는 다음을 수행합니다:
+
+1.  코드에서 `useIntlayer` 호출을 **분석**합니다.
+2.  해당 사전 콘텐츠를 **생성**합니다.
+3.  구성에 따라 `useIntlayer` 호출을 최적화된 코드로 **대체**합니다.
+
+이를 통해 다음을 보장합니다:
+
+- 컴포넌트가 임포트되지 않으면, 해당 콘텐츠는 번들에 포함되지 않습니다 (Dead Code Elimination).
+- 컴포넌트가 지연 로드(lazy-loaded)되면, 해당 콘텐츠도 지연 로드됩니다.
+
+## 플랫폼별 설정
+
+### Next.js
+
+Next.js는 빌드에 SWC를 사용하기 때문에 변환을 처리하기 위해 `@intlayer/swc` 플러그인이 필요합니다.
+
+> 이 플러그인은 SWC 플러그인이 Next.js에서 아직 실험적이기 때문에 기본적으로 설치되어 있습니다. 향후 변경될 수 있습니다.
+
+### Vite
+
+Vite는 `vite-intlayer`의 의존성으로 포함된 `@intlayer/babel` 플러그인을 사용합니다. 최적화는 기본적으로 활성화되어 있습니다.
+
+### Webpack
+
+Webpack에서 Intlayer를 사용한 번들 최적화를 활성화하려면 적절한 Babel(`@intlayer/babel`) 또는 SWC(`@intlayer/swc`) 플러그인을 설치하고 구성해야 합니다.
+
+### Expo / Lynx
+
+이 플랫폼에서는 번들 최적화가 **아직 지원되지 않습니다**. 향후 릴리스에서 지원이 추가될 예정입니다.
+
+## 구성
+
+Intlayer가 번들을 최적화하는 방식을 `intlayer.config.ts` 파일의 `build` 속성을 통해 제어할 수 있습니다.
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  build: {
+    optimize: true,
+    importMode: "static", // 또는 'dynamic'
+    traversePattern: ["**/*.{js,ts,mjs,cjs,jsx,tsx}", "!**/node_modules/**"],
+  },
+};
+
+export default config;
+```
+
+> 대부분의 경우 기본값인 `optimize` 옵션을 유지하는 것이 권장됩니다.
+
+> 자세한 내용은 문서 설정을 참조하세요: [Configuration](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/configuration.md)
+
+### 빌드 옵션
+
+`build` 구성 객체 아래에서 다음 옵션들을 사용할 수 있습니다:
+
+| 속성                  | 타입                            | 기본값                          | 설명                                                                                                                                                                                                            |
+| :-------------------- | :------------------------------ | :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`optimize`**        | `boolean`                       | `undefined`                     | 빌드 최적화가 활성화되는지 여부를 제어합니다. `true`인 경우, Intlayer는 사전 호출을 최적화된 인젝션으로 대체합니다. `false`인 경우 최적화가 비활성화됩니다. 프로덕션 환경에서는 이상적으로 `true`로 설정합니다. |
+| **`importMode`**      | `'static' , 'dynamic' , 'live'` | `'static'`                      | 사전이 로드되는 방식을 결정합니다(아래 세부사항 참조).                                                                                                                                                          |
+| **`traversePattern`** | `string[]`                      | `['**/*.{js,ts,jsx,tsx}', ...]` | Intlayer가 최적화를 위해 스캔할 파일을 정의하는 Glob 패턴입니다. 관련 없는 파일을 제외하고 빌드 속도를 높이는 데 사용하세요.                                                                                    |
+| **`outputFormat`**    | `'esm', 'cjs'`                  | `'esm', 'cjs'`                  | 빌드된 사전의 출력 형식을 제어합니다.                                                                                                                                                                           |
+
+## Import Modes
+
+`importMode` 설정은 사전 콘텐츠가 컴포넌트에 어떻게 주입되는지를 결정합니다.
+
+### 1. Static Mode (`default`)
+
+정적 모드에서 Intlayer는 `useIntlayer`를 `useDictionary`로 대체하고 사전을 JavaScript 번들에 직접 주입합니다.
+
+- **장점:** 즉각적인 렌더링(동기적), 하이드레이션 시 추가 네트워크 요청 없음.
+- **단점:** 번들에 해당 컴포넌트에 사용 가능한 **모든** 언어의 번역이 포함됩니다.
+- **적합한 경우:** 싱글 페이지 애플리케이션(SPA).
+
+**변환된 코드 예시:**
+
+```tsx
+// 원본 코드
+const content = useIntlayer("my-key");
+
+// 최적화된 코드 (정적)
+const content = useDictionary({
+  key: "my-key",
+  content: {
+    nodeType: "translation",
+    translation: {
+      en: "My title",
+      fr: "Mon titre",
+    },
+  },
+});
+```
+
+### 2. 동적 모드
+
+동적 모드에서 Intlayer는 `useIntlayer`를 `useDictionaryAsync`로 대체합니다. 이는 `import()` (Suspense와 유사한 메커니즘)를 사용하여 현재 로케일에 해당하는 JSON을 지연 로드합니다.
+
+- **장점:** **로케일 단위 트리 쉐이킹.** 영어 버전을 보는 사용자는 영어 사전만 다운로드합니다. 프랑스어 사전은 절대 로드되지 않습니다.
+- **단점:** 하이드레이션 시 컴포넌트별로 네트워크 요청(자산 페치)이 발생합니다.
+- **적합한 경우:** 대용량 텍스트 블록, 기사, 또는 번들 크기가 중요한 다국어 지원 애플리케이션.
+
+**변환된 코드 예시:**
+
+```tsx
+// Your code
+const content = useIntlayer("my-key");
+
+// Optimized code (Dynamic)
+const content = useDictionaryAsync({
+  en: () =>
+    import(".intlayer/dynamic_dictionary/en.json").then((mod) => mod.default),
+  fr: () =>
+    import(".intlayer/dynamic_dictionary/fr.json").then((mod) => mod.default),
+});
+```
+
+> `importMode: 'dynamic'`를 사용할 때, 한 페이지에 `useIntlayer`를 사용하는 컴포넌트가 100개라면 브라우저는 100개의 별도 요청을 시도합니다. 이러한 "워터폴" 요청을 피하기 위해, 콘텐츠를 각 원자 컴포넌트별로 나누기보다는 `.content` 파일 수를 줄여서(예: 페이지 섹션별 사전 하나) 그룹화하는 것이 좋습니다.
+
+> 현재 `importMode: 'dynamic'`은 Vue와 Svelte에서 완전히 지원되지 않습니다. 이 프레임워크들에서는 추가 업데이트가 있을 때까지 `importMode: 'static'` 사용을 권장합니다.
+
+### 3. 라이브 모드 (Live Mode)
+
+동적 모드와 유사하게 동작하지만, 먼저 Intlayer Live Sync API에서 사전을 가져오려고 시도합니다. API 호출이 실패하거나 콘텐츠가 라이브 업데이트로 표시되지 않은 경우에는 동적 임포트로 대체됩니다.
+
+> 자세한 내용은 CMS 문서를 참조하세요: [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/intlayer_CMS.md)
+
+## 요약: 정적 vs 동적
+
+| 기능               | 정적 모드                              | 동적 모드                            |
+| :----------------- | :------------------------------------- | :----------------------------------- |
+| **JS 번들 크기**   | 더 큼 (컴포넌트에 대한 모든 언어 포함) | 가장 작음 (코드만 포함, 콘텐츠 없음) |
+| **초기 로드**      | 즉시 (콘텐츠가 번들에 포함됨)          | 약간의 지연 (JSON을 가져옴)          |
+| **네트워크 요청**  | 추가 요청 없음                         | 사전별로 1회 요청                    |
+| **트리 쉐이킹**    | 컴포넌트 수준                          | 컴포넌트 수준 + 로케일 수준          |
+| **최적 사용 사례** | UI 컴포넌트, 소규모 앱                 | 텍스트가 많은 페이지, 다국어 지원    |

package/docs/ko/vs_code_extension.md

@@ -42,6 +42,10 @@ history:
 
 ## 기능
 
+![콘텐츠 추출](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_extract_content.gif?raw=true)
+
+- **콘텐츠 추출** – React / Vue / Svelte 컴포넌트에서 콘텐츠를 추출합니다
+
 ![사전 채우기](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_fill_active_dictionary.gif?raw=true)
 
 - **즉시 탐색** – `useIntlayer` 키를 클릭하면 올바른 콘텐츠 파일로 빠르게 이동합니다.

package/docs/pl/bundle_optimization.md

@@ -0,0 +1,180 @@
+---
+createdAt: 2025-11-25
+updatedAt: 2025-11-25
+title: Optymalizacja rozmiaru i wydajności pakietu i18n
+description: Zmniejsz rozmiar pakietu aplikacji poprzez optymalizację treści internacjonalizacji (i18n). Dowiedz się, jak wykorzystać tree shaking i lazy loading słowników z Intlayer.
+keywords:
+  - Optymalizacja pakietu
+  - Automatyzacja treści
+  - Treść dynamiczna
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - bundle-optimization
+history:
+  - version: 6.0.0
+    date: 2025-11-25
+    changes: Inicjalizacja historii
+---
+
+# Optymalizacja rozmiaru i wydajności pakietu i18n
+
+Jednym z najczęstszych wyzwań tradycyjnych rozwiązań i18n opartych na plikach JSON jest zarządzanie rozmiarem treści. Jeśli deweloperzy nie rozdzielą ręcznie treści na przestrzenie nazw, użytkownicy często kończą z pobieraniem tłumaczeń dla każdej strony i potencjalnie każdego języka, tylko po to, aby wyświetlić pojedynczą stronę.
+
+Na przykład aplikacja z 10 stronami przetłumaczonymi na 10 języków może skutkować tym, że użytkownik pobierze zawartość 100 stron, mimo że potrzebuje tylko **jednej** (aktualnej strony w aktualnym języku). Prowadzi to do marnowania przepustowości i wolniejszego ładowania.
+
+> Aby to wykryć, możesz użyć analizatora pakietów takiego jak `rollup-plugin-visualizer` (vite), `@next/bundle-analyzer` (next.js) lub `webpack-bundle-analyzer` (React CRA / Angular / itd).
+
+**Intlayer rozwiązuje ten problem poprzez optymalizację w czasie kompilacji.** Analizuje Twój kod, aby wykryć, które słowniki są faktycznie używane w poszczególnych komponentach i wstrzykuje do pakietu tylko niezbędną zawartość.
+
+## Spis treści
+
+<TOC />
+
+## Jak to działa
+
+Intlayer stosuje **podejście per-komponent**. W przeciwieństwie do globalnych plików JSON, Twoja zawartość jest definiowana obok lub wewnątrz komponentów. Podczas procesu budowania Intlayer:
+
+1.  **Analizuje** Twój kod, aby znaleźć wywołania `useIntlayer`.
+2.  **Buduje** odpowiadającą zawartość słownika.
+3.  **Zastępuje** wywołanie `useIntlayer` zoptymalizowanym kodem na podstawie Twojej konfiguracji.
+
+To zapewnia, że:
+
+- Jeśli komponent nie jest importowany, jego zawartość nie jest dołączana do pakietu (eliminacja martwego kodu).
+- Jeśli komponent jest ładowany leniwie, jego zawartość jest również ładowana leniwie.
+
+## Konfiguracja według platformy
+
+### Next.js
+
+Next.js wymaga wtyczki `@intlayer/swc` do obsługi transformacji, ponieważ Next.js używa SWC do budowania.
+
+> Ta wtyczka jest instalowana domyślnie, ponieważ wtyczki SWC są nadal eksperymentalne dla Next.js. Może się to zmienić w przyszłości.
+
+### Vite
+
+Vite używa wtyczki `@intlayer/babel`, która jest dołączona jako zależność `vite-intlayer`. Optymalizacja jest domyślnie włączona.
+
+### Webpack
+
+Aby włączyć optymalizację pakietu z Intlayer na Webpack, musisz zainstalować i skonfigurować odpowiednią wtyczkę Babel (`@intlayer/babel`) lub SWC (`@intlayer/swc`).
+
+### Expo / Lynx
+
+Optymalizacja pakietu jest **jeszcze niedostępna** dla tej platformy. Wsparcie zostanie dodane w przyszłej wersji.
+
+## Konfiguracja
+
+Możesz kontrolować, jak Intlayer optymalizuje Twój pakiet za pomocą właściwości `build` w pliku `intlayer.config.ts`.
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  build: {
+    optimize: true,
+    importMode: "static", // lub 'dynamic'
+    traversePattern: ["**/*.{js,ts,mjs,cjs,jsx,tsx}", "!**/node_modules/**"],
+  },
+};
+
+export default config;
+```
+
+> Zaleca się pozostawienie domyślnej opcji `optimize` w większości przypadków.
+
+> Zobacz dokumentację konfiguracji, aby uzyskać więcej szczegółów: [Konfiguracja](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md)
+
+### Opcje budowania
+
+Dostępne są następujące opcje w obiekcie konfiguracyjnym `build`:
+
+| Właściwość            | Typ                             | Domyślna wartość                | Opis                                                                                                                                                                                                                              |
+| :-------------------- | :------------------------------ | :------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`optimize`**        | `boolean`                       | `undefined`                     | Kontroluje, czy optymalizacja builda jest włączona. Jeśli `true`, Intlayer zastępuje wywołania słowników zoptymalizowanymi wstrzyknięciami. Jeśli `false`, optymalizacja jest wyłączona. Najlepiej ustawić na `true` w produkcji. |
+| **`importMode`**      | `'static' , 'dynamic' , 'live'` | `'static'`                      | Określa sposób ładowania słowników (szczegóły poniżej).                                                                                                                                                                           |
+| **`traversePattern`** | `string[]`                      | `['**/*.{js,ts,jsx,tsx}', ...]` | Wzorce glob określające, które pliki Intlayer powinien skanować pod kątem optymalizacji. Użyj tego, aby wykluczyć niepowiązane pliki i przyspieszyć proces budowania.                                                             |
+| **`outputFormat`**    | `'esm', 'cjs'`                  | `'esm', 'cjs'`                  | Kontroluje format wyjściowy zbudowanych słowników.                                                                                                                                                                                |
+
+## Tryby importu
+
+Ustawienie `importMode` określa, jak zawartość słownika jest wstrzykiwana do twojego komponentu.
+
+### 1. Tryb statyczny (`default`)
+
+W trybie statycznym Intlayer zastępuje `useIntlayer` funkcją `useDictionary` i wstrzykuje słownik bezpośrednio do pakietu JavaScript.
+
+- **Zalety:** Natychmiastowe renderowanie (synchroniczne), brak dodatkowych żądań sieciowych podczas hydracji.
+- **Wady:** Pakiet zawiera tłumaczenia dla **wszystkich** dostępnych języków dla danego komponentu.
+- **Najlepsze zastosowanie:** Aplikacje jednostronicowe (SPA).
+
+**Przykład przekształconego kodu:**
+
+```tsx
+// Twój kod
+const content = useIntlayer("my-key");
+
+// Kod zoptymalizowany (statyczny)
+const content = useDictionary({
+  key: "my-key",
+  content: {
+    nodeType: "translation",
+    translation: {
+      en: "My title",
+      fr: "Mon titre",
+    },
+  },
+});
+```
+
+### 2. Tryb dynamiczny
+
+W trybie dynamicznym Intlayer zastępuje `useIntlayer` funkcją `useDictionaryAsync`. Używa to `import()` (mechanizm podobny do Suspense) do leniwego ładowania konkretnie pliku JSON dla bieżącej lokalizacji.
+
+- **Zalety:** **Tree shaking na poziomie lokalizacji.** Użytkownik przeglądający wersję angielską pobierze _tylko_ angielski słownik. Francuski słownik nigdy nie jest ładowany.
+- **Wady:** Wywołuje żądanie sieciowe (pobranie zasobu) dla każdego komponentu podczas hydracji.
+- **Najlepsze zastosowanie:** Duże bloki tekstu, artykuły lub aplikacje obsługujące wiele języków, gdzie rozmiar pakietu jest krytyczny.
+
+**Przykład przekształconego kodu:**
+
+```tsx
+// Twój kod
+const content = useIntlayer("my-key");
+
+// Kod zoptymalizowany (Dynamiczny)
+const content = useDictionaryAsync({
+  en: () =>
+    import(".intlayer/dynamic_dictionary/en.json").then((mod) => mod.default),
+  fr: () =>
+    import(".intlayer/dynamic_dictionary/fr.json").then((mod) => mod.default),
+});
+```
+
+> Korzystając z `importMode: 'dynamic'`, jeśli na jednej stronie masz 100 komponentów używających `useIntlayer`, przeglądarka spróbuje wykonać 100 osobnych pobrań. Aby uniknąć tego „efektu wodospadu” żądań, grupuj zawartość w mniejszej liczbie plików `.content` (np. jeden słownik na sekcję strony) zamiast po jednym na każdy atomowy komponent.
+
+> Obecnie `importMode: 'dynamic'` nie jest w pełni wspierany dla Vue i Svelte. Zaleca się używanie `importMode: 'static'` dla tych frameworków do czasu kolejnych aktualizacji.
+
+### 3. Tryb na żywo (Live Mode)
+
+Działa podobnie do trybu Dynamic, ale najpierw próbuje pobrać słowniki z Intlayer Live Sync API. Jeśli wywołanie API się nie powiedzie lub zawartość nie jest oznaczona do aktualizacji na żywo, następuje powrót do importu dynamicznego.
+
+> Zobacz dokumentację CMS, aby uzyskać więcej szczegółów: [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_CMS.md)
+
+## Podsumowanie: Static vs Dynamic
+
+| Funkcja                    | Tryb Static                                       | Tryb Dynamic                                |
+| :------------------------- | :------------------------------------------------ | :------------------------------------------ |
+| **Rozmiar pakietu JS**     | Większy (zawiera wszystkie języki dla komponentu) | Najmniejszy (tylko kod, bez zawartości)     |
+| **Początkowe ładowanie**   | Natychmiastowe (zawartość jest w pakiecie)        | Niewielkie opóźnienie (pobiera JSON)        |
+| **Żądania sieciowe**       | 0 dodatkowych żądań                               | 1 żądanie na słownik                        |
+| **Tree Shaking**           | Na poziomie komponentu                            | Na poziomie komponentu + lokalizacji        |
+| **Najlepsze zastosowanie** | Komponenty UI, małe aplikacje                     | Strony z dużą ilością tekstu, wiele języków |

package/docs/pl/how_works_intlayer.md

@@ -146,7 +146,7 @@ Pakiet `vue-intlayer` jest używany do interpretacji słowników Intlayer i umo
 
 Pakiet `nuxt-intlayer` jest modułem Nuxt, który umożliwia korzystanie ze słowników Intlayer w aplikacjach Nuxt. Integruje on niezbędne funkcje, aby Intlayer działał w środowisku Nuxt, takie jak middleware tłumaczeń, routing czy konfiguracja pliku `nuxt.config.js`.
 
-### svelte-intlayer (WIP)
+### svelte-intlayer
 
 Pakiet `svelte-intlayer` jest używany do interpretacji słowników Intlayer i umożliwia ich użycie w aplikacjach Svelte.
 

package/docs/pl/vs_code_extension.md

@@ -42,6 +42,10 @@ Link do rozszerzenia: [https://marketplace.visualstudio.com/items?itemName=Intla
 
 ## Funkcje
 
+![Wyodrębnij zawartość](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_extract_content.gif?raw=true)
+
+- **Wyodrębnij Zawartość** – Wyodrębnij zawartość z komponentów React / Vue / Svelte
+
 ![Wypełnianie słowników](https://github.com/aymericzip/intlayer-vs-code-extension/blob/master/assets/vscode_extention_fill_active_dictionary.gif?raw=true)
 
 - **Natychmiastowa Nawigacja** – Szybko przejdź do odpowiedniego pliku z treścią, klikając na klucz `useIntlayer`.