@intlayer/docs 9.0.0-canary.2 → 9.0.0-canary.20

package/docs/zh/formatters.md

@@ -383,6 +383,36 @@ currency(1234.5, { currency: "EUR" }); // "€1,234.50"
 currency("5000", { locale: "fr", currency: "CAD", currencyDisplay: "code" }); // "5 000,00 CAD"
 ```
 
+## 缓存的 Intl
+
+从 `intlayer` 导出的 `Intl` 是围绕全局 `Intl` 的缓存包装器。它会缓存格式化程序实例（`NumberFormat`、`DateTimeFormat` 等），以避免重复构造它们，从而提高性能。
+
+```ts
+import { Intl } from "intlayer";
+
+// 数字格式化
+const numberFormat = new Intl.NumberFormat("en-GB", {
+  style: "currency",
+  currency: "GBP",
+});
+numberFormat.format(1234.5); // "£1,234.50"
+
+// 语言、地区等的显示名称
+const displayNames = new Intl.DisplayNames("fr", { type: "language" });
+displayNames.of("en"); // "anglais"
+
+// 用于排序的排序规则
+const collator = new Intl.Collator("fr", { sensitivity: "base" });
+collator.compare("é", "e"); // 0 (相等)
+
+// 复数规则
+const pluralRules = new Intl.PluralRules("fr");
+pluralRules.select(1); // "one"
+pluralRules.select(2); // "other"
+```
+
+### 额外的 Intl 功能
+
 ### `date(date, optionsOrPreset?)`
 
 使用 `Intl.DateTimeFormat` 格式化日期/时间值。
@@ -441,6 +471,8 @@ units(5, { unit: "kilometer", unitDisplay: "long", locale: "en-GB" }); // "5 kil
 units(1024, { unit: "byte", unitDisplay: "narrow" }); // "1,024B"（依赖于区域设置）
 ```
 
+## 地区工具
+
 ### `compact(value, options?)`
 
 使用紧凑表示法格式化数字（例如，`1.2K`，`1M`）。
@@ -482,6 +514,17 @@ list([1, 2, 3], { type: "unit" }); // "1, 2, 3"
 - 如果未提供，区域设置默认使用您配置的 `internationalization.defaultLocale`。
 - 这些工具是轻量封装；对于高级格式化，请直接传递标准的 `Intl` 选项。
 
+### `getPathWithoutLocale(inputUrl, locales?)`
+
+从 URL 中移除语言区域段：
+
+```ts
+import { getPathWithoutLocale } from "intlayer";
+
+getPathWithoutLocale("/en/dashboard"); // "/dashboard"
+getPathWithoutLocale("/fr/dashboard"); // "/dashboard"
+```
+
 ## 入口点和重新导出（`@index.ts`）
 
 格式化函数位于核心包中，并从更高级的包中重新导出，以保持跨运行时的导入简洁：
@@ -512,6 +555,20 @@ import {
 } from "intlayer";
 ```
 
+### `getHTMLTextDir(locale?)`
+
+返回一个 locale 的文本方向：
+
+```ts
+import { getHTMLTextDir } from "intlayer";
+
+getHTMLTextDir("en-US"); // "ltr"
+getHTMLTextDir("ar"); // "rtl"
+getHTMLTextDir("he"); // "rtl"
+```
+
+## 内容处理工具
+
 ### React
 
 客户端组件：
@@ -592,6 +649,20 @@ import {
 
 > 这些钩子将会从 `IntlayerProvider` 或 `IntlayerServerProvider` 中获取语言环境
 
+### `getTranslation(languageContent, locale?, fallback?)`
+
+为特定语言环境提取内容：
+
+```ts
+import { getTranslation } from "intlayer";
+
+const content = getTranslation(
+  { zh: "你好", en: "Hello", fr: "Bonjour", de: "Hallo" },
+  "fr",
+  true
+); // "Bonjour"
+```
+
 ### Vue
 
 客户端组件：
@@ -610,3 +681,9 @@ import {
 ```
 
 > 这些组合式函数将会使用注入的 `IntlayerProvider` 中的语言环境
+
+## 注意事项
+
+- 所有辅助函数接受 `string` 输入；它们在内部被强制转换为数字或日期。
+- 如果未提供 locale，则默认为你配置的 `internationalization.defaultLocale`。
+- 这些实用程序是薄包装器；对于高级格式化，请传递标准 `Intl` 选项。

package/docs/zh/how_works_intlayer.md

@@ -22,6 +22,10 @@ author: aymericzip
 
 # Intlayer 的工作原理
 
+## 目录
+
+<TOC/>
+
 ## 概述
 
 Intlayer 的核心理念是采用每个组件的内容管理。因此，Intlayer 的理念是允许您在代码库中的任何地方声明内容，例如与组件位于同一目录中。
@@ -127,8 +131,6 @@ Intlayer 由多个包组成，每个包在翻译过程中都有特定的角色
 
 ### react-intlayer
 
-### react-intlayer
-
 `react-intlayer` 包用于解释 Intlayer 字典并使其在 React 应用中可用。
 
 ### next-intlayer
