@intlayer/docs 9.0.0-canary.14 → 9.0.0-canary.16

package/docs/zh/intlayer_CMS.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-08-23
-updatedAt: 2025-08-23
+updatedAt: 2026-07-08
 title: Intlayer CMS | 将您的内容外部化到 Intlayer CMS
 description: 将您的内容外部化到 Intlayer CMS，以将内容管理委托给您的团队。
 keywords:
@@ -18,6 +18,9 @@ slugs:
   - cms
 youtubeVideo: https://www.youtube.com/watch?v=UDDTnirwi_4
 history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "将「实时同步」章节移动到独立页面（live-sync.md），此处仅保留简短介绍和链接"
   - version: 6.0.1
     date: 2025-09-22
     changes: "添加实时同步文档"
@@ -245,134 +248,7 @@ bun x intlayer dictionary push -d my-first-dictionary-key --env production
 
 实时同步让您的应用在运行时反映 CMS 内容的更改。无需重新构建或重新部署。启用后，更新会被流式传输到实时同步服务器，刷新您的应用读取的字典。
 
-> 实时同步需要持续的服务器连接，并且仅在企业版计划中可用。
-
-通过更新您的 Intlayer 配置来启用实时同步：
-
-```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
-import type { IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  // ... 其他配置设置
-  editor: {
-    /**
-     * 当检测到更改时，启用本地配置的热重载。
-     * 例如，当添加或更新字典时，应用程序会更新页面上显示的内容。
-     *
-     * 由于热重载需要与服务器保持持续连接，
-     * 因此仅对 `enterprise` 计划的客户开放。
-     *
-     * 默认值：false
-     */
-    liveSync: true,
-  },
-  dictionary: {
-    /**
-     * 控制字典的导入方式：
-     *
-     * - "live"：字典通过 Live Sync API 动态获取。
-     *   替换 useIntlayer 为 useDictionaryDynamic。
-     *
-     * 注意：Live 模式使用 Live Sync API 获取字典。如果 API 调用失败，
-     * 字典将动态导入。
-     * 注意：只有带有远程内容和 "live" 标志的字典使用 live 模式。
-     * 其他字典为了性能使用动态模式。
-     */
-    importMode: "fetch",
-  },
-};
-
-export default config;
-```
-
-启动 Live Sync 服务器以包裹您的应用程序：
-
-使用 Next.js 的示例：
-
-```json5 fileName="package.json"
-{
-  "scripts": {
-    // ... 其他脚本
-    "build": "next build",
-    "dev": "next dev",
-    "start": "npx intlayer live --with 'next start'",
-  },
-}
-```
-
-使用 Vite 的示例：
-
-```json5 fileName="package.json"
-{
-  "scripts": {
-    // ... 其他脚本
-    "build": "vite build",
-    "dev": "vite dev",
-    "start": "npx intlayer live --with 'vite start'",
-  },
-}
-```
-
-Live Sync 服务器包裹您的应用程序，并在更新内容到达时自动应用。
-
-为了接收来自 CMS 的变更通知，Live Sync 服务器会与后端保持 SSE 连接。当 CMS 中的内容发生变化时，后端会将更新转发给 Live Sync 服务器，服务器会写入新的字典。您的应用将在下一次导航或浏览器刷新时反映更新, 无需重新构建。
-
-流程图（CMS/后端 -> Live Sync 服务器 -> 应用服务器 -> 前端）：
-
-![Live Sync 逻辑示意图](https://github.com/aymericzip/intlayer/blob/main/docs/assets/live_sync_logic_schema.svg)
-
-工作原理：
-
-![Live Sync 流程 CMS/后端/Live Sync 服务器/应用服务器/前端示意图](https://github.com/aymericzip/intlayer/blob/main/docs/assets/live_sync_flow_scema.svg)
-
-### 开发工作流程（本地）
-
-- 在开发过程中，应用启动时会获取所有远程字典，因此您可以快速测试更新。
-- 要在本地使用 Next.js 测试 Live Sync，请包装您的开发服务器：
-
-```json5 fileName="package.json"
-{
-  "scripts": {
-    // ... 其他脚本
-    "dev": "npx intlayer live --with 'next dev'",
-    // "dev": "npx intlayer live --with 'vite dev'", // 适用于 Vite
-  },
-}
-```
-
-启用优化，以便 Intlayer 在开发期间应用实时导入转换：
-
-```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
-import type { IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  editor: {
-    applicationURL: "http://localhost:5173",
-    liveSyncURL: "http://localhost:4000",
-    liveSync: true,
-  },
-  dictionary: {
-    importMode: "fetch",
-  },
-  build: {
-    optimize: true,
-  },
-};
-
-export default config;
-```
-
-此设置将您的开发服务器与实时同步服务器包装在一起，在启动时获取远程字典，并通过 SSE 从 CMS 流式传输更新。刷新页面以查看更改。
-
-注意事项和限制：
-
-- 将实时同步源添加到您的站点安全策略（CSP）中。确保实时同步 URL 被允许在 `connect-src` 中（如果相关，也包括 `frame-ancestors`）。
-- 实时同步不适用于静态输出。对于 Next.js，页面必须是动态的才能在运行时接收更新（例如，适当使用 `generateStaticParams`、`generateMetadata`、`getServerSideProps` 或 `getStaticProps`，以避免完全静态的限制）。
-- 应用程序 URL 应与您在编辑器配置中设置的 URL (`applicationURL`) 匹配。
-- CMS URL
-- 确保项目配置已推送到 Intlayer CMS。
-
-- 可视化编辑器使用 iframe 来显示您的网站。确保您网站的内容安全策略（CSP）允许 CMS URL 作为 `frame-ancestors`（默认是 'https://intlayer.org'）。检查编辑器控制台是否有任何错误。
+完整的设置指南（启用方式、启动 Live Sync 服务器、本地开发工作流程和限制条件）请参阅 [Live Sync 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/live-sync.md)。
 
 ## 调试
 

package/docs/zh/live-sync.md

@@ -0,0 +1,175 @@
+---
+createdAt: 2026-07-08
+updatedAt: 2026-07-08
+title: 实时同步（Live Sync）| 让应用实时反映 CMS 内容变更
+description: 让您的应用在运行时实时反映 Intlayer CMS 的内容变更，无需重新构建或重新部署。
+keywords:
+  - 实时同步
+  - Live Sync
+  - CMS
+  - 可视化编辑器
+  - 国际化
+  - 文档
+  - Intlayer
+  - Next.js
+  - Vite
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "从 Intlayer CMS 文档中拆分为独立页面"
+  - version: 6.0.1
+    date: 2025-09-22
+    changes: "添加实时同步文档"
+  - version: 6.0.0
+    date: 2025-09-04
+    changes: "用 `liveSync` 字段替换 `hotReload` 字段"
+author: aymericzip
+---
+
+# 实时同步
+
+实时同步让您的应用在运行时反映 CMS 内容的更改。无需重新构建或重新部署。启用后，更新会被流式传输到实时同步服务器，刷新您的应用读取的字典。
+
+## 目录
+
+<TOC/>
+
+---
+
+## 启用实时同步
+
+> 实时同步需要持续的服务器连接，并且仅在企业版计划中可用。
+
+通过更新您的 Intlayer 配置来启用实时同步：
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... 其他配置设置
+  editor: {
+    /**
+     * 当检测到更改时，启用本地配置的热重载。
+     * 例如，当添加或更新字典时，应用程序会更新页面上显示的内容。
+     *
+     * 由于热重载需要与服务器保持持续连接，
+     * 因此仅对 `enterprise` 计划的客户开放。
+     *
+     * 默认值：false
+     */
+    liveSync: true,
+  },
+  dictionary: {
+    /**
+     * 控制字典的导入方式：
+     *
+     * - "live"：字典通过 Live Sync API 动态获取。
+     *   替换 useIntlayer 为 useDictionaryDynamic。
+     *
+     * 注意：Live 模式使用 Live Sync API 获取字典。如果 API 调用失败，
+     * 字典将动态导入。
+     * 注意：只有带有远程内容和 "live" 标志的字典使用 live 模式。
+     * 其他字典为了性能使用动态模式。
+     */
+    importMode: "fetch",
+  },
+};
+
+export default config;
+```
+
+启动 Live Sync 服务器以包裹您的应用程序：
+
+使用 Next.js 的示例：
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... 其他脚本
+    "build": "next build",
+    "dev": "next dev",
+    "start": "npx intlayer live --with 'next start'",
+  },
+}
+```
+
+使用 Vite 的示例：
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... 其他脚本
+    "build": "vite build",
+    "dev": "vite dev",
+    "start": "npx intlayer live --with 'vite start'",
+  },
+}
+```
+
+Live Sync 服务器包裹您的应用程序，并在更新内容到达时自动应用。
+
+为了接收来自 CMS 的变更通知，Live Sync 服务器会与后端保持 SSE 连接。当 CMS 中的内容发生变化时，后端会将更新转发给 Live Sync 服务器，服务器会写入新的字典。您的应用将在下一次导航或浏览器刷新时反映更新, 无需重新构建。
+
+流程图（CMS/后端 -> Live Sync 服务器 -> 应用服务器 -> 前端）：
+
+![Live Sync 逻辑示意图](https://github.com/aymericzip/intlayer/blob/main/docs/assets/live_sync_logic_schema.svg)
+
+工作原理：
+
+![Live Sync 流程 CMS/后端/Live Sync 服务器/应用服务器/前端示意图](https://github.com/aymericzip/intlayer/blob/main/docs/assets/live_sync_flow_scema.svg)
+
+## 开发工作流程（本地）
+
+- 在开发过程中，应用启动时会获取所有远程字典，因此您可以快速测试更新。
+- 要在本地使用 Next.js 测试 Live Sync，请包装您的开发服务器：
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    // ... 其他脚本
+    "dev": "npx intlayer live --with 'next dev'",
+    // "dev": "npx intlayer live --with 'vite dev'", // 适用于 Vite
+  },
+}
+```
+
+启用优化，以便 Intlayer 在开发期间应用实时导入转换：
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    applicationURL: "http://localhost:5173",
+    liveSyncURL: "http://localhost:4000",
+    liveSync: true,
+  },
+  dictionary: {
+    importMode: "fetch",
+  },
+  build: {
+    optimize: true,
+  },
+};
+
+export default config;
+```
+
+此设置将您的开发服务器与实时同步服务器包装在一起，在启动时获取远程字典，并通过 SSE 从 CMS 流式传输更新。刷新页面以查看更改。
+
+## 注意事项和限制
+
+- 将实时同步源添加到您的站点安全策略（CSP）中。确保实时同步 URL 被允许在 `connect-src` 中（如果相关，也包括 `frame-ancestors`）。
+- 实时同步不适用于静态输出。对于 Next.js，页面必须是动态的才能在运行时接收更新（例如，适当使用 `generateStaticParams`、`generateMetadata`、`getServerSideProps` 或 `getStaticProps`，以避免完全静态的限制）。
+- 应用程序 URL 应与您在编辑器配置中设置的 URL (`applicationURL`) 匹配。
+- CMS URL
+- 确保项目配置已推送到 Intlayer CMS。
+
+- 可视化编辑器使用 iframe 来显示您的网站。确保您网站的内容安全策略（CSP）允许 CMS URL 作为 `frame-ancestors`（默认是 'https://intlayer.org'）。检查编辑器控制台是否有任何错误。
+
+## Useful links
+
+- [Intlayer CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md)
+- [Intlayer 可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md)
+- [配置参考](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)
+- [自托管指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/self_hosting.md)

package/docs/zh/releases/v9.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-29
+updatedAt: 2026-07-08
 title: New Intlayer v9 - What's new?
 description: Discover what's new in Intlayer v9. Introducing drop-in compatibility packages for popular i18n libraries and support for Collections and Variants.
 keywords:
@@ -199,6 +199,49 @@ const product = useIntlayer("product-copy", {
 
 ---
 
+## `@intlayer/analytics`：内容曝光追踪与 A/B 测试
+
+全新的可选包 [`@intlayer/analytics`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md) 会告诉您访客实际看到了哪些内容——并通过让您对内容进行 A/B 测试、按变体衡量转化率，补上 **Collections & Variants** 的最后一环。
+
+- **Provider 级别追踪**：`IntlayerProvider`（React / Next.js / React Native）会在加载、路由变化和语言切换时自动记录 `page_view` 事件。
+- **节点级别追踪**：每次 `useIntlayer` 解析都会上报一个 `content_exposure` 事件——包括显示了哪个字典键、键路径、语言，以及（如适用）哪个 A/B **变体**。同一刷新窗口内对同一节点的重复曝光会被合并为一个事件。
+- **确定性 A/B 分配**：`getVariant(experimentKey, variants)` 在**无需服务器往返**的情况下为每个会话分配变体，因此首次渲染前不会出现闪烁。
+- **`useConversion()`**：将目标（注册、点击、购买等）归因于会话所看到的变体。
+- **未安装时零成本**：与 `@intlayer/editor` 相同的可摇树优化模式——用 `try/catch` 包裹的动态 `import()`，加上一个编译期环境变量（`INTLAYER_ANALYTICS_ENABLED`），对未启用的应用会将整个集成从打包结果中彻底移除。
+- **无需新增配置项**：复用现有的 `editor.backendURL`（上报端点 / 自托管）和 `editor.clientId`（项目密钥，同时也是启用开关）。
+- **注重隐私**：会话匿名哈希化（SHA-256，不存储原始 ID）、不存储 IP、仅保留粗粒度的国家级地理位置，请求大约每 20 秒批量发送一次。
+- **仪表盘**：新的 **Analytics** 页面（选择项目后显示在侧边栏中）展示活跃用户数、今日用户数、最近 7/30/90 天用户数、访客变化趋势图，以及按语言和地理位置的细分。
+
+```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",
+        })
+      }
+    >
+      Get started
+    </button>
+  );
+};
+```
+
+```bash packageManager="npm"
+npm install @intlayer/analytics
+```
+
+目前已支持 React、Next.js 和 React Native（通过 `react-intlayer`）；其他框架绑定（Vue、Svelte、Angular 等）正在规划中，将遵循与 `@intlayer/editor` 相同的推广模式。完整指南请参阅 [Analytics 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md)。
+
+---
+
 ## Vite Plugin: 捆绑编译器和代理
 
 `intlayer()` Vite 插件现在直接捆绑了**编译器**和**区域设置路由代理**，因此大多数项目只需在 `vite.config.ts` 中使用单个插件：
@@ -320,5 +363,6 @@ If you are upgrading from v8, note that the v9 does not include breaking changes
 
 - [Compat Adapter Packages Guide](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md)
 - [Dynamic Dictionaries - Collections & Variants](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/dynamic_dictionaries/index.md)
+- [Analytics - 内容曝光追踪与 A/B 测试](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/analytics.md)
 - [Configuration Reference](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)
 - [CMS SDK - 通过 @intlayer/api 进行编程访问](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/docs",
-  "version": "9.0.0-canary.14",
+  "version": "9.0.0-canary.16",
   "private": false,
   "description": "Intlayer documentation",
   "keywords": [
@@ -73,13 +73,13 @@
     "watch": "webpack --config ./webpack.config.ts --watch"
   },
   "dependencies": {
-    "@intlayer/config": "9.0.0-canary.14",
-    "@intlayer/core": "9.0.0-canary.14",
-    "@intlayer/types": "9.0.0-canary.14"
+    "@intlayer/config": "9.0.0-canary.16",
+    "@intlayer/core": "9.0.0-canary.16",
+    "@intlayer/types": "9.0.0-canary.16"
   },
   "devDependencies": {
-    "@intlayer/api": "9.0.0-canary.14",
-    "@intlayer/cli": "9.0.0-canary.14",
+    "@intlayer/api": "9.0.0-canary.16",
+    "@intlayer/cli": "9.0.0-canary.16",
     "@types/node": "25.9.4",
     "@utils/ts-config": "1.0.4",
     "@utils/ts-config-types": "1.0.4",
@@ -88,7 +88,7 @@
     "rimraf": "6.1.3",
     "tsdown": "0.21.10",
     "typescript": "6.0.3",
-    "vitest": "4.1.9"
+    "vitest": "4.1.10"
   },
   "engines": {
     "node": ">=14.18"

package/src/generated/docs.entry.ts

@@ -93,6 +93,26 @@ export const docsEntry = {
     vi: readLocale('agent_skills.md', 'vi'),
     uk: readLocale('agent_skills.md', 'uk'),
   } as unknown as Record<LocalesValues, Promise<string>>,
+  './docs/en/analytics.md': {
+    en: readLocale('analytics.md', 'en'),
+    ru: readLocale('analytics.md', 'ru'),
+    ja: readLocale('analytics.md', 'ja'),
+    fr: readLocale('analytics.md', 'fr'),
+    ko: readLocale('analytics.md', 'ko'),
+    zh: readLocale('analytics.md', 'zh'),
+    es: readLocale('analytics.md', 'es'),
+    de: readLocale('analytics.md', 'de'),
+    ar: readLocale('analytics.md', 'ar'),
+    it: readLocale('analytics.md', 'it'),
+    'en-GB': readLocale('analytics.md', 'en-GB'),
+    pt: readLocale('analytics.md', 'pt'),
+    hi: readLocale('analytics.md', 'hi'),
+    tr: readLocale('analytics.md', 'tr'),
+    pl: readLocale('analytics.md', 'pl'),
+    id: readLocale('analytics.md', 'id'),
+    vi: readLocale('analytics.md', 'vi'),
+    uk: readLocale('analytics.md', 'uk'),
+  } as unknown as Record<LocalesValues, Promise<string>>,
   './docs/en/autoFill.md': {
     en: readLocale('autoFill.md', 'en'),
     ru: readLocale('autoFill.md', 'ru'),
@@ -2393,6 +2413,26 @@ export const docsEntry = {
     vi: readLocale('introduction.md', 'vi'),
     uk: readLocale('introduction.md', 'uk'),
   } as unknown as Record<LocalesValues, Promise<string>>,
+  './docs/en/live-sync.md': {
+    en: readLocale('live-sync.md', 'en'),
+    ru: readLocale('live-sync.md', 'ru'),
+    ja: readLocale('live-sync.md', 'ja'),
+    fr: readLocale('live-sync.md', 'fr'),
+    ko: readLocale('live-sync.md', 'ko'),
+    zh: readLocale('live-sync.md', 'zh'),
+    es: readLocale('live-sync.md', 'es'),
+    de: readLocale('live-sync.md', 'de'),
+    ar: readLocale('live-sync.md', 'ar'),
+    it: readLocale('live-sync.md', 'it'),
+    'en-GB': readLocale('live-sync.md', 'en-GB'),
+    pt: readLocale('live-sync.md', 'pt'),
+    hi: readLocale('live-sync.md', 'hi'),
+    tr: readLocale('live-sync.md', 'tr'),
+    pl: readLocale('live-sync.md', 'pl'),
+    id: readLocale('live-sync.md', 'id'),
+    vi: readLocale('live-sync.md', 'vi'),
+    uk: readLocale('live-sync.md', 'uk'),
+  } as unknown as Record<LocalesValues, Promise<string>>,
   './docs/en/locale_mapper.md': {
     en: readLocale('locale_mapper.md', 'en'),
     ru: readLocale('locale_mapper.md', 'ru'),