@intlayer/docs 9.1.3 → 9.3.0

package/docs/ur/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-07-11
+updatedAt: 2026-08-06
 title: ترتیب (Configuration)
 description: سیکھیں کہ اپنی ایپلیکیشن کے لیے Intlayer کو کیسے ترتیب دینا ہے۔ اپنی ضروریات کے مطابق Intlayer کو اپنی مرضی کے مطابق بنانے کے لیے دستیاب مختلف ترتیبات اور اختیارات کو سمجھیں۔
 keywords:
@@ -16,6 +16,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.1.3
+    date: 2026-08-06
+    changes: "`routing.enableProxy` کو تین حالتوں والا بنایا گیا: غیر مقرر (auto)، `true`، `false`"
   - version: 9.0.0
     date: 2026-07-11
     changes: "`analytics` کنفیگریشن شامل کی گئی"
@@ -237,6 +240,19 @@ const config: IntlayerConfig = {
      */
     mode: "prefix-no-default",
 
+    /**
+     * Intlayer لوکیل-روٹنگ پراکسی (مڈل ویئر) کو فعال کرتا ہے۔
+     * dev، preview اور SSR میں لوکیل کی شناخت، ری ڈائریکٹ اور ری رائٹ سنبھالتا ہے۔
+     * - غیر مقرر (auto): dev اور preview سرورز کوکیز اور ہیڈرز میں محفوظ لوکیل کو
+     *   نظر انداز کرتے ہوئے روٹنگ کو URL پر مبنی رکھتے ہیں۔ پریفکس اب بھی حل ہوتے ہیں،
+     *   لوکیل اب بھی محفوظ ہوتا ہے، اور Accept-Language کی شناخت اب بھی لاگو ہوتی ہے۔
+     *   پروڈکشن میں یہ `true` کی طرح برتاؤ کرتا ہے۔
+     * - true: ہر ماحول میں مکمل برتاؤ۔
+     * - false: کوئی لوکیل روٹنگ نہیں۔
+     * ڈیفالٹ: undefined (auto)
+     */
+    enableProxy: undefined,
+
     /**
      * صارف کے منتخب کردہ لوکل کو کہاں محفوظ کرنا ہے۔
      * اختیارات: 'cookie', 'localStorage', 'sessionStorage', 'header'، یا ان کا مجموعہ۔
@@ -715,13 +731,14 @@ Intlayer اینالیٹکس سے متعلق ترتیبات کی وضاحت کر
 
 ترتیبات جو راؤٹنگ کے رویے کو کنٹرول کرتی ہیں، بشمول URL کا ڈھانچہ، لوکل اسٹوریج، اور مڈل ویئر ہینڈلنگ۔
 
-| فیلڈ       | وضاحت                                                                                                                                                                                                            | قسم                                                                                                                                                                                                          | ڈیفالٹ                 | مثال                                                                                                                                                                                               | نوٹ                                                                                                                                                                                                                                                                            |
-| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `mode`     | لوکل ہینڈلنگ کے لیے URL راؤٹنگ موڈ۔                                                                                                                                                                              | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) یا `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: لوکل دوسرے ذرائع سے ہینڈل کیا جاتا ہے۔ `'search-params'`: `/dashboard?locale=fr` | کوکی یا لوکل اسٹوریج مینجمنٹ پر اثر انداز نہیں ہوتا۔                                                                                                                                                                                                                           |
-| `storage`  | کلائنٹ میں لوکل محفوظ کرنے کی کنفیگریشن۔                                                                                                                                                                         | `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 }]`                                                                                                                 | نیچے اسٹوریج کے اختیارات والا ٹیبل دیکھیں۔                                                                                                                                                                                                                                     |
-| `basePath` | ایپلیکیشن URLs کے لیے بنیادی راستہ۔                                                                                                                                                                              | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                                        | اگر ایپ `https://example.com/my-app` پر ہے، تو basePath `'/my-app'` ہے اور URLs `https://example.com/my-app/en` بن جاتے ہیں۔                                                                                                                                                   |
-| `rewrite`  | کسٹم URL رائٹنگ کے قواعد جو مخصوص راستوں کے لیے ڈیفالٹ راؤٹنگ موڈ کو اوور رائڈ کرتے ہیں۔ `[param]` متحرک پیرامیٹرز کی سپورٹ۔                                                                                     | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | نیچے دی گئی مثال دیکھیں                                                                                                                                                                            | • ری رائٹ رولز `mode` پر فوقیت رکھتے ہیں۔<br/>• Next.js اور Vite کے ساتھ کام کرتا ہے۔<br/>• `getLocalizedUrl()` خودکار طور پر مماثل رولز لاگو کرتا ہے۔<br/>• [کسٹم URL ری رائٹس](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md) دیکھیں۔ |
-| `domains`  | ڈومین پر مبنی راؤٹنگ کے لیے لوکلز کو ڈومین ہوسٹ نیمز کے ساتھ میپ کرتا ہے۔ جب سیٹ کیا جائے تو اس لوکل کے URLs اس ڈومین کو بطور بنیاد (مطلق URL) استعمال کرتے ہیں اور پاتھ میں کوئی لوکل سابقہ شامل نہیں کیا جاتا۔ | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                                        | • اگر ہوسٹ نیم میں شامل نہ ہو تو ڈیفالٹ پروٹوکول `https://` ہے۔<br/>• ڈومین خود لوکل کی شناخت کرتا ہے، اس لیے کوئی `/zh/` سابقہ شامل نہیں کیا جاتا۔<br/>• `getLocalizedUrl('/', 'zh')` واپسی دیتا ہے `https://intlayer.zh/`۔                                                   |
+| فیلڈ          | وضاحت                                                                                                                                                                                                            | قسم                                                                                                                                                                                                          | ڈیفالٹ                 | مثال                                                                                                                                                                                               | نوٹ                                                                                                                                                                                                                                                                                                                                                         |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`        | لوکل ہینڈلنگ کے لیے URL راؤٹنگ موڈ۔                                                                                                                                                                              | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) یا `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: لوکل دوسرے ذرائع سے ہینڈل کیا جاتا ہے۔ `'search-params'`: `/dashboard?locale=fr` | کوکی یا لوکل اسٹوریج مینجمنٹ پر اثر انداز نہیں ہوتا۔                                                                                                                                                                                                                                                                                                        |
+| `enableProxy` | Intlayer لوکیل-روٹنگ پراکسی (مڈل ویئر) کو فعال کرتا ہے۔                                                                                                                                                          | `boolean` &#124; <br/> `undefined`                                                                                                                                                                           | `undefined` (auto)     | `true`                                                                                                                                                                                             | • غیر مقرر (auto): dev اور preview سرورز کوکیز/ہیڈرز میں محفوظ لوکیل کو ری ڈائریکٹ کے ماخذ کے طور پر نظر انداز کرتے ہیں؛ پریفکس، محفوظ کرنا اور `Accept-Language` کی شناخت اب بھی لاگو ہوتی ہے۔ پروڈکشن میں `true` کی طرح۔<br/>• `true`: ہر جگہ مکمل برتاؤ۔<br/>• `false`: کوئی لوکیل روٹنگ نہیں۔ Next.js میں `intlayerProxy` مڈل ویئر پاس-تھرو بن جاتا ہے۔ |
+| `storage`     | کلائنٹ میں لوکل محفوظ کرنے کی کنفیگریشن۔                                                                                                                                                                         | `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 }]`                                                                                                                 | نیچے اسٹوریج کے اختیارات والا ٹیبل دیکھیں۔                                                                                                                                                                                                                                                                                                                  |
+| `basePath`    | ایپلیکیشن URLs کے لیے بنیادی راستہ۔                                                                                                                                                                              | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                                        | اگر ایپ `https://example.com/my-app` پر ہے، تو basePath `'/my-app'` ہے اور URLs `https://example.com/my-app/en` بن جاتے ہیں۔                                                                                                                                                                                                                                |
+| `rewrite`     | کسٹم URL رائٹنگ کے قواعد جو مخصوص راستوں کے لیے ڈیفالٹ راؤٹنگ موڈ کو اوور رائڈ کرتے ہیں۔ `[param]` متحرک پیرامیٹرز کی سپورٹ۔                                                                                     | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | نیچے دی گئی مثال دیکھیں                                                                                                                                                                            | • ری رائٹ رولز `mode` پر فوقیت رکھتے ہیں۔<br/>• Next.js اور Vite کے ساتھ کام کرتا ہے۔<br/>• `getLocalizedUrl()` خودکار طور پر مماثل رولز لاگو کرتا ہے۔<br/>• [کسٹم URL ری رائٹس](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/custom_url_rewrites.md) دیکھیں۔                                                                              |
+| `domains`     | ڈومین پر مبنی راؤٹنگ کے لیے لوکلز کو ڈومین ہوسٹ نیمز کے ساتھ میپ کرتا ہے۔ جب سیٹ کیا جائے تو اس لوکل کے URLs اس ڈومین کو بطور بنیاد (مطلق URL) استعمال کرتے ہیں اور پاتھ میں کوئی لوکل سابقہ شامل نہیں کیا جاتا۔ | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                                        | • اگر ہوسٹ نیم میں شامل نہ ہو تو ڈیفالٹ پروٹوکول `https://` ہے۔<br/>• ڈومین خود لوکل کی شناخت کرتا ہے، اس لیے کوئی `/zh/` سابقہ شامل نہیں کیا جاتا۔<br/>• `getLocalizedUrl('/', 'zh')` واپسی دیتا ہے `https://intlayer.zh/`۔                                                                                                                                |
 
 **`rewrite` کی مثال**:
 

package/docs/ur/intlayer_with_angular_21.md

@@ -1,8 +1,8 @@
 ---
 createdAt: 2025-04-18
 updatedAt: 2026-05-31
-title: "Angular 21 i18n - اپنی ایپ کو ترجمہ کرنے کا مکمل گائیڈ"
-description: "اب i18next کی ضرورت نہیں۔ 2026 میں Angular 21 ایپ کو کثیر لسانی (i18n) بنانے کا گائیڈ۔ AI ایجنٹس سے ترجمہ کریں اور بنڈل سائز، SEO اور پرفارمنس بہتر بنائیں۔"
+title: "Angular 22 i18n - اپنی ایپ کو ترجمہ کرنے کا مکمل گائیڈ"
+description: "اب i18next کی ضرورت نہیں۔ 2026 میں Angular 22 ایپ کو کثیر لسانی (i18n) بنانے کا گائیڈ۔ AI ایجنٹس سے ترجمہ کریں اور بنڈل سائز، SEO اور پرفارمنس بہتر بنائیں۔"
 keywords:
   - بین الاقوامی بنانا
   - دستاویزات
@@ -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
 ---
 
-# Intlayer کا استعمال کرتے ہوئے اپنی Angular 21 (Vite) ویب سائٹ کا ترجمہ کریں | بین الاقوامی بنانا (i18n)
+# Intlayer کا استعمال کرتے ہوئے اپنی Angular 22 (Vite) ویب سائٹ کا ترجمہ کریں | بین الاقوامی بنانا (i18n)
 
 ## فہرست
 
@@ -56,7 +56,7 @@ Intlayer کے ساتھ، آپ کر سکتے ہیں:
   <Tab label="کوڈ" 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 - Intlayer کا استعمال کرتے ہوئے اپنی ایپلی کیشن کو کیسے بین الاقوامی بنائیں"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
@@ -67,7 +67,7 @@ Intlayer کے ساتھ، آپ کر سکتے ہیں:
   <Tab label="ڈیمو" 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 @@ Intlayer کے ساتھ، آپ کر سکتے ہیں:
   </Tab>
 </Tabs>
 
-GitHub پر [ایپلیکیشن ٹیمپلیٹ](https://github.com/aymericzip/intlayer-angular-21-template) دیکھیں۔
+GitHub پر [ایپلیکیشن ٹیمپلیٹ](https://github.com/aymericzip/intlayer-angular-22-template) دیکھیں۔
 
 <Steps>
 
@@ -165,7 +165,7 @@ export default config;
 
 <Step number={3} title="اپنی Angular کنفیگریشن میں Intlayer کو شامل کریں">
 
-Intlayer کو Angular CLI کے ساتھ مربوط کرنے کے لیے، آپ کو ایک کسٹم بلڈر استعمال کرنے کی ضرورت ہے۔ یہ گائیڈ فرض کرتی ہے کہ آپ Vite/esbuild (Angular 21 پروجیکٹس کے لیے ڈیفالٹ) استعمال کر رہے ہیں۔
+Intlayer کو Angular CLI کے ساتھ مربوط کرنے کے لیے، آپ کو ایک کسٹم بلڈر استعمال کرنے کی ضرورت ہے۔ یہ گائیڈ فرض کرتی ہے کہ آپ Vite/esbuild (Angular 22 پروجیکٹس کے لیے ڈیفالٹ) استعمال کر رہے ہیں۔
 
 پہلے، کسٹم esbuild بلڈر استعمال کرنے کے لیے اپنے `angular.json` میں ترمیم کریں۔ `build` اور `serve` کی کنفیگریشن کو اپ ڈیٹ کریں:
 

package/docs/vi/analytics.md

@@ -0,0 +1,222 @@
+---
+createdAt: 2026-07-08
+updatedAt: 2026-07-08
+title: Intlayer Analytics | Theo dõi hiển thị nội dung và chạy thử nghiệm A/B
+description: Khám phá cách @intlayer/analytics theo dõi lượt xem trang/ngôn ngữ và lượt hiển thị nội dung, cũng như cách sử dụng nó để chạy thử nghiệm A/B trên nội dung Intlayer của bạn.
+keywords:
+  - Analytics
+  - A/B Testing
+  - Audience
+  - Internationalization
+  - Documentation
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - analytics
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Init doc — gói @intlayer/analytics, theo dõi ở cấp độ provider/node, thử nghiệm A/B, dashboard"
+author: aymericzip
+---
+
+# Tài liệu Intlayer Analytics
+
+`@intlayer/analytics` là một gói đồng hành tùy chọn cho bạn biết **chính xác nội dung nào được hiển thị** cho khách truy cập của bạn — trang nào, bằng ngôn ngữ (locale) nào và đoạn nội dung được dịch cụ thể nào — để bạn có thể hiểu rõ khán giả của mình và chạy **thử nghiệm A/B trên nội dung**.
+
+## Mục lục
+
+<TOC/>
+
+---
+
+## Những gì nó theo dõi
+
+`@intlayer/analytics` gom nhóm ba loại sự kiện ẩn danh thành các batch:
+
+| Sự kiện            | Bắt ở đâu                                            | Cho bạn biết điều gì                                                                                                                                              |
+| ------------------ | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `page_view`        | Cấp độ Provider (`IntlayerProvider`)                 | Trang và ngôn ngữ nào mà một phiên (session) đã xem, khi tải lần đầu, khi chuyển hướng (route change) hoặc chuyển ngôn ngữ.                                       |
+| `content_exposure` | Cấp độ Node (`useIntlayer` / plugin trình biên dịch) | Khóa từ điển (dictionary key) / đường dẫn khóa nào thực sự được giải quyết và hiển thị — và nếu là một phần của thử nghiệm, thì đó là **biến thể (variant)** nào. |
+| `conversion`       | Bất cứ nơi nào bạn gọi `useConversion()`             | Một mục tiêu đạt được (đăng ký, nhấp chuột, mua hàng...) được quy cho (attributed) biến thể A/B mà phiên đó đã tiếp xúc.                                          |
+
+Các sự kiện được thu thập trong bộ nhớ và được gửi dưới dạng một **yêu cầu batch duy nhất khoảng 20 giây một lần** — không bao giờ gửi trên mỗi lần gõ phím hoặc mỗi lần render — do đó, analytics không bao giờ ảnh hưởng đến thời gian render đầu tiên hoặc thêm một yêu cầu cho mỗi tương tác.
+
+## Cách nó hỗ trợ thử nghiệm A/B trên nội dung
+
+Intlayer đã cho phép bạn khai báo [Biến thể (Variants)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/index.md) nội dung (ví dụ: từ điển `hero-banner` có biến thể `control` và `black_friday`). `@intlayer/analytics` khép kín quy trình này:
+
+1. `getVariant(experimentKey, variants)` gán một cách tất định mỗi phiên ẩn danh cho một biến thể — đây là một hàm thuần túy (pure function) của session id và khóa thử nghiệm, vì vậy việc gán là **ổn định trong toàn bộ phiên** và **không cần round-trip đến máy chủ** trước lần render đầu tiên (không bị nhấp nháy (flicker), không thay đổi bố cục (layout shift)).
+2. Mỗi sự kiện `content_exposure` mang theo `variant` đã được hiển thị.
+3. `useConversion()` cho phép bạn quy một mục tiêu (ví dụ: `"cta_click"`) cho biến thể đó.
+4. Điểm cuối (endpoint) kết quả thử nghiệm trên dashboard sẽ so sánh tỷ lệ chuyển đổi trên mỗi biến thể, bao gồm cả ý nghĩa thống kê (kiểm định z).
+
+## Cài đặt
+
+`@intlayer/analytics` là một dependency **ngang hàng (peer), tùy chọn** — không bao giờ được tự động cài đặt bởi một gói framework. Hãy thêm nó cùng với `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
+```
+
+Nếu bạn không cài đặt nó, mọi điểm tích hợp (integration point) sẽ được coi là một hành động trống (no-op) — xem phần [Không tốn phí khi không được cài đặt](#khong-ton-phi-khi-khong-duoc-cai-dat) bên dưới.
+
+## Cấu hình
+
+Analytics **sử dụng lại khối cấu hình `editor` hiện có** — không có schema cấu hình `analytics` riêng biệt để điền vào:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    backendURL: "https://back.intlayer.org", // Cũng được sử dụng làm điểm cuối nhận dữ liệu (ingestion endpoint) cho analytics
+    clientId: "your-client-id", // Cũng được sử dụng làm khóa dự án analytics
+    clientSecret: "your-client-secret",
+  },
+};
+
+export default config;
+```
+
+- `editor.backendURL` — URL cơ sở mà các sự kiện analytics được gửi đến (`POST {backendURL}/api/analytics/events`).
+- `editor.clientId` — khóa dự án công khai được gắn vào mọi sự kiện được thu nhận. Nó cũng đóng vai trò là **công tắc bật (enable switch)**: analytics hoàn toàn bị vô hiệu hóa (và được loại bỏ bằng tree-shaking, xem bên dưới) cho đến khi `clientId` được định cấu hình.
+
+Nếu bạn tự lưu trữ (self-host) Intlayer, analytics sẽ tự động trỏ đến phiên bản của riêng bạn vì nó dùng chung `editor.backendURL`.
+
+## Hỗ trợ Framework
+
+Analytics được liên kết với `IntlayerProvider` dùng chung từ `react-intlayer`, vì vậy nó có sẵn ở bất kỳ đâu provider đó được sử dụng:
+
+| Framework                                                | Trạng thái                                                                                            |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| React                                                    | ✅ Có sẵn                                                                                             |
+| Next.js (`next-intlayer`)                                | ✅ Có sẵn (thông qua `react-intlayer`)                                                                |
+| React Native / Expo (`react-native-intlayer`)            | ✅ Có sẵn (thông qua `react-intlayer`)                                                                |
+| Vue, Svelte, Angular, Solid, Preact, Lit, Astro, Vanilla | 🚧 Đã lên kế hoạch — cùng một client, các ràng buộc cấp provider tuân theo mô hình `@intlayer/editor` |
+
+## Cách sử dụng
+
+### Tự động theo dõi ở cấp độ provider
+
+Không cần thay đổi mã nguồn. Khi `@intlayer/analytics` đã được cài đặt và `editor.clientId` được cấu hình, `IntlayerProvider` sẽ tự động:
+
+- khởi tạo analytics client khi mount,
+- ghi lại một `page_view` ở lần tải ban đầu,
+- ghi lại một `page_view` mỗi khi thay đổi ngôn ngữ,
+- bắt đầu vòng lặp flush ~20 giây và flush mọi sự kiện còn lại khi unmount / đóng tab (thông qua `navigator.sendBeacon`, với fallback là `fetch(..., { keepalive: true })`).
+
+### Tự động theo dõi ở cấp độ node
+
+Mỗi khi `useIntlayer` phân giải một phần nội dung để hiển thị, trình thông dịch sẽ báo cáo một sự kiện `content_exposure` cho chính xác `dictionaryKey` + đường dẫn khóa + ngôn ngữ đó — một lần nữa, không cần thay đổi mã. Các lần hiển thị lặp lại của cùng một node trong cùng một cửa sổ flush sẽ được gộp lại thành một sự kiện duy nhất với thuộc tính `count`, vì vậy một danh sách hiển thị lại (re-render) 50 lần sẽ không gửi 50 sự kiện.
+
+### Theo dõi chuyển đổi cho thử nghiệm A/B
+
+Sử dụng `useConversion()` để quy một mục tiêu cho biến thể mà một phiên đã thấy:
+
+```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",
+        })
+      }
+    >
+      Bắt đầu
+    </button>
+  );
+};
+```
+
+### Phân giải biến thể phía client (client-side)
+
+```tsx fileName="useHeroVariant.ts" codeFormat="tsx"
+import { getGlobalAnalyticsClient } from "@intlayer/analytics/client";
+
+const client = getGlobalAnalyticsClient();
+const variant = client?.getVariant("homepage-hero", [
+  "control",
+  "black_friday",
+]);
+```
+
+## Quyền riêng tư & Hiệu suất
+
+- **Ẩn danh theo thiết kế (Anonymous by design)**: các phiên được xác định bằng một id xoay vòng (rotating id); máy chủ (backend) chỉ lưu trữ **mã băm SHA-256** của id đó — không bao giờ lưu trữ id thô và không bao giờ lưu trữ địa chỉ IP.
+- **Vị trí là tương đối**: chỉ có mã quốc gia, bắt nguồn từ các tiêu đề vị trí địa lý của CDN (ví dụ: `cf-ipcountry`, `x-vercel-ip-country`, ...) — không có IP nào được đọc hoặc lưu trữ.
+- **URL loại trừ tham số tìm kiếm (search params)** theo mặc định, do đó các chuỗi truy vấn (query strings) không bao giờ bị thu thập.
+- **Lấy mẫu (Sampling)**: `sampleRate` cho phép bạn chỉ giữ lại một phần nhỏ các sự kiện hiển thị nội dung trên các ứng dụng có lưu lượng truy cập cao.
+- **Xử lý theo batch**: một yêu cầu được gửi sau khoảng 20 giây (`flushInterval`), hoặc sớm hơn nếu bộ đệm bị đầy (`maxBufferSize`) — không bao giờ gửi một yêu cầu cho mỗi sự kiện.
+
+### Không tốn phí khi không được cài đặt
+
+`@intlayer/analytics` tuân theo chính xác cùng một mô hình tùy chọn-dependency như `@intlayer/editor`:
+
+- mọi điểm tích hợp đều tải gói này thông qua việc sử dụng **dynamic `import()` được bao bọc trong khối `try/catch`** — một ứng dụng không bao giờ cài đặt `@intlayer/analytics` sẽ không bao giờ bị tăng kích thước bundle hoặc chi phí thời gian chạy, và không bao giờ thấy lỗi;
+- một biến môi trường ở thời điểm biên dịch (`INTLAYER_ANALYTICS_ENABLED`), được đặt tự động thành `'false'` bởi `@intlayer/config` bất cứ khi nào `editor.clientId` không được định cấu hình, cho phép các bundler có thể **loại bỏ mã thừa (dead-code-eliminate)** toàn bộ tích hợp này;
+- analytics bị vô hiệu hóa bên trong iframe xem trước của trình chỉnh sửa / CMS Intlayer, do đó các phiên của trình chỉnh sửa không bao giờ được tính là lưu lượng truy cập thực.
+
+## Dashboard: Trang Analytics
+
+Sau khi dự án của bạn đã thu thập các sự kiện, trang **Analytics** trong [Intlayer dashboard](https://app.intlayer.org/analytics) (hiển thị ở thanh bên sau khi dự án được chọn) sẽ hiển thị:
+
+- **Người dùng đang hoạt động (Active users)** — số lượng khách truy cập duy nhất trong khoảng thời gian cuộn (rolling window) đã chọn (7 / 30 / 90 ngày).
+- **Người dùng hôm nay** và **người dùng trong 7 ngày qua**.
+- **Lượt xem trang (Page views)** trong khoảng thời gian đã chọn.
+- Một **biểu đồ diễn biến (evolution graph)** của số khách truy cập duy nhất hàng ngày.
+- Các tab phân tích theo **Ngôn ngữ (Locales)** và **Vị trí (Location)**, xếp hạng khán giả của bạn theo ngôn ngữ và quốc gia.
+
+## Tham khảo API Backend (Backend API reference)
+
+Tất cả các điểm cuối (endpoint) để đọc đều yêu cầu xác thực; việc thu thập dữ liệu (ingestion) là công khai và được quy cho thông qua thuộc tính `clientId` trong phần body.
+
+| Phương thức | Điểm cuối (Endpoint)                        | Mô tả                                                                                             |
+| ----------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `POST`      | `/api/analytics/events`                     | Thu nhận một lô sự kiện (công khai, được gán bởi `clientId` trong body).                          |
+| `GET`       | `/api/analytics/overview`                   | Tổng số trang / ngôn ngữ cho dự án đã được xác thực.                                              |
+| `GET`       | `/api/analytics/audience?days=30`           | Khách truy cập duy nhất, lượt xem trang, chuỗi ngày, phân tích theo ngôn ngữ + quốc gia.          |
+| `GET`       | `/api/analytics/content-stats`              | Tổng số lượt hiển thị theo mỗi nội dung, được nhóm theo khóa từ điển / đường dẫn khóa / ngôn ngữ. |
+| `GET`       | `/api/analytics/experiments/:experimentKey` | Tỷ lệ chuyển đổi cho mỗi biến thể và ý nghĩa thống kê cho một thử nghiệm A/B.                     |
+
+Bạn cũng có thể gọi các API này theo chương trình thông qua [CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/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);
+```
+
+## Các liên kết hữu ích
+
+- [Từ điển Động - Bộ sưu tập & Biến thể (Dynamic Dictionaries)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dynamic_dictionaries/index.md)
+- [Intlayer CMS - CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/intlayer_CMS.md)
+- [Trình chỉnh sửa Trực quan Intlayer (Visual Editor)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/intlayer_visual_editor.md)
+- [Tham khảo Cấu hình (Configuration Reference)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/configuration.md)
+- [Hướng dẫn Tự lưu trữ (Self-Hosting Guide)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/self_hosting.md)

package/docs/vi/bundle_optimization.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-06-07
+updatedAt: 2026-08-09
 title: Tối ưu hóa dung lượng Bundle & Hiệu suất i18n
 description: Giảm dung lượng bundle của ứng dụng bằng cách tối ưu hóa nội dung quốc tế hóa (i18n). Tìm hiểu cách tận dụng tree shaking và tải 지연 (lazy loading) cho các từ điển với Intlayer.
 keywords:
@@ -16,6 +16,12 @@ slugs:
   - concept
   - bundle-optimization
 history:
+  - version: 9.2.1
+    date: 2026-08-09
+    changes: "`purge` và `minify` giờ đã hoạt động trên Next.js thông qua `@intlayer/swc` — không cần `babel.config.js`"
+  - version: 8.12.0
+    date: 2026-06-24
+    changes: "Liệt kê các plugin Babel theo đúng thứ tự pipeline (extract → purge → minify → optimize) trong các bảng tham chiếu"
   - version: 8.12.0
     date: 2026-06-07
     changes: "Thêm `intlayerPurgeBabelPlugin` và `intlayerMinifyBabelPlugin` cho Babel/Webpack; làm rõ quá trình thực thi của các plugin"
@@ -191,12 +197,14 @@ Trình tối ưu hóa build của Intlayer được chia làm nhiều plugin ri
 
 Những plugin này được khai báo trực tiếp vào `babel.config.js` ở các dự án phụ thuộc cấu hình Webpack (như Next.js dùng Babel, CRA, hoặc Webpack tùy chỉnh v.v.).
 
+Bảng dưới đây liệt kê chúng theo đúng thứ tự pipeline (cùng thứ tự mà chúng phải xuất hiện trong `babel.config.js`):
+
 | Plugin                        | Công dụng                                                                                                                                     |
 | :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- |
 | `intlayerExtractBabelPlugin`  | Quét các file `.content.ts` và ghi nội dung từ điển đã biên dịch thành định dạng chuẩn vào thư mục `.intlayer/`                               |
-| `intlayerOptimizeBabelPlugin` | Viết lại `useIntlayer('key')` thành `useDictionary(hash)` và tự động inject thư viện `import` để nạp từ điển khớp tương ứng                   |
 | `intlayerPurgeBabelPlugin`    | Quét toàn bộ mã nguồn, thực hiện loại bỏ (remove) **các trường nội dung không được sử dụng** ở file từ điển JSON tại `.intlayer/**/*.json`    |
 | `intlayerMinifyBabelPlugin`   | **Rút ngắn tên (rename) khóa (keys) của nội dung** thành ký tự ngắn rút gọn (vd: `title` đổi thành `a`) ở JSON cũng như bên trong Source Code |
+| `intlayerOptimizeBabelPlugin` | Viết lại `useIntlayer('key')` thành `useDictionary(hash)` và tự động inject thư viện `import` để nạp từ điển khớp tương ứng                   |
 
 > **Thứ tự sắp xếp của plugin là rất quan trọng.** Trong `babel.config.js` của bạn, các plugin purge và minify phải được đặt **trước** plugin optimize. Bước optimize thay thế `useIntlayer('key')` bằng một hàm gọi không minh bạch `useDictionary(hash)`, điều này có khả năng làm mất thông tin dictionary-key gốc - vốn là thông tin cần thiết để purge và minify có thể định danh các trường thuộc tính đang được ứng dụng.
 
@@ -205,9 +213,9 @@ Mỗi plugin Babel sẽ đi kèm một helper option để đọc trực tiếp
 | Options helper               | Dùng cùng với                 |
 | :--------------------------- | :---------------------------- |
 | `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
-| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 | `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
 | `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 
 ### Các plugin của Vite (`vite-intlayer`)
 
@@ -220,6 +228,20 @@ Những người dùng Vite **không bao giờ phải cấu hình cái này mộ
 | Dictionary minify     | Tương tự quy trình cắt giảm và rút ngắn độ dài JSON của `intlayerMinifyBabelPlugin` qua JSON                                                       |
 | Babel transform       | Tương tự quá trình viết lại tên khóa (key rename) bên nguồn code của `intlayerMinifyBabelPlugin` + thay phiên mã của `intlayerOptimizeBabelPlugin` |
 
+### Plugin SWC (`@intlayer/swc`)
+
+Người dùng Next.js cũng **không bao giờ cấu hình những thứ này trực tiếp**. Từ **v9.2.1**, `withIntlayer()` trong `next.config.ts` chạy toàn bộ pipeline — purge, minify và viết lại import — chỉ dựa trên hai cờ `build.purge` và `build.minify`.
+
+Công việc được chia làm hai, vì một plugin Wasm của SWC chỉ biến đổi một tệp tại một thời điểm và không có quyền truy cập hệ thống tệp:
+
+| Lượt xử lý                                 | Chạy ở đâu                       | Làm gì                                                                                   |
+| :----------------------------------------- | :------------------------------- | :--------------------------------------------------------------------------------------- |
+| Phân tích sử dụng + purge/minify JSON      | Node, bên trong `withIntlayer()` | Đọc mọi tệp nguồn của component, viết lại `.intlayer/**/*.json`, tạo ra các bảng đổi tên |
+| Viết lại mã nguồn (`content.title` → `.a`) | `@intlayer/swc` (Wasm)           | Áp dụng các bảng đổi tên cho những truy cập thuộc tính tương ứng trong mã của bạn        |
+| Viết lại import (`useIntlayer` → dict)     | `@intlayer/swc` (Wasm)           | Giống `intlayerOptimizeBabelPlugin`                                                      |
+
+Việc xác định _những_ trường nào không được dùng và mỗi trường nhận _bí danh_ nào đòi hỏi trạng thái xuyên tệp và I/O tệp, nên nửa đó chạy trong Node; plugin SWC chỉ nhận các bảng kết quả.
+
 ## Tùy chỉnh thiết lập dựa vào Platform (nền tảng)
 
 <Tabs>
@@ -227,10 +249,12 @@ Những người dùng Vite **không bao giờ phải cấu hình cái này mộ
 
 ### Next.js
 
-Next.js yêu cầu có plugin `@intlayer/swc` cho bước optimize (bước thay thế các lệnh import của hệ thống), do Next.js dùng lõi SWC làm công cụ biên dịch tự động.
+Next.js cần plugin `@intlayer/swc`, vì Next.js dùng SWC để build. Từ **v9.2.1**, chỉ một gói này đã bao trọn toàn bộ pipeline — tối ưu hóa (viết lại import), purge và minify.
 
 > Plugin này không cài đặt theo mặc định bởi vì nền tảng hỗ trợ (API SWC Plugins) trên Next.js vẫn còn là một thử nghiệm. Do đó sẽ có thay đổi khi nó được cập nhật.
 
+> **Next.js 16.1.0 là phiên bản tối thiểu.** Đây là bản phát hành đầu tiên được xây dựng trên ABI plugin Wasm tương thích tiến của SWC; các bản trước đó từ chối plugin. `withIntlayer` đọc phiên bản Next.js của dự án và đơn giản là không đăng ký plugin nếu thấp hơn 16.1.0 — các build đó vẫn thành công, chỉ là chạy mà không có tối ưu hóa bundle.
+
 <Tabs>
  <Tab value="npm">
 
@@ -265,33 +289,40 @@ intlayer-swc-plugin = "*"
 
 Sau khi hoàn tất, Intlayer có thể tìm kiếm và ứng dụng tự động nó cho phần compile hệ thống.
 
-Để áp dụng các bước thao tác **purge và minify** (chức năng xóa bỏ các trường hoặc cấu trúc bị dư thừa, đặt biệt danh thay thế cho file), nên thực hiện bổ sung cài `@intlayer/babel` và thiết lập trên config của Babel. Vì bản thân lõi Next.js dù sử dụng SWC trong quy trình dịch mã cho code (transform) nhưng lại luôn thực hiện phân giải config cài đặt của Babel (qua file `babel.config.js`). Cho nên plugin của Babel sẽ vận hành như bước khởi động tiền đề trước khi chạy SWC.
+Các lượt **purge và minify** (xóa trường và đổi tên trường) không cần gói bổ sung nào cũng không cần `babel.config.js`. Hãy bọc cấu hình của bạn bằng `withIntlayer` và bật các cờ trong `intlayer.config.ts`:
 
-```bash packageManager="npm"
-npm install -D @intlayer/babel
+```typescript fileName="next.config.ts"
+import { withIntlayer } from "next-intlayer/server";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {/* cấu hình của bạn */};
+
+export default withIntlayer(nextConfig);
 ```
 
-```javascript fileName="babel.config.js"
-const {
-  intlayerPurgeBabelPlugin,
-  intlayerMinifyBabelPlugin,
-  getPurgePluginOptions,
-  getMinifyPluginOptions,
-} = require("@intlayer/babel");
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
 
-module.exports = {
-  presets: ["next/babel"],
-  plugins: [
-    // Purge: hủy bỏ các trường đã không còn sử dụng được tìm thấy bên trong .intlayer/**/*.json
-    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
-    // Minify: rút gọn và rút ngắn tên cho các JSON + sửa lệnh ở trên source code
-    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
-    // Lưu ý: Không cần đến khai báo `intlayerOptimizeBabelPlugin` ở đây vì
-    // @intlayer/swc đã tiếp quản tiến trình biến đổi useIntlayer → useDictionary.
-  ],
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // xóa các trường nội dung không dùng khỏi JSON được đóng gói
+    minify: true, // đổi tên khóa trường nội dung thành bí danh ngắn
+  },
 };
+
+export default config;
 ```
 
+Trong quá trình `next build`, `withIntlayer` phân tích mã nguồn, viết lại các từ điển đã biên dịch và chuyển các bảng đổi tên trường thu được cho `@intlayer/swc`, plugin này cập nhật những truy cập thuộc tính tương ứng trong mã của bạn.
+
+> Hãy dùng `withIntlayer` bất đồng bộ, không phải `withIntlayerSync`. Biến thể đồng bộ không chạy pipeline phân tích, nên purge và minify không có tác dụng với nó.
+
+> Purge và minify chỉ chạy khi `next build` — pipeline tối ưu hóa tắt trong lúc `next dev`.
+
+> Chúng cũng bị tắt khi có cấu hình các lời gọi từ bộ chuyển đổi tương thích (`swcExtraCallers`, do các gói tương thích như `@intlayer/next-intl` hay `@intlayer/react-i18next` thiết lập): những điểm gọi đó vô hình với bộ phân tích sử dụng, nên purge sẽ xóa mất các trường mà mã vẫn đang đọc. Việc viết lại import vẫn hoạt động.
+
+**Các phiên bản trước (trước 9.2.1)** yêu cầu `@intlayer/babel` và một tệp `babel.config.js` khai báo `intlayerPurgeBabelPlugin` và `intlayerMinifyBabelPlugin`. Tệp đó không còn cần thiết và có thể xóa.
+
  </Tab>
  <Tab value="vite">
 
@@ -447,6 +478,8 @@ export default config;
 
 > Lưu ý: Sự can thiệp minify sẽ ngừng thực hiện nếu cờ `optimize` được kích ở mức `false` hoặc lúc bộ hiển thị bằng editor đang dùng tham số `editor.enabled` = `true` (do phía editor thiết kế cần đọc đúng định dạng khai báo nguồn nội dung ban đầu từ file config).
 
+> Trên Next.js, minify cũng bị bỏ qua khi `@intlayer/swc` không được cài đặt hoặc không thể tải (Next.js dưới 16.1.0). Plugin chính là nửa viết lại các truy cập trong mã nguồn, nên đổi tên từ điển mà thiếu nó sẽ khiến mã của bạn đọc những tên trường không còn tồn tại.
+
 > Sự can thiệp bằng minify đồng thời mất kiểm soát khi tải từ các lệnh gọi JSON ngoại lai của server api khác thông qua thông số gán thiết lập mặc định qua file nguồn `importMode: 'fetch'` — điều này giải quyết và chống phá hỏng liên lạc bằng json của đầu ra máy chủ do nếu app tại máy tính người xài thay danh định gốc trên code sẽ đứt đường tiếp nhận dữ liệu phía cloud.
 
 ### Hệ chức năng gạt bỏ rác Purging (xóa trắng các khóa thuộc tính trống hoặc dư)
@@ -475,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> Hãy cân nhắc bởi Purge cũng chẳng khác gì minify, hệ sẽ phớt lờ thao tác nếu như thông số thuộc `optimize` để là `false` hay công cụ trình hỗ trợ `editor.enabled` đang mở (true).
+> Hãy cân nhắc bởi Purge cũng chẳng khác gì minify, hệ sẽ phớt lờ thao tác nếu như thông số thuộc `optimize` để là `false` hay công cụ trình hỗ trợ `editor.enabled` đang mở (true). Trên Next.js, nó còn bị bỏ qua khi `@intlayer/swc` không khả dụng và khi có cấu hình các lời gọi từ bộ chuyển đổi tương thích.
 
 > Ngoài ra chức năng của hệ cũng bảo lưu quy trình rủi ro và buộc dừng tiến trình purge (như khi không parse được code nguồn để phân tích), hoặc lệnh trả biến ở bộ thu nhận `useIntlayer` xài như thông số ẩn hoặc bị mã hóa ngầm lúc khai báo truyền tin nên analyzer bot mất dấu để định hướng hành tung của nội dung nguồn (một trường hợp cụ thể đó là kiểu trải dữ liệu `spread` cho vô Object bự xài nhưng quên không destructure rõ ràng tham số lúc dùng trong prop). Tại ranh giới bất an kiểu này hệ tự ép lấy sạch sành sanh cho yên tâm trọn gói JSON mà khỏi sợ cắt lố làm mất dữ liệu oan.