@@ -157,8 +159,6 @@ Intlayer 由多个包组成，每个包在翻译过程中都有特定的角色
 
 ### angular-intlayer (开发中)
 
-### angular-intlayer (开发中)
-
 `angular-intlayer` 包用于解释 Intlayer 字典并使其在 Angular 应用中可用。
 
 ### express-intlayer
@@ -219,9 +219,9 @@ Intlayer 由多个包组成，每个包在翻译过程中都有特定的角色
 
 `@intlayer/dictionaries-entry`、`@intlayer/unmerged-dictionaries-entry` 和 `@intlayer/dynamic-dictionaries-entry` 包返回 Intlayer 字典的入口路径。由于浏览器无法搜索文件系统，因此无法使用像 Webpack 或 Rollup 这样的打包工具来获取字典的入口路径。这些包设计为别名，以便在 Vite、Webpack 和 Turbopack 等各种打包工具中进行打包优化。
 
-### @intlayer/chokidar
+### @intlayer/engine
 
-`@intlayer/chokidar` 包用于监视内容文件，并在每次修改时重新生成被修改的字典。
+`@intlayer/engine` 包用于监视内容文件，并在每次修改时重新生成被修改的字典。
 
 ### @intlayer/editor
 

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: "添加实时同步文档"
@@ -40,6 +43,12 @@ Intlayer CMS 是一个应用程序，允许您将 Intlayer 项目的内容外部
 
 ![Intlayer CMS 界面](https://github.com/aymericzip/intlayer/blob/main/docs/assets/CMS.png)
 
+## 目录
+
+<TOC/>
+
+---
+
 ## 理解远程字典
 
 Intlayer 区分“本地”字典和“远程”字典。
@@ -239,131 +248,19 @@ 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 服务器，服务器会写入新的字典。您的应用将在下一次导航或浏览器刷新时反映更新, 无需重新构建。
+完整的设置指南（启用方式、启动 Live Sync 服务器、本地开发工作流程和限制条件）请参阅 [Live Sync 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/live-sync.md)。
 
-流程图（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;
-```
+如果您遇到 CMS 的任何问题，请检查以下内容：
 
-此设置将您的开发服务器与实时同步服务器包装在一起，在启动时获取远程字典，并通过 SSE 从 CMS 流式传输更新。刷新页面以查看更改。
+- 应用程序正在运行。
 
-注意事项和限制：
+- [`editor`](https://intlayer.org/doc/concept/configuration#editor-configuration) 配置在您的 Intlayer 配置文件中设置正确。
+  - 必需字段：
+    - 应用程序 URL 应该与您在编辑器配置中设置的 URL 相匹配（`applicationURL`）。
+    - CMS URL
 
-- 将实时同步源添加到您的站点安全策略（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'）。检查编辑器控制台是否有任何错误。
+- 可视化编辑器使用 iframe 来显示您的网站。确保您的网站的内容安全策略 (CSP) 允许 CMS URL 作为 `frame-ancestors`（默认为 'https://app.intlayer.org'）。检查编辑器控制台中的任何错误。

package/docs/zh/intlayer_with_adonisjs.md

@@ -59,24 +59,44 @@ See [Application Template](https://github.com/aymericzip/intlayer-adonis-templat
 
 要开始使用 `adonis-intlayer`，请使用 npm 安装该包：
 
+```bash packageManager="npm"
+npx intlayer@canary init --interactive    # v9
+# npx intlayer init                       # v8
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer@canary init --interactive   # v9
+# pnpm dlx intlayer init                      # v8
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer@canary init --interactive   # v9
+# yarn dlx intlayer init                      # v8
+```
+
+```bash packageManager="bun"
+bunx intlayer@canary init --interactive   # v9
+# bunx intlayer init                      # v8
+```
+
+> `--interactive` 标志是可选的。如果您是 AI 代理，请使用 `intlayer-cli init`。
+
+> 该命令将检测您的环境并安装所需的软件包。例如：
+
 ```bash packageManager="npm"
 npm install intlayer adonis-intlayer
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer adonis-intlayer
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer adonis-intlayer
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer adonis-intlayer
-bun x intlayer init
 ```
 
 ### 设置

package/docs/zh/intlayer_with_analog.md

@@ -91,160 +91,6 @@ Intlayer 不仅仅是一个 i18n 解决方案，还提供了一个**自托管的
 
 ---
 
-## 在 Analog 应用中设置 Intlayer 的分步指南
-
-查看 GitHub 上的 [应用模板](https://github.com/aymericzip/intlayer-analog-template)。
-
-### 第 1 步：安装依赖项
-
-使用 npm 安装必要的软件包：
-
-```bash packageManager="npm"
-npm install intlayer angular-intlayer vite-intlayer
-npx intlayer init
-```
-
-```bash packageManager="pnpm"
-pnpm add intlayer angular-intlayer vite-intlayer
-pnpm intlayer init
-```
-
-```bash packageManager="yarn"
-yarn add intlayer angular-intlayer vite-intlayer
-yarn intlayer init
-```
-
-```bash packageManager="bun"
-bun add intlayer angular-intlayer vite-intlayer
-bun x intlayer init
-```
-
-- **intlayer**
-
-  核心软件包，提供用于配置管理、翻译、[内容声明](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)、编译和 [CLI 命令](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md)的国际化工具。
-
-- **angular-intlayer**
-  将 Intlayer 与 Angular 应用集成的软件包。它为 Angular 国际化提供上下文提供者和 Hook。
-
-- **vite-intlayer**
-  将 Intlayer 与 Vite 集成的软件包。它提供一个插件来处理内容声明文件，并为优化性能设置别名。
-
-### 第 2 步：项目配置
-
-创建一个配置文件来配置应用的语言：
-
-```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
-import { Locales, type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [
-      Locales.ENGLISH,
-      Locales.FRENCH,
-      Locales.SPANISH,
-      // 您的其他语言
-    ],
-    defaultLocale: Locales.ENGLISH,
-  },
-};
-
-export default config;
-```
-
-> 通过此配置文件，您可以设置本地化 URL、中间件重定向、Cookie 名称、内容声明的位置和扩展名、禁用控制台中的 Intlayer 日志等。有关可用参数的完整列表，请参考[配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
-
-### 第 3 步：在 Vite 配置中集成 Intlayer
-
-要将 Intlayer 与 Analog 集成，您需要使用 `vite-intlayer` 插件。
-
-修改您的 `vite.config.ts` 文件：
-
-```typescript fileName="vite.config.ts"
-import { defineConfig } from "vite";
-import { intlayer } from "vite-intlayer";
-import analog from "@analogjs/platform";
-
-// https://vitejs.dev/config/
-export default defineConfig(() => ({
-  plugins: [
-    analog(),
-    intlayer(), // 添加 Intlayer 插件
-  ],
-}));
-```
-
-> `intlayer()` 插件为 Vite 配置了 Intlayer。它处理内容声明文件并为优化性能设置别名。
-
-### 第 4 步：声明您的内容
-
-创建并管理您的内容声明以存储翻译：
-
-```tsx fileName="src/app/app.content.ts" contentDeclarationFormat=["typescript", "esm", "cjs"]
-import { t, type Dictionary } from "intlayer";
-
-const appContent = {
-  key: "app",
-  content: {
-    title: t({
-      en: "Hello",
-      fr: "Bonjour",
-      es: "Hola",
-      zh: "你好",
-    }),
-    congratulations: t({
-      en: "Congratulations! Your app is running. 🎉",
-      fr: "Félicitations! Votre application est en cours d'exécution. 🎉",
-      es: "¡Felicidades! Tu aplicación está en ejecución. 🎉",
-      zh: "恭喜！您的应用正在运行。 🎉",
-    }),
-  },
-} satisfies Dictionary;
-
-export default appContent;
-```
-
-> 您的内容声明可以定义在应用中的任何位置，只要它们包含在 `contentDir` 目录（默认为 `./src`）中，并且符合内容声明文件扩展名（默认为 `.content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}`）。
-
-> 有关更多详细信息，请参考[内容声明文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)。
-
-### 第 5 步：在代码中使用 Intlayer
-
-要在整个 Analog 应用中使用 Intlayer 的国际化功能，您需要在应用配置中提供 Intlayer。
-
-```typescript fileName="src/app/app.config.ts"
-import { ApplicationConfig } from "@angular/core";
-import { provideIntlayer } from "angular-intlayer";
-
-export const appConfig: ApplicationConfig = {
-  providers: [
-    provideIntlayer(), // 在此处添加 Intlayer 提供者
-  ],
-};
-```
-
-然后，您可以在任何组件中使用 `useIntlayer` 函数。
-
-```typescript fileName="src/app/pages/index.page.ts"
-import { Component } from "@angular/core";
-import { useIntlayer } from "angular-intlayer";
-
-@Component({
-  selector: "app-home",
-  standalone: true,
-  template: `
-    <div class="content">
-      <h1>{{ content().title }}</h1>
-      <p>{{ content().congratulations }}</p>
-    </div>
-  `,
-})
-export default class HomeComponent {
-  content = useIntlayer("app");
-}
-```
-
-Intlayer 内容以 `Signal` 形式返回，因此您通过调用 Signal 来访问值：`content().title`。
-
 ### （可选）第 6 步：更改内容语言
 
 要更改内容的语言，您可以使用 `useLocale` 函数提供的 `setLocale` 函数。这允许您设置应用的语言环境并相应地更新内容。
@@ -351,3 +197,7 @@ Intlayer 使用模块扩充 (module augmentation) 来利用 TypeScript 的优势
 - 轻松创建和更新翻译的**快速操作**。
 
 有关如何使用该扩展的更多详细信息，请参考 [Intlayer VS Code 扩展文档](https://intlayer.org/doc/vs-code-extension)。
+
+### 进一步探索
+
+要进一步探索，你可以实现 [可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md) 或使用 [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md) 外部化你的内容。