@intlayer/docs 9.1.3 → 9.2.0

package/docs/ko/self_hosting.md

@@ -64,6 +64,32 @@ Chromium (Puppeteer 스크린샷 생성에 사용됨)은 백엔드 이미지 내
 
 ## 빠른 시작
 
+게시된 이미지를 pull하고 실행한 후 MongoDB Atlas 자격증명과 보안 키를 제공합니다:
+
+```sh
+docker run -d --name intlayer \
+  -p 3000:3000 \
+  -p 3100:3100 \
+  -p 9000:9000 \
+  -p 9001:9001 \
+  -v intlayer-data:/data \
+  -e DB_ID="<atlas-user>" \
+  -e DB_MDP="<atlas-password>" \
+  -e DB_CLUSTER="<cluster>.xxxxx.mongodb.net" \
+  -e BETTER_AUTH_SECRET="$(openssl rand -hex 32)" \
+  -e S3_SECRET_ACCESS_KEY="$(openssl rand -hex 16)" \
+  -e RESEND_API_KEY="<your-resend-key>" \
+  aymericzip/intlayer-selfhost
+```
+
+그 다음 **http://localhost:3000**을 엽니다.
+
+> 대시보드는 `localhost`에서 제공됩니다. [제한 사항](#limitations)을 참고하세요 — 게시된 이미지에서는 커스텀 도메인이 지원되지 않습니다.
+
+---
+
+## 빠른 시작
+
 ```sh
 curl -fsSL https://intlayer.org/install.sh | sh
 ```
@@ -99,7 +125,16 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 ## 환경 변수
 
-설치 프로그램은 즉시 사용할 수 있는 `.env` 파일을 생성합니다. 아래 표는 모든 변수를 설명합니다.
+### 필수
+
+| Variable               | Example                      | Description                                                                                                                                  |
+| ---------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DB_ID`                | `intlayer`                   | MongoDB Atlas user                                                                                                                           |
+| `DB_MDP`               | _(your password)_            | MongoDB Atlas password                                                                                                                       |
+| `DB_CLUSTER`           | `cluster0.xxxxx.mongodb.net` | MongoDB Atlas cluster host (used in the `mongodb+srv://` URI)                                                                                |
+| `BETTER_AUTH_SECRET`   | _(generated)_                | 32-byte secret for session signing                                                                                                           |
+| `S3_SECRET_ACCESS_KEY` | _(generated)_                | Secret for the bundled MinIO                                                                                                                 |
+| `RESEND_API_KEY`       | _(your key)_                 | Transactional email via Resend. Required for first-run setup unless you configure a global SMTP mailer (see [Global mailer](#global-mailer)) |
 
 ### 필수 (자동 생성 또는 프롬프트)
 
@@ -141,6 +176,26 @@ curl -fsSL https://intlayer.org/install.sh | sh
 
 ---
 
+### Global mailer
+
+기본적으로 모든 트랜잭션 이메일은 `RESEND_API_KEY`를 사용하여 Resend를 통해 전송됩니다. Self-hosted 배포는 대신 환경 변수로 구성된 global mailer를 통해 비조직 이메일(예: 비밀번호 재설정 및 magic link)을 포함한 **모든** 이메일을 라우팅할 수 있습니다.
+
+`MAIL_PROVIDER`를 설정하여 활성화합니다. 설정하지 않으면 기본 Resend mailer가 사용됩니다.
+
+| Variable             | Example                        | Description                                                               |
+| -------------------- | ------------------------------ | ------------------------------------------------------------------------- |
+| `MAIL_PROVIDER`      | `smtp`                         | Global transport: `smtp` 또는 `resend`. 기본값을 사용하려면 설정하지 않음 |
+| `MAIL_FROM`          | `Intlayer <no-reply@acme.com>` | Sender header. 단순 주소 또는 `Name <email>` 형식 허용                    |
+| `MAIL_SMTP_HOST`     | `smtp.acme.com`                | SMTP host (`MAIL_PROVIDER=smtp`일 때 필수)                                |
+| `MAIL_SMTP_PORT`     | `587`                          | SMTP port (기본값: `587`)                                                 |
+| `MAIL_SMTP_SECURE`   | `false`                        | Implicit TLS. port `465`에서는 `true`로 설정                              |
+| `MAIL_SMTP_USER`     | _(your user)_                  | SMTP username (선택사항; unauthenticated relay의 경우 생략)               |
+| `MAIL_SMTP_PASSWORD` | _(your password)_              | SMTP password                                                             |
+
+> Precedence: 조직의 자체 mailer (**Organization** dashboard에서 구성)가 global mailer보다 우선하며, global mailer는 기본 Resend key보다 우선합니다.
+
+---
+
 ## Intlayer 프로젝트 연결하기
 
 스택이 실행되면 프로젝트가 `intlayer.org` 대신 자체 호스팅된 백엔드 및 대시보드를 가리키도록 설정하세요.
@@ -259,47 +314,11 @@ docker run --rm \
 
 ---
 
-## 리버스 프록시 사용 (Nginx / Caddy)
-
-프로덕션 배포의 경우, 앱 및 백엔드 컨테이너를 직접 노출하는 대신 리버스 프록시를 앞에 배치하세요.
-
-### 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는 외부(Atlas)여야 합니다.** 백엔드는 `mongodb+srv://`로만 연결되며(`DB_ID` / `DB_MDP` / `DB_CLUSTER`로 구성됨), 일반 `mongodb://host:27017` — 컨테이너의 자체 번들 `mongod` 포함 — 은 사용할 수 없습니다. MongoDB Atlas 클러스터를 제공하세요.
+- **사용자 정의 도메인 없음.** 모든 브라우저 대면 `VITE_*` URL은 빌드 시 앱에 인라인되며, 게시된 이미지는 `localhost` 값으로 제공됩니다. 대시보드는 `http://localhost:3000`에서 액세스해야 합니다. 공개 도메인에서 제공하려면 대상 URL을 포함하여 이미지를 다시 빌드해야 하며 기본적으로 지원되지 않습니다.
+- **이메일에는 작동하는 메일러가 필요합니다.** 초기 실행 설정은 이메일 확인을 강제하므로 `RESEND_API_KEY` 또는 [글로벌 SMTP 메일러](#global-mailer)(`MAIL_PROVIDER=smtp` + `MAIL_SMTP_*`)를 구성해야 합니다. 첫 번째 관리자가 로그인한 후 각 조직은 대시보드에서 자신의 SMTP 또는 Resend 메일러를 구성할 수도 있습니다.
 
 ---
 
@@ -324,14 +343,6 @@ 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가 준비되기 전에 실행된 경우), 수동으로 버킷을 생성하세요:

package/docs/nl/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-07-11
+updatedAt: 2026-08-06
 title: Configuratie (Configuration)
 description: Leer hoe u Intlayer configureert voor uw applicatie. Begrijp de verschillende instellingen en opties die beschikbaar zijn om Intlayer aan uw behoeften aan te passen.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.1.3
+    date: 2026-08-06
+    changes: "`routing.enableProxy` drieledig maken: niet ingesteld (auto), `true`, `false`"
   - version: 9.0.0
     date: 2026-07-11
     changes: "`analytics` configuratie toegevoegd"
@@ -235,6 +238,19 @@ const config: IntlayerConfig = {
      */
     mode: "prefix-no-default",
 
+    /**
+     * Schakelt de Intlayer locale-routing proxy (middleware) in.
+     * Verzorgt localedetectie, redirects en rewrites in dev, preview en SSR.
+     * - niet ingesteld (auto): dev- en preview-servers houden de routing URL-gestuurd
+     *   en negeren de locale die in cookies en headers is opgeslagen. Prefixen worden
+     *   nog steeds opgelost, de locale wordt nog steeds bewaard en
+     *   Accept-Language-detectie blijft gelden. In productie gedraagt het zich als `true`.
+     * - true: volledig gedrag in elke omgeving.
+     * - false: geen locale-routing.
+     * Standaard: undefined (auto)
+     */
+    enableProxy: undefined,
+
     /**
      * Waar de door de gebruiker gekozen locale moet worden opgeslagen.
      * Opties: 'cookie', 'localStorage', 'sessionStorage', 'header' of een array hiervan.
@@ -713,13 +729,14 @@ Analytics is strikt opt-in: er wordt niets verzameld tenzij `analytics.enabled`
 
 Instellingen die het gedrag van routing regelen, inclusief URL-structuur, opslag van locales en beheer van middleware.
 
-| Veld       | Beschrijving                                                                                                                                                                                                          | Type                                                                                                                                                                                                         | Standaard              | Voorbeeld                                                                                                                                                                                            | Opmerking                                                                                                                                                                                                                                                                         |
-| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mode`     | URL routingmodus voor het beheer van locales.                                                                                                                                                                         | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) of `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: locale wordt op andere manieren beheerd. `'search-params'`: `/dashboard?locale=fr` | Heeft geen invloed op het beheer van cookies of opslag van locales.                                                                                                                                                                                                               |
-| `storage`  | Configuratie van de opslag van de locale op de client.                                                                                                                                                                | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                                   | Zie de tabel met opslagparameters hieronder.                                                                                                                                                                                                                                      |
-| `basePath` | Basispad voor de URL's van de applicatie.                                                                                                                                                                             | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                                          | Als de applicatie op het adres `https://example.com/my-app` werkt, is basePath `'/my-app'` en worden URL's `https://example.com/my-app/en`.                                                                                                                                       |
-| `rewrite`  | Aangepaste URL-herschrijfregels die de standaard routingmodus overschrijven voor specifieke paden. Ondersteunt dynamische parameters `[param]`.                                                                       | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | Zie voorbeeld hieronder                                                                                                                                                                              | • Herschrijfregels hebben voorrang op `mode`.<br/>• Werkt met Next.js en Vite.<br/>• `getLocalizedUrl()` past automatisch de juiste regels toe.<br/>• Zie [Aangepaste URL-herschrijvingen](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md). |
-| `domains`  | Koppelt locales aan domeinhastnamen voor domeingebaseerde routing. Wanneer ingesteld, gebruiken URL's voor die locale dat domein als basis (absolute URL) en wordt er geen locale-voorvoegsel aan het pad toegevoegd. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                                          | • Het standaardprotocol is `https://` wanneer dit niet in de hostnaam is opgenomen.<br/>• Het domein zelf identificeert de locale, dus er wordt geen `/zh/` voorvoegsel toegevoegd.<br/>• `getLocalizedUrl('/', 'zh')` retourneert `https://intlayer.zh/`.                        |
+| Veld          | Beschrijving                                                                                                                                                                                                          | Type                                                                                                                                                                                                         | Standaard              | Voorbeeld                                                                                                                                                                                            | Opmerking                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mode`        | URL routingmodus voor het beheer van locales.                                                                                                                                                                         | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) of `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: locale wordt op andere manieren beheerd. `'search-params'`: `/dashboard?locale=fr` | Heeft geen invloed op het beheer van cookies of opslag van locales.                                                                                                                                                                                                                                                                                                            |
+| `enableProxy` | Schakelt de Intlayer locale-routing proxy (middleware) in.                                                                                                                                                            | `boolean` &#124; <br/> `undefined`                                                                                                                                                                           | `undefined` (auto)     | `true`                                                                                                                                                                                               | • Niet ingesteld (auto): dev- en preview-servers negeren de in cookies/headers opgeslagen locale als redirectbron; prefixen, persistentie en `Accept-Language`-detectie blijven gelden. In productie gedraagt het zich als `true`.<br/>• `true`: volledig gedrag overal.<br/>• `false`: geen locale-routing. Bij Next.js wordt de `intlayerProxy`-middleware een doorgeefluik. |
+| `storage`     | Configuratie van de opslag van de locale op de client.                                                                                                                                                                | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                                   | Zie de tabel met opslagparameters hieronder.                                                                                                                                                                                                                                                                                                                                   |
+| `basePath`    | Basispad voor de URL's van de applicatie.                                                                                                                                                                             | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                                          | Als de applicatie op het adres `https://example.com/my-app` werkt, is basePath `'/my-app'` en worden URL's `https://example.com/my-app/en`.                                                                                                                                                                                                                                    |
+| `rewrite`     | Aangepaste URL-herschrijfregels die de standaard routingmodus overschrijven voor specifieke paden. Ondersteunt dynamische parameters `[param]`.                                                                       | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | Zie voorbeeld hieronder                                                                                                                                                                              | • Herschrijfregels hebben voorrang op `mode`.<br/>• Werkt met Next.js en Vite.<br/>• `getLocalizedUrl()` past automatisch de juiste regels toe.<br/>• Zie [Aangepaste URL-herschrijvingen](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md).                                                                                              |
+| `domains`     | Koppelt locales aan domeinhastnamen voor domeingebaseerde routing. Wanneer ingesteld, gebruiken URL's voor die locale dat domein als basis (absolute URL) en wordt er geen locale-voorvoegsel aan het pad toegevoegd. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                                          | • Het standaardprotocol is `https://` wanneer dit niet in de hostnaam is opgenomen.<br/>• Het domein zelf identificeert de locale, dus er wordt geen `/zh/` voorvoegsel toegevoegd.<br/>• `getLocalizedUrl('/', 'zh')` retourneert `https://intlayer.zh/`.                                                                                                                     |
 
 **Voorbeeld `rewrite`**:
 

package/docs/nl/intlayer_with_angular_21.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-04-18
 updatedAt: 2026-05-31
-title: "Angular 21 i18n - Volledige gids voor het vertalen van uw app"
-description: "Geen i18next meer. De 2026-gids voor het bouwen van een meertalige (i18n) Angular 21-app. Vertaal met AI-agenten en optimaliseer bundelgrootte, SEO en prestaties."
+title: "Angular 22 i18n - Volledige gids voor het vertalen van uw app"
+description: "Geen i18next meer. De 2026-gids voor het bouwen van een meertalige (i18n) Angular 22-app. Vertaal met AI-agenten en optimaliseer bundelgrootte, SEO en prestaties."
 keywords:
   - Internationalisatie
   - Documentatie
@@ -13,8 +13,8 @@ slugs:
   - doc
   - environment
   - angular
-applicationTemplate: https://github.com/aymericzip/intlayer-angular-21-template
-applicationShowcase: https://intlayer-angular-21-template.vercel.app/
+applicationTemplate: https://github.com/aymericzip/intlayer-angular-22-template
+applicationShowcase: https://intlayer-angular-22-template.vercel.app/
 history:
   - version: 8.9.0
     date: 2026-05-04
@@ -31,7 +31,7 @@ history:
 author: aymericzip
 ---
 
-# Vertaal uw Angular 21 (Vite) website met Intlayer | Internationalisatie (i18n)
+# Vertaal uw Angular 22 (Vite) website met Intlayer | Internationalisatie (i18n)
 
 ## Inhoudsopgave
 
@@ -56,7 +56,7 @@ Met Intlayer kunt u:
   <Tab label="Code" value="code">
 
 <iframe
-  src="https://ide.intlayer.org/aymericzip/intlayer-angular-21-template?file=intlayer.config.ts"
+  src="https://ide.intlayer.org/aymericzip/intlayer-angular-22-template?file=intlayer.config.ts"
   className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
   title="Demo CodeSandbox - Hoe u uw applicatie kunt internationaliseren met Intlayer"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
@@ -67,7 +67,7 @@ Met Intlayer kunt u:
   <Tab label="Demo" value="demo">
 
 <iframe
-  src="https://intlayer-angular-21-template.vercel.app/"
+  src="https://intlayer-angular-22-template.vercel.app/"
   className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
   title="Demo - intlayer-angular-template"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
@@ -77,7 +77,7 @@ Met Intlayer kunt u:
   </Tab>
 </Tabs>
 
-Zie de [Applicatiesjabloon](https://github.com/aymericzip/intlayer-angular-21-template) op GitHub.
+Zie de [Applicatiesjabloon](https://github.com/aymericzip/intlayer-angular-22-template) op GitHub.
 
 <Steps>
 
@@ -165,7 +165,7 @@ export default config;
 
 <Step number={3} title="Intlayer integreren in uw Angular-configuratie">
 
-Om Intlayer met de Angular CLI te integreren, moet u een aangepaste builder gebruiken. Deze handleiding gaat ervan uit dat u Vite/esbuild gebruikt (standaard voor Angular 21-projecten).
+Om Intlayer met de Angular CLI te integreren, moet u een aangepaste builder gebruiken. Deze handleiding gaat ervan uit dat u Vite/esbuild gebruikt (standaard voor Angular 22-projecten).
 
 Pas eerst uw `angular.json` aan om de aangepaste esbuild-builder te gebruiken. Werk de `build`- en `serve`-configuraties bij:
 

package/docs/pl/analytics.md

@@ -0,0 +1,220 @@
+---
+createdAt: 2026-07-08
+updatedAt: 2026-07-08
+title: Intlayer Analytics | Śledzenie ekspozycji treści i testy A/B
+description: Dowiedz się, w jaki sposób @intlayer/analytics śledzi wyświetlenia stron/języków i ekspozycję treści oraz jak z niego korzystać do przeprowadzania testów A/B zawartości Intlayer.
+keywords:
+  - Analytics (Analityka)
+  - Testy A/B
+  - Odbiorcy (Audience)
+  - Internacjonalizacja
+  - Dokumentacja
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - analytics
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Init doc — pakiet @intlayer/analytics, śledzenie na poziomie dostawcy (provider)/węzła (node), testy A/B, dashboard"
+author: aymericzip
+---
+
+# Dokumentacja Intlayer Analytics
+
+`@intlayer/analytics` to opcjonalny pakiet dodatkowy, który podpowiada ci **jakie treści są faktycznie wyświetlane** twoim odwiedzającym — jaka strona, w jakiej lokalizacji (języku) oraz jaki konkretny fragment przetłumaczonej treści — co pozwala ci lepiej zrozumieć odbiorców i przeprowadzać **testy A/B zawartości**.
+
+## Spis treści
+
+<TOC/>
+
+---
+
+## Co jest śledzone
+
+`@intlayer/analytics` gromadzi i wysyła (batch) trzy rodzaje anonimowych zdarzeń:
+
+| Zdarzenie          | Gdzie przechwytywane                             | Co mówi                                                                                                                                    |
+| ------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `page_view`        | Na poziomie Providera (`IntlayerProvider`)       | Jaką stronę i lokalizację (locale) przeglądała sesja podczas pierwszego ładowania, zmiany trasy lub zmiany lokalizacji.                    |
+| `content_exposure` | Na poziomie Węzła (`useIntlayer` / interpretery) | Jaki klucz słownika / ścieżka klucza został faktycznie rozwiązany i wyświetlony — oraz, jeśli jest częścią eksperymentu, jaki **wariant**. |
+| `conversion`       | Gdziekolwiek wywołasz `useConversion()`          | Cel osiągnięty (rejestracja, kliknięcie, zakup...) przypisany do wariantu A/B, na który została wystawiona sesja.                          |
+
+Zdarzenia są zbierane w pamięci i wysyłane jako **jedno żądanie wsadowe (batch request) w przybliżeniu co 20 sekund** — nigdy po każdym wciśnięciu klawisza czy renderowaniu — więc analityka nigdy nie wpływa na czas pierwszego wyrenderowania ani nie dodaje żądań dla każdej interakcji.
+
+## Jak napędza to testy A/B treści
+
+Intlayer pozwala ci już deklarować [Warianty (Variants)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/index.md) zawartości (np. słownik `hero-banner` z wariantem `control` i `black_friday`). `@intlayer/analytics` zamyka pętlę:
+
+1. `getVariant(experimentKey, variants)` deterministycznie przypisuje każdą anonimową sesję do danego wariantu — czysta funkcja bazująca na identyfikatorze sesji i kluczu eksperymentu, więc przypisanie jest **stabilne przez całą sesję** i nie wymaga **okrężnego zapytania do serwera (server round-trip)** przed pierwszym wyrenderowaniem (brak migotania, brak przesunięć układu/layout shift).
+2. Każde zdarzenie `content_exposure` przenosi `variant`, który został pokazany.
+3. `useConversion()` pozwala na przypisanie celu (np. `"cta_click"`) do tego wariantu.
+4. Punkt końcowy (endpoint) z wynikami eksperymentu na dashboardzie porównuje współczynniki konwersji (conversion rates) wariantów, wliczając w to istotność statystyczną (test-z).
+
+## Instalacja
+
+`@intlayer/analytics` jest zależnością typu **peer, opcjonalną** — nigdy nie jest instalowana automatycznie przez żaden pakiet frameworku. Dodaj ją obok `intlayer`:
+
+```bash packageManager="npm"
+npm install @intlayer/analytics
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/analytics
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/analytics
+```
+
+```bash packageManager="bun"
+bun add @intlayer/analytics
+```
+
+Jeśli nie ją zainstalujesz, każdy punkt integracyjny sprowadza się do pustej operacji (no-op) — zobacz [Zerowy koszt, gdy nie zainstalowano](#zerowy-koszt-gdy-nie-zainstalowano) poniżej.
+
+## Konfiguracja
+
+Analytics **wykorzystuje ponownie istniejący blok konfiguracji `editor`** — nie ma osobnego schematu konfiguracyjnego `analytics` do uzupełnienia:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    backendURL: "https://back.intlayer.org", // Wykorzystywane również jako punkt końcowy przyswajania analityki
+    clientId: "your-client-id", // Wykorzystywane również jako klucz projektu analityki
+    clientSecret: "your-client-secret",
+  },
+};
+
+export default config;
+```
+
+- `editor.backendURL` — podstawowy URL, do którego przesyłane są zdarzenia analityki (`POST {backendURL}/api/analytics/events`).
+- `editor.clientId` — publiczny klucz projektu przypisany do każdego przetworzonego zdarzenia. Służy również jako **przełącznik aktywacji**: analityka pozostaje całkowicie wyłączona (oraz usunięta podczas tree-shakingu, patrz niżej), dopóki `clientId` nie zostanie skonfigurowany.
+
+Jeśli hostujesz sam Intlayer (self-host), analityka automatycznie wskazuje na twoją własną instancję, jako że współdzieli parametr `editor.backendURL`.
+
+## Wsparcie dla Frameworków
+
+Analytics jest wpięty w udostępniony `IntlayerProvider` z `react-intlayer`, stąd jest dostępny już dziś w każdym miejscu, w którym ten provider jest używany:
+
+| Framework                                                | Status                                                                                               |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| React                                                    | ✅ Dostępne                                                                                          |
+| Next.js (`next-intlayer`)                                | ✅ Dostępne (poprzez `react-intlayer`)                                                               |
+| React Native / Expo (`react-native-intlayer`)            | ✅ Dostępne (poprzez `react-intlayer`)                                                               |
+| Vue, Svelte, Angular, Solid, Preact, Lit, Astro, Vanilla | 🚧 Zaplanowano — ten sam klient, podpięcia na poziomie providera wzorujące się na `@intlayer/editor` |
+
+## Użycie
+
+### Automatyczne śledzenie na poziomie providera
+
+Brak konieczności modyfikowania kodu. Po zainstalowaniu pakietu `@intlayer/analytics` oraz po skonfigurowaniu `editor.clientId`, `IntlayerProvider` będzie automatycznie:
+
+- inicjalizować klienta analityki po zamontowaniu (mount),
+- rejestrować `page_view` po pierwszym załadowaniu,
+- rejestrować `page_view` za każdą zmianą lokalizacji,
+- uruchamiać cykl „wypychania” (flush) zdarzeń po około 20 sekundach oraz natychmiast, gdy zakładka zostanie zamknięta (za pośrednictwem `navigator.sendBeacon`, z trybem zapasowym (fallback) do `fetch(..., { keepalive: true })`).
+
+### Automatyczne śledzenie na poziomie węzła
+
+Za każdym razem, gdy `useIntlayer` rozwiąże jakiś fragment treści do wyświetlenia, interpreter raportuje zdarzenie typu `content_exposure` dla odpowiedniego elementu tj. zbiór `dictionaryKey` + lokalizacja (locale) + precyzyjna ścieżka klucza (key path) — ponownie, nie ma potrzeby zmieniania kodu. Powielone zdarzenia tego samego węzła pojawiające się w cyklu wypychania zostają zgrupowane do 1 zapytania razem z właściwością `count` — dzięki czemu lista z renderowaniem wykonywanym po 50 razy nie wypycha 50 razy osobnego zapytania.
+
+### Śledzenie konwersji do testów A/B
+
+Wykorzystaj `useConversion()`, aby przypisać cel do wariantu, z którym wchodzono w interakcję w czasie sesji:
+
+```tsx fileName="CTAButton.tsx" codeFormat="tsx"
+import { useConversion } from "react-intlayer";
+
+const CTAButton = () => {
+  const trackConversion = useConversion();
+
+  return (
+    <button
+      onClick={() =>
+        trackConversion({
+          experimentKey: "homepage-hero",
+          variant: "black_friday",
+          goal: "cta_click",
+        })
+      }
+    >
+      Rozpocznij
+    </button>
+  );
+};
+```
+
+### Odbieranie wariantu bezpośrednio po stronie klienta
+
+```tsx fileName="useHeroVariant.ts" codeFormat="tsx"
+import { getGlobalAnalyticsClient } from "@intlayer/analytics/client";
+
+const client = getGlobalAnalyticsClient();
+const variant = client?.getVariant("homepage-hero", [
+  "control",
+  "black_friday",
+]);
+```
+
+## Prywatność & Wydajność
+
+- **Z założenia anonimowe (Anonymous by design)**: sesje definiowane są losowymi unikalnymi indentyfikatorami (rotating ids), i backend nie przetwarza danych tak mocno, by przetrzymywać oryginał i nigdy IP urządzenia; pozostawia jedynie odcienie, zjawisko **SHA-256 hash**.
+- **Dokładność pozycjonowania ogólna (coarse)**: pozostaje do dyspozycji jedynie unikalny fragment kraju.
+- **Odnośniki odrzucają query string (search params)** z definicji.
+- **Losowanie pul (Sampling)**: opcja `sampleRate` umożliwia selekcjonowanie wyświetlanej treści.
+- **Zbiorcze transakcje (Batched)**: 1 transakcja średnio na 20 sec (`flushInterval`), w skrajnych momentach częściej, np. by wyzerować zapętlające procesy, jeżeli dojdzie do uzupełniania bufru (`maxBufferSize`).
+
+### Zerowy koszt, gdy nie zainstalowano
+
+`@intlayer/analytics` podąża za tym samym modelem zależności opcjonalnej co `@intlayer/editor`:
+
+- Zawsze paczka dociągana jest dynamicznie w osłonie **`import()` z klauzulą `try/catch`**.
+- Stała wartość dla buildowania (`INTLAYER_ANALYTICS_ENABLED`) redukuje procesowanie w kodzie zjawiskiem **dead-code-eliminate** do momentu skonfigurowania i deklaracji `editor.clientId`.
+
+## Dashboard: Strona Analityki
+
+Jak tylko system zdobędzie niezbędne detale na start z Twojego portalu (podpiętego pod projekt), sekcja **Analytics** (pod panelem) ukaże widok:
+
+- Ilość użytkowników „Aktywnych”.
+- Sumę w danym przedziale do ok 7 dni.
+- Widok wyświetleń z perspektywy danej grupy stron (Page views).
+- Pełen zakres podziału z punktu widzenia specyficznych preferencji odwiedzającego – w oparciu o sekcje państw z dodatkiem preferowanych ustawień językowych na zakładce podziału.
+
+## Odniesienie Backend API
+
+Każde odniesienie czytające poddawane jest procesom weryfikacyjnym. System pobierający wystawiony jest na świat by funkcjonować prawidłowo z argumentem body `clientId`.
+
+| Metoda | Endpoint                                    | Opis                                                                                |
+| ------ | ------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `POST` | `/api/analytics/events`                     | Masowe pobieranie eventów z puli publicznej odfiltrowane wg. kryteriów `clientId`.  |
+| `GET`  | `/api/analytics/overview`                   | Parametry odsłon na język i podstrony do autoryzowanego projektu.                   |
+| `GET`  | `/api/analytics/audience?days=30`           | Grupy wizytorów i szczegóły wyświetlania w ujęciu wielowymiarowym (dzień,język,itd) |
+| `GET`  | `/api/analytics/content-stats`              | Odsłony w grupie precyzyjnie celowanej ścieżki i pod klucz w słowniku.              |
+| `GET`  | `/api/analytics/experiments/:experimentKey` | Konwersja by przeprowadzać na wariantach testy (A/B testing, statistical itp.)      |
+
+Korzystając z dostępu masz uprawnienia do podpięcia własnych wywoływań ze skryptami wspierając system SDK: [CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_CMS.md):
+
+```ts fileName="analytics.ts"
+import { createIntlayerCMS } from "@intlayer/api";
+import { analyticsEndpoint } from "@intlayer/api/analytics";
+
+const cms = createIntlayerCMS();
+
+const { data: audience } = await analyticsEndpoint(cms).getAudience(30);
+```
+
+## Przydatne linki
+
+- [Słowniki dynamiczne – Kolekcje & Warianty (Dynamic Dictionaries)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/dynamic_dictionaries/index.md)
+- [Intlayer CMS - CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_CMS.md)
+- [Intlayer Visual Editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/intlayer_visual_editor.md)
+- [Odwołanie konfiguracyjne (Configuration Reference)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/configuration.md)
+- [Poradnik hostingu samodzielnego (Self-Hosting Guide)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pl/self_hosting.md)

package/docs/pl/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-07-11
+updatedAt: 2026-08-06
 title: Konfiguracja
 description: Dowiedz się, jak skonfigurować Intlayer dla swojej aplikacji. Zrozum różne ustawienia i opcje dostępne do dostosowania Intlayer do Twoich potrzeb.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.1.3
+    date: 2026-08-06
+    changes: "Uczynienie `routing.enableProxy` trójstanowym: nieustawione (auto), `true`, `false`"
   - version: 9.0.0
     date: 2026-07-11
     changes: "Dodano konfigurację `analytics`"
@@ -235,6 +238,19 @@ const config: IntlayerConfig = {
      */
     mode: "prefix-no-default",
 
+    /**
+     * Włącza proxy routingu lokalizacji Intlayer (middleware).
+     * Obsługuje wykrywanie lokalizacji, przekierowania i przepisywanie w dev, preview i SSR.
+     * - nieustawione (auto): serwery dev i preview utrzymują routing sterowany adresem URL,
+     *   ignorując lokalizację zapisaną w ciasteczkach i nagłówkach. Prefiksy nadal są
+     *   rozwiązywane, lokalizacja nadal jest zapisywana, a wykrywanie Accept-Language
+     *   nadal działa. W produkcji zachowuje się jak `true`.
+     * - true: pełne zachowanie w każdym środowisku.
+     * - false: brak routingu lokalizacji.
+     * Domyślnie: undefined (auto)
+     */
+    enableProxy: undefined,
+
     /**
      * Miejsce przechowywania locale wybranego przez użytkownika.
      * Opcje: 'cookie', 'localStorage', 'sessionStorage', 'header' lub ich tablica.
@@ -713,13 +729,14 @@ Analityka jest ściśle opt-in: nic nie jest zbierane, dopóki `analytics.enable
 
 Ustawienia kontrolujące zachowanie routingu, w tym strukturę URL, przechowywanie locale i obsługę middleware.
 
-| Pole       | Opis                                                                                                                                                                                                           | Typ                                                                                                                                                                                                          | Domyślnie              | Przykład                                                                                                                                                                                | Uwagi                                                                                                                                                                                                                                                                              |
-| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mode`     | Tryb struktury URL do zarządzania locale.                                                                                                                                                                      | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) lub `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: locale zarządzane inaczej. `'search-params'`: `/dashboard?locale=fr` | Nie wpływa na zarządzanie plikami cookie ani pamięcią lokalną.                                                                                                                                                                                                                     |
-| `storage`  | Konfiguracja przechowywania locale u klienta.                                                                                                                                                                  | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                      | Zobacz tabelę opcji przechowywania poniżej.                                                                                                                                                                                                                                        |
-| `basePath` | Bazowa ścieżka dla adresów URL aplikacji.                                                                                                                                                                      | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                             | Jeśli Twoja aplikacja znajduje się pod adresem `https://example.com/my-app`, basePath to `'/my-app'`, co wskazuje na URL `https://example.com/my-app/en`.                                                                                                                          |
-| `rewrite`  | Własne reguły przepisywania URL w celu zmiany domyślnego trybu routingu dla określonych ścieżek. Obsługuje parametry dynamiczne `[param]`.                                                                     | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | Zobacz przykład poniżej                                                                                                                                                                 | • Reguły routingu mają wyższy priorytet niż `mode`.<br/>• Działa z Next.js i Vite.<br/>• `getLocalizedUrl()` automatycznie stosuje pasujące reguły.<br/>• Zobacz [Własne przepisywanie URL](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md). |
-| `domains`  | Mapuje locale na nazwy hostów domen dla routingu opartego na domenach. Gdy ustawione, adresy URL dla danego locale używają tej domeny jako bazy (absolutny URL) i do ścieżki nie jest dodawany prefiks locale. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                             | • Domyślnym protokołem jest `https://`, gdy nie jest zawarty w nazwie hosta.<br/>• Sama domena identyfikuje locale, więc prefiks `/zh/` nie jest dodawany.<br/>• `getLocalizedUrl('/', 'zh')` zwraca `https://intlayer.zh/`.                                                       |
+| Pole          | Opis                                                                                                                                                                                                           | Typ                                                                                                                                                                                                          | Domyślnie              | Przykład                                                                                                                                                                                | Uwagi                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`        | Tryb struktury URL do zarządzania locale.                                                                                                                                                                      | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) lub `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: locale zarządzane inaczej. `'search-params'`: `/dashboard?locale=fr` | Nie wpływa na zarządzanie plikami cookie ani pamięcią lokalną.                                                                                                                                                                                                                                                                                                                               |
+| `enableProxy` | Włącza proxy routingu lokalizacji Intlayer (middleware).                                                                                                                                                       | `boolean` &#124; <br/> `undefined`                                                                                                                                                                           | `undefined` (auto)     | `true`                                                                                                                                                                                  | • Nieustawione (auto): serwery dev i preview ignorują lokalizację zapisaną w ciasteczkach/nagłówkach jako źródło przekierowania; prefiksy, zapisywanie i wykrywanie `Accept-Language` nadal działają. W produkcji zachowuje się jak `true`.<br/>• `true`: pełne zachowanie wszędzie.<br/>• `false`: brak routingu lokalizacji. W Next.js middleware `intlayerProxy` staje się przezroczysty. |
+| `storage`     | Konfiguracja przechowywania locale u klienta.                                                                                                                                                                  | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                      | Zobacz tabelę opcji przechowywania poniżej.                                                                                                                                                                                                                                                                                                                                                  |
+| `basePath`    | Bazowa ścieżka dla adresów URL aplikacji.                                                                                                                                                                      | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                             | Jeśli Twoja aplikacja znajduje się pod adresem `https://example.com/my-app`, basePath to `'/my-app'`, co wskazuje na URL `https://example.com/my-app/en`.                                                                                                                                                                                                                                    |
+| `rewrite`     | Własne reguły przepisywania URL w celu zmiany domyślnego trybu routingu dla określonych ścieżek. Obsługuje parametry dynamiczne `[param]`.                                                                     | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | Zobacz przykład poniżej                                                                                                                                                                 | • Reguły routingu mają wyższy priorytet niż `mode`.<br/>• Działa z Next.js i Vite.<br/>• `getLocalizedUrl()` automatycznie stosuje pasujące reguły.<br/>• Zobacz [Własne przepisywanie URL](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md).                                                                                                           |
+| `domains`     | Mapuje locale na nazwy hostów domen dla routingu opartego na domenach. Gdy ustawione, adresy URL dla danego locale używają tej domeny jako bazy (absolutny URL) i do ścieżki nie jest dodawany prefiks locale. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                             | • Domyślnym protokołem jest `https://`, gdy nie jest zawarty w nazwie hosta.<br/>• Sama domena identyfikuje locale, więc prefiks `/zh/` nie jest dodawany.<br/>• `getLocalizedUrl('/', 'zh')` zwraca `https://intlayer.zh/`.                                                                                                                                                                 |
 
 **Przykład `rewrite`**: