@intlayer/docs 7.3.0 → 7.3.2-canary.0

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,184 @@
+---
+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/my-key/en.json").then(
+      (mod) => mod.default
+    ),
+  fr: () =>
+    import(".intlayer/dynamic_dictionary/my-key/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/compiler.md

@@ -0,0 +1,133 @@
+---
+createdAt: 2025-09-09
+updatedAt: 2025-09-09
+title: Intlayer 컴파일러 | i18n을 위한 자동화된 콘텐츠 추출
+description: Intlayer 컴파일러로 국제화 프로세스를 자동화하세요. Vite, Next.js 등에서 더 빠르고 효율적인 i18n을 위해 컴포넌트에서 직접 콘텐츠를 추출합니다.
+keywords:
+  - Intlayer
+  - 컴파일러
+  - 국제화
+  - i18n
+  - 자동화
+  - 추출
+  - 속도
+  - Vite
+  - Next.js
+  - React
+  - Vue
+  - Svelte
+slugs:
+  - doc
+  - compiler
+history:
+  - version: 7.3.1
+    date: 2025-11-27
+    changes: 컴파일러 출시
+---
+
+# Intlayer 컴파일러 | i18n을 위한 자동화된 콘텐츠 추출
+
+## Intlayer 컴파일러란?
+
+**Intlayer 컴파일러**는 애플리케이션의 국제화(i18n) 프로세스를 자동화하도록 설계된 강력한 도구입니다. 소스 코드(JSX, TSX, Vue, Svelte)에서 콘텐츠 선언을 스캔하고 추출하여 필요한 사전(dictionary) 파일을 자동으로 생성합니다. 이를 통해 콘텐츠를 컴포넌트와 함께 위치시킬 수 있으며, Intlayer가 사전의 관리 및 동기화를 처리합니다.
+
+## Intlayer 컴파일러를 사용하는 이유
+
+- **자동화**: 콘텐츠를 사전에 수동으로 복사하여 붙여넣는 작업을 제거합니다.
+- **속도**: 빌드 프로세스가 빠르게 유지되도록 최적화된 콘텐츠 추출을 제공합니다.
+- **개발자 경험**: 콘텐츠 선언을 사용되는 위치에 그대로 유지하여 유지보수성을 향상시킵니다.
+- **실시간 업데이트**: 개발 중 즉각적인 피드백을 위한 Hot Module Replacement(HMR)를 지원합니다.
+
+더 깊은 비교를 원한다면 [Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/ko/compiler_vs_declarative_i18n.md) 블로그 게시물을 참조하세요.
+
+## Intlayer 컴파일러를 사용하지 않는 이유
+
+컴파일러는 훌륭한 "바로 작동" 경험을 제공하지만, 인지해야 할 몇 가지 트레이드오프도 도입합니다:
+
+- **휴리스틱 모호성**: 컴파일러는 사용자 지향 콘텐츠와 애플리케이션 로직(예: `className="active"`, 상태 코드, 제품 ID)을 추측해야 합니다. 복잡한 코드베이스에서는 이것이 오탐지 또는 누락된 문자열로 이어질 수 있으며, 수동 주석 및 예외 처리가 필요합니다.
+- **정적 추출만**: 컴파일러 기반 추출은 정적 분석에 의존합니다. 런타임에만 존재하는 문자열(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 transform`([CLI 문서](https://github.com/aymericzip/intlayer/blob/main/docs/docs/ko/cli/transform.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) 참조)도 제공합니다.
+
+## 사용법
+
+### Vite
+
+Vite 기반 애플리케이션(React, Vue, Svelte 등)의 경우, 컴파일러를 사용하는 가장 쉬운 방법은 `vite-intlayer` 플러그인을 사용하는 것입니다.
+
+#### 설치
+
+```bash
+npm install vite-intlayer
+```
+
+#### 구성
+
+`vite.config.ts` 파일을 업데이트하여 `intlayerCompiler` 플러그인을 포함하세요:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer, intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer(),
+    intlayerCompiler(), // 컴파일러 플러그인 추가
+  ],
+});
+```
+
+#### 프레임워크 지원
+
+Vite 플러그인은 다양한 파일 유형을 자동으로 감지하고 처리합니다:
+
+- **React / JSX / TSX**: 기본적으로 처리됩니다.
+- **Vue**: `@intlayer/vue-compiler`가 필요합니다.
+- **Svelte**: `@intlayer/svelte-compiler`가 필요합니다.
+
+사용하는 프레임워크에 맞는 컴파일러 패키지를 반드시 설치하세요:
+
+```bash
+# Vue용
+npm install @intlayer/vue-compiler
+
+# Svelte용
+npm install @intlayer/svelte-compiler
+```
+
+### Next.js (Babel)
+
+Next.js 또는 Babel을 사용하는 다른 Webpack 기반 애플리케이션의 경우, `@intlayer/babel` 플러그인을 사용하여 컴파일러를 구성할 수 있습니다.
+
+#### 설치
+
+```bash
+npm install @intlayer/babel
+```
+
+#### 구성
+
+`babel.config.js`(또는 `babel.config.json`) 파일을 업데이트하여 추출 플러그인을 포함하세요. Intlayer 구성을 자동으로 로드하는 헬퍼 함수 `getExtractPluginOptions`를 제공합니다.
+
+```js fileName="babel.config.js"
+const {
+  intlayerExtractBabelPlugin,
+  intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getOptimizePluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    // Extract content from components into dictionaries
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+    // Optimize imports by replacing useIntlayer with direct dictionary imports
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
+};
+```
+
+이 구성은 컴포넌트 내에 선언된 콘텐츠가 자동으로 추출되어 빌드 과정 중에 사전 생성에 사용되도록 보장합니다.

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,184 @@
+---
+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/my-key/en.json").then(
+      (mod) => mod.default
+    ),
+  fr: () =>
+    import(".intlayer/dynamic_dictionary/my-key/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/compiler.md

@@ -0,0 +1,133 @@
+---
+createdAt: 2025-09-09
+updatedAt: 2025-09-09
+title: Intlayer Compiler | Zautomatyzowane wydobywanie treści dla i18n
+description: Zautomatyzuj proces internacjonalizacji za pomocą Intlayer Compiler. Wydobywaj treści bezpośrednio z komponentów dla szybszego i bardziej efektywnego i18n w Vite, Next.js i innych.
+keywords:
+  - Intlayer
+  - Compiler
+  - Internacjonalizacja
+  - i18n
+  - Automatyzacja
+  - Wydobywanie
+  - Szybkość
+  - Vite
+  - Next.js
+  - React
+  - Vue
+  - Svelte
+slugs:
+  - doc
+  - compiler
+history:
+  - version: 7.3.1
+    date: 2025-11-27
+    changes: Wydanie kompilatora
+---
+
+# Intlayer Compiler | Zautomatyzowane wydobywanie treści dla i18n
+
+## Czym jest Intlayer Compiler?
+
+**Intlayer Compiler** to potężne narzędzie zaprojektowane w celu automatyzacji procesu internacjonalizacji (i18n) w Twoich aplikacjach. Przeszukuje Twój kod źródłowy (JSX, TSX, Vue, Svelte) w poszukiwaniu deklaracji treści, wydobywa je i automatycznie generuje niezbędne pliki słowników. Pozwala to na utrzymanie treści współlokalnie z komponentami, podczas gdy Intlayer zajmuje się zarządzaniem i synchronizacją Twoich słowników.
+
+## Dlaczego warto używać Intlayer Compiler?
+
+- **Automatyzacja**: Eliminuje ręczne kopiowanie i wklejanie treści do słowników.
+- **Szybkość**: Optymalizowane wydobywanie treści zapewnia szybki proces budowania.
+- **Doświadczenie programisty**: Zachowaj deklaracje treści dokładnie tam, gdzie są używane, co poprawia utrzymanie kodu.
+- **Aktualizacje na żywo**: Obsługuje Hot Module Replacement (HMR) dla natychmiastowej informacji zwrotnej podczas tworzenia aplikacji.
+
+Zobacz wpis na blogu [Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/compiler_vs_declarative_i18n.md) dla głębszego porównania.
+
+## Dlaczego nie używać Intlayer Compiler?
+
+Chociaż kompilator oferuje doskonałe doświadczenie "działa od razu", wprowadza również pewne kompromisy, o których powinieneś wiedzieć:
+
+- **Niejednoznaczność heurystyczna**: Kompilator musi zgadywać, co jest treścią skierowaną do użytkownika, a co logiką aplikacji (np. `className="active"`, kody statusu, ID produktów). W złożonych bazach kodu może to prowadzić do fałszywych pozytywów lub pominiętych ciągów znaków, które wymagają ręcznych adnotacji i wyjątków.
+- **Tylko statyczna ekstrakcja**: Ekstrakcja oparta na kompilatorze opiera się na analizie statycznej. Ciągi znaków, które istnieją tylko w czasie wykonywania (kody błędów API, pola CMS itp.), nie mogą być odkryte ani przetłumaczone przez sam kompilator, więc nadal potrzebujesz uzupełniającej strategii i18n czasu wykonywania.
+
+Aby uzyskać głębsze porównanie architektoniczne, zobacz wpis na blogu [Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/pl/compiler_vs_declarative_i18n.md).
+
+Jako alternatywę, aby zautomatyzować proces i18n przy zachowaniu pełnej kontroli nad treścią, Intlayer zapewnia również polecenie auto-ekstrakcji `intlayer transform` (zobacz [dokumentację CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/cli/transform.md)) lub polecenie `Intlayer: extract content to Dictionary` z rozszerzenia Intlayer VS Code (zobacz [dokumentację rozszerzenia VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/vs_code_extension.md)).
+
+## Użycie
+
+### Vite
+
+Dla aplikacji opartych na Vite (React, Vue, Svelte itp.) najprostszym sposobem użycia kompilatora jest wtyczka `vite-intlayer`.
+
+#### Instalacja
+
+```bash
+npm install vite-intlayer
+```
+
+#### Konfiguracja
+
+Zaktualizuj swój plik `vite.config.ts`, aby dołączyć wtyczkę `intlayerCompiler`:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer, intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer(),
+    intlayerCompiler(), // Dodaje wtyczkę kompilatora
+  ],
+});
+```
+
+#### Wsparcie dla frameworków
+
+Wtyczka Vite automatycznie wykrywa i obsługuje różne typy plików:
+
+- **React / JSX / TSX**: Obsługiwane natywnie.
+- **Vue**: Wymaga `@intlayer/vue-compiler`.
+- **Svelte**: Wymaga `@intlayer/svelte-compiler`.
+
+Upewnij się, że zainstalowałeś odpowiedni pakiet kompilatora dla swojego frameworka:
+
+```bash
+# Dla Vue
+npm install @intlayer/vue-compiler
+
+# Dla Svelte
+npm install @intlayer/svelte-compiler
+```
+
+### Next.js (Babel)
+
+Dla Next.js lub innych aplikacji opartych na Webpack z użyciem Babel, możesz skonfigurować kompilator za pomocą wtyczki `@intlayer/babel`.
+
+#### Instalacja
+
+```bash
+npm install @intlayer/babel
+```
+
+#### Konfiguracja
+
+Zaktualizuj swój plik `babel.config.js` (lub `babel.config.json`), aby uwzględnić wtyczkę ekstrakcji. Udostępniamy pomocniczą funkcję `getExtractPluginOptions`, która automatycznie ładuje Twoją konfigurację Intlayer.
+
+```js fileName="babel.config.js"
+const {
+  intlayerExtractBabelPlugin,
+  intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getOptimizePluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    // Extract content from components into dictionaries
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+    // Optimize imports by replacing useIntlayer with direct dictionary imports
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
+};
+```
+
+Ta konfiguracja zapewnia, że zawartość zadeklarowana w Twoich komponentach jest automatycznie wyodrębniana i używana do generowania słowników podczas procesu budowania.

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.