@intlayer/docs 9.0.0-canary.3 → 9.0.0-canary.5

package/docs/zh/packages/vue-intlayer/usePathname.md

@@ -0,0 +1,109 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: usePathname 函数文档 | vue-intlayer
+description: 了解如何使用 vue-intlayer 包中的 usePathname 函数
+keywords:
+  - usePathname
+  - pathname
+  - locale
+  - Intlayer
+  - 国际化 (Internationalization)
+  - 文档 (Documentation)
+  - Vue
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - vue-intlayer
+  - usePathname
+history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "添加 usePathname 实用程序"
+  - version: 8.2.0
+    date: 2026-06-22
+    changes: "初始化历史记录"
+author: aymericzip
+---
+
+# Vue 集成：`usePathname` 文档
+
+`usePathname` 函数返回当前浏览器的路径名（pathname），并以 Vue `ComputedRef<string>` 的形式提供移除了 locale 片段后的路径名。这对于构建可感知 locale 的导航非常有用——例如，确定哪个导航项处于激活状态——而无需手动移除 locale 前缀。
+
+## 在 Vue 中导入 `usePathname`
+
+```typescript
+import { usePathname } from "vue-intlayer";
+```
+
+## 概览
+
+`usePathname` 创建一个 Vue 计算引用 (computed ref)，它读取 `window.location.pathname`，通过 `getPathWithoutLocale` 移除 locale 前缀，并且每当浏览器触发 `popstate` 事件（后退/前进导航）时自动更新其值。该值可以直接在你的 Vue 模板或 setup 函数中使用。
+
+## 用法
+
+```vue fileName="src/components/NavItem.vue"
+<script setup lang="ts">
+import { usePathname } from "vue-intlayer";
+
+const props = defineProps<{
+  href: string;
+  label: string;
+}>();
+
+const pathname = usePathname();
+</script>
+
+<template>
+  <a :href="href" :aria-current="pathname === href ? 'page' : undefined">
+    {{ label }}
+  </a>
+</template>
+```
+
+## 返回值
+
+| 类型                  | 描述                                                             |
+| --------------------- | ---------------------------------------------------------------- |
+| `ComputedRef<string>` | Vue Computed Ref，包含不带 locale 前缀的当前路径名（pathname）。 |
+
+## 行为
+
+- **Locale 剥离 (Locale stripping)**：移除路径开头的 locale 片段（例如：`/zh/dashboard` → `/dashboard`）。
+- **响应式 (Reactive)**：在每次 `popstate` 事件（浏览器后退 / 前进导航）时更新值。
+- **SSR 安全 (SSR-safe)**：当 `window` 不可用时返回 `""`。
+- **清理 (Cleanup)**：`popstate` 监听器在初始化时全局添加，由于 Vue 对生命周期的管理，通常不需要在每个组件中手动进行清理。
+
+## 示例
+
+```vue fileName="src/components/Sidebar.vue"
+<script setup lang="ts">
+import { usePathname } from "vue-intlayer";
+
+const links = [
+  { href: "/dashboard", label: "仪表盘" },
+  { href: "/settings", label: "设置" },
+];
+
+const pathname = usePathname();
+</script>
+
+<template>
+  <nav>
+    <a
+      v-for="link in links"
+      :key="link.href"
+      :href="link.href"
+      :style="{ fontWeight: pathname === link.href ? 'bold' : 'normal' }"
+    >
+      {{ link.label }}
+    </a>
+  </nav>
+</template>
+```
+
+## 相关内容
+
+- [`useLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vue-intlayer/useLocale.md) — 当前 locale 及其切换器
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/intlayer/getPathWithoutLocale.md) — 此 hook 所使用的底层实用函数

package/docs/zh/releases/v6.md

@@ -25,6 +25,10 @@ author: aymericzip
 
 欢迎使用 Intlayer v6！本次发布重点提升了性能、开发者体验和可靠性。以下是主要亮点，包括迁移说明和可复制粘贴的示例。
 
+## 目录
+
+<TOC levels={[2]} maxDepth={1} />
+
 ## 亮点
 
 - 新命令：`npx intlayer content test` 用于检测缺失的翻译
@@ -294,6 +298,24 @@ bun x intlayer live --with 'vite preview'
 
 ---
 
+## 使用 turbopack 监视文件的并行进程
+
+当在 Next.js 14 及以上版本中使用 Turbopack 作为开发服务器，并使用 `next dev --turbopack` 命令时，默认情况下字典更改不会被自动检测。
+
+这个限制发生是因为 Turbopack 无法运行 webpack 插件来并行监视内容文件中的更改。
+
+为了解决这个问题，我们使用 `--with` 选项来运行 `intlayer watch` 命令，同时运行开发服务器和 Intlayer 构建监视器。
+
+```json5 fileName="package.json"
+{
+  "scripts": {
+    "dev": "npx intlayer watch --with 'next dev --turbopack'",
+  },
+}
+```
+
+---
+
 ## 迁移说明
 
 - 移除：`dictionaryOutput`（之前为 `i18next` 或 `next-intl`）。此功能将在未来版本中以可插拔适配器形式回归。请从配置中删除该字段。
@@ -312,6 +334,12 @@ bun x intlayer live --with 'vite preview'
 
 ---
 
+## 从 v6 到 v7 的迁移说明
+
+查看 [从 v6 到 v7 的迁移说明](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/releases/v7.md) 了解更多信息。
+
+---
+
 ## 有用的链接
 
 - [CLI 参考](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md)

package/docs/zh/releases/v7.md

@@ -25,6 +25,10 @@ author: aymericzip
 
 欢迎使用 Intlayer v7！此次重大版本发布带来了性能、类型安全和开发者体验的显著提升。以下是主要亮点，包括迁移说明和实用示例。
 
+## 目录
+
+<TOC levels={[2]} maxDepth={1} />
+
 ## 亮点
 
 - 缓存策略以加快构建速度
@@ -261,6 +265,126 @@ setLocale("en");
 
 ---
 
+## 自动代码格式化：formatCommand 配置
+
+v7 在编辑器配置中引入了 `formatCommand` 选项，允许你在 Intlayer 写入内容文件时自动格式化这些文件。这确保了内容声明文件的代码风格和格式的一致性。
+
+如果未设置，Intlayer 将尝试自动检测格式化命令。通过尝试解析以下命令：prettier、biome、eslint。
+
+### 配置
+
+`formatCommand` 选项接受一个字符串模板，其中 `{{file}}` 将被替换为实际的文件路径：
+
+```typescript fileName="intlayer.config.ts"
+export default {
+  content: {
+    formatCommand: 'bun x biome format "{{file}}" --write --log-level none',
+  },
+};
+```
+
+### 支持的格式化工具
+
+你可以使用任何接受文件路径作为参数的代码格式化工具：
+
+**使用 Biome：**
+
+```typescript
+formatCommand: 'bun x biome format "{{file}}" --write --log-level none';
+```
+
+**使用 Prettier：**
+
+```typescript
+formatCommand: 'npx prettier --write "{{file}}" --log-level silent';
+```
+
+**使用 ESLint：**
+
+```typescript
+formatCommand: 'npx eslint --fix "{{file}}" --quiet';
+```
+
+**使用 Bun 的内置格式化工具：**
+
+```typescript
+formatCommand: 'bun format "{{file}}"';
+```
+
+### 优势
+
+- **一致的格式化**：所有内容文件都根据您的项目风格指南自动格式化
+- **开发者体验**：Intlayer 写入文件后无需手动格式化
+- **团队一致性**：确保所有团队成员对内容文件应用相同的格式化
+- **CI/CD 集成**：内容文件在自动化工作流中保持一致的格式化
+
+### 工作原理
+
+当 Intlayer 写入或更新内容声明文件（`.content.ts`、`.content.js` 等）时，它会自动在该文件上运行指定的格式化命令。`{{file}}` 占位符被替换为实际的文件路径，命令在项目的基础目录中执行。
+
+---
+
+## 字典配置：更好的组织和结构
+
+v7 引入了一个新的专属 `dictionary` 配置部分，为字典相关设置和改进的内容管理提供了更好的组织。
+
+### 新的字典配置结构
+
+`fill` 属性已从 `content` 部分移到新的 `dictionary` 部分，提供了更清晰的关注点分离：
+
+**v6 配置：**
+
+```typescript fileName="intlayer.config.ts"
+export default {
+  content: {
+    autoFill: "./{{fileName}}.content.json",
+    contentDir: ["src"],
+  },
+};
+```
+
+**v7 配置：**
+
+```typescript fileName="intlayer.config.ts"
+export default {
+  content: {
+    contentDir: ["src"],
+  },
+  dictionary: {
+    fill: "./{{fileName}}.content.json",
+  },
+};
+```
+
+### 新结构的优势
+
+- **更清晰的组织**: 字典特定的设置现在被分组在一起
+- **更好的关注点分离**: 内容发现与字典操作清晰分离
+- **增强的可维护性**: 更容易理解和修改字典相关的配置
+- **未来的可扩展性**: 字典部分可以容纳额外的字典特定设置
+- **全面的字典管理**: 包括 `title`、`live`、`priority`、`tags`、`version` 和 `description` 等属性，用于创建和管理新的字典
+
+### 配置使用
+
+字典配置有两个主要目的：
+
+1. **默认值**：在创建内容声明文件时定义默认值
+2. **回退行为**：当未定义特定字段时提供回退值，允许您全局定义字典操作行为
+
+字典部分包含用于字典管理的全面属性：
+
+- **`fill`**：内容生成的自动填充行为
+- **`title`**：新字典的默认标题
+- **`live`**：用于实时更新的实时同步配置
+- **`priority`**：字典解析的优先级设置
+- **`tags`**：用于内容组织的默认标签
+- **`version`**：字典更新的版本管理
+- **`description`**：新内容的默认描述
+
+有关内容声明文件以及如何应用配置值的更多信息，请参阅[内容文件文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)。
+
+---
+
 ## fill 命令：更新行为以更好地管理内容
 
 v7 引入了 `fill` 命令的改进行为，提供了更可预测和灵活的内容管理：
@@ -408,6 +532,10 @@ const content = {
 - **`middleware.prefixDefault`**：被 `routing.mode` 替代
 - **`middleware.noPrefix`**：被 `routing.mode` 替代
 
+### 新配置
+
+- **`editor.formatCommand`**: 用于自动格式化内容文件的新选项
+
 ### 迁移映射
 
 #### 配置映射

package/docs/zh/releases/v8.md

@@ -409,6 +409,16 @@ Intlayer v8 对富内容的处理方式进行了重大改进，引入了 **HTML
 
 ---
 
+## YAML & Markdown 内容文件 (v8.10.0)
+
+您现在可以直接使用 `.content.md` 和 `.content.yaml` 文件扩展名声明内容。这非常适合长篇内容、博客、文档和隐私政策。
+
+这些文件可以从可视化编辑器完全编辑，为非技术团队成员提供了简化的工作流程。
+
+有关更多详细信息，请参阅 [YAML 内容文件文档](https://intlayer.org/doc/concept/content#yaml-content-file) 和 [Markdown 内容文件文档](https://intlayer.org/doc/concept/content/markdown)。
+
+---
+
 ## 自定义 URL 重写
 
 Intlayer v8 引入对 **自定义 URL 重写** 的支持，允许你定义与标准 `/locale/path` 结构不同的特定语言路径。此功能可显著提升本地 SEO，并为非英文用户提供更自然的使用体验。
@@ -753,6 +763,62 @@ export default {
   </Tab>
 </Tabs>
 
+## Unicode CLDR 复数规则 (v8.8.0)
+
+基于 Unicode CLDR 项目定义的复数规则，引入了一个新的 `plural` 节点助手，改进了对复杂语言的支持。
+
+```typescript fileName="src/openings.content.ts"
+import { plural, t, type Dictionary } from "intlayer";
+
+const openingsContent = {
+  key: "total_openings",
+  content: {
+    totalOpenings: t({
+      zh: plural({
+        one: "{{count}} 个职位",
+        other: "{{count}} 个职位",
+      }),
+      en: plural({
+        one: "{{count}} opening",
+        other: "{{count}} openings",
+      }),
+      fr: plural({
+        one: "{{count}} offre",
+        other: "{{count}} offres",
+      }),
+    }),
+  },
+} satisfies Dictionary;
+
+export default openingsContent;
+```
+
+然后，你可以在你的框架组件中动态传递计数：
+
+```tsx
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const OpeningsComponent: FC<{ count: number }> = ({ count }) => {
+  const { totalOpenings } = useIntlayer("total_openings");
+
+  return (
+    <div>
+      {/* 英文:                                  */}
+      {/*  count=0  → "0 openings"   (other)           */}
+      {/*  count=1  → "1 opening"    (one)             */}
+      {/*  count=2  → "2 openings"   (other)           */}
+      {/*  count=21 → "21 openings"  (other)           */}
+      <p>{totalOpenings(count)}</p>
+    </div>
+  );
+};
+```
+
+更多信息，请参见 [复数化文档](https://intlayer.org/doc/concept/content/plural)。
+
+---
+
 ## 内容 Schema 验证
 
 Intlayer v8 为字典引入了 schema 验证。你现在可以在配置中使用 Zod 定义可重用的验证 schema，并将其应用到你的内容文件中。这可以确保你的内容始终遵循预期的结构，并在构建时 (build time)捕获错误。
@@ -797,6 +863,34 @@ export default aboutPageMetaContent;
 
 ---
 
+## TypeScript: IntlayerNode Primitive Accessors
+
+`IntlayerNode` 类型已更新，允许直接在内容节点上调用原始 JavaScript 方法。这使得可以直接与本地化内容交互，就像它是一个标准字符串、数字、布尔值或数组原始类型一样。
+
+支持 React、Preact、Solid、Svelte、Vue 和 Angular。
+
+### String 示例
+
+```typescript
+content.placeholder; // 返回 IntlayerNode<string>
+content.placeholder.value; // 返回 string
+content.placeholder.toString(); // 返回 string
+content.placeholder.toLowerCase(); // 返回 string
+String(content.placeholder); // 返回 string
+content.placeholder.toUpperCase(); // 返回大写字符串
+content.placeholder.replace("a", "b"); // 返回修改后的字符串
+```
+
+### Array Example
+
+```typescript
+content.myArrayOfString             // 返回 IntlayerNode<Array<string>>
+content.myArrayOfString.find(...)   // 返回元素
+content.myArrayOfString.join(', ')  // 返回连接的字符串
+```
+
+---
+
 ### 增强的自动内容检测
 
 在 v8 中，Intlayer 能智能检测内容字符串中的 Markdown 语法、HTML 标签和变量插入。这意味着通常可以省略像 `md()`、`html()` 或 `insert()` 这样的辅助函数。
@@ -1002,6 +1096,17 @@ Intlayer 的 VSCode 扩展在 v8 中迎来重大更新，以简化你的国际
 
 ---
 
+## 工具：C++ Watcher & OXC-based LSP (v8.12.0)
+
+Intlayer v8.12.0 为开发者体验带来了重大改进：
+
+- **Parcel Watcher**：内容监听器已从 `chokidar` 迁移到 `@parcel/watcher`，利用原生 C++ 文件监听来提供更快的更新和显著降低的内存消耗。
+- **新的语言服务器协议 (LSP)**：一个全新的 LSP 现已推出。采用基于 OXC 的解析构建，它帮助您的 IDE 和 AI 代理无缝链接 `useIntlayer('my-key')` 调用与其对应的 `.content` 文件，反之亦然。
+
+有关详细信息，请参阅 [LSP 文档](https://intlayer.org/doc/lsp)。
+
+---
+
 ## 编译器优化
 
 Intlayer v8 为 Markdown 和 HTML 编译器引入了新的缓存层。这确保在相同配置下相同的内容字符串只被解析一次，从而显著降低在重新渲染或在多个地方使用相同内容时的开销。
@@ -1057,6 +1162,48 @@ Intlayer v8 为 Markdown 和 HTML 编译器引入了新的缓存层。这确保
 
 ---
 
+## 实验性构建优化：代码缩小和清理 (v8.7.0)
+
+Intlayer v8.7.0 在你的 `intlayer.config.ts` 中引入了新的实验性构建功能，旨在优化你的生产包：
+
+- **字典缩小化**：缩小字典文件以减小大小。
+- **未使用密钥清理**：扫描并从字典中移除未使用的翻译密钥，将活跃密钥重命名为短字符（例如 `"products" -> "a"`、`"pricing" -> "b"`）。这可将包大小减少多达 5%。
+- **禁用 TypeScript 检查**：通过在编译步骤中禁用 TypeScript 类型检查来加快构建速度。
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  dictionary: {
+    importMode: "dynamic",
+  },
+  build: {
+    /**
+     * 缩小字典以减少包大小。
+     */
+    minify: true,
+
+    /**
+     * 清理字典中的未使用密钥
+     */
+    purge: true,
+
+    /**
+     * 指示构建是否应检查 TypeScript 类型
+     */
+    checkTypes: false,
+  },
+};
+
+export default config;
+```
+
+---
+
 ## 灵活性：统一导入模式
 
 `live` 布尔属性已被弃用，改用更为全面的 `importMode` 属性。这样可以明确定义 dictionaries 应如何加载：静态、动态，或通过实时同步。
@@ -1204,6 +1351,49 @@ export default {
 
 ---
 
+## Angular 支持：Vite Bundler (v8.11.0)
+
+对于 Angular 用户，Intlayer 现在通过新的自定义 esbuild 插件原生支持 Vite bundler，加快了开发和构建时间。
+
+有关配置详情，请参阅 [Angular 环境文档](https://intlayer.org/doc/environment/angular)。
+
+---
+
+## 网站地图生成 (v8.6.0)
+
+Intlayer 现在根据您的语言环境和路由模式自动生成网站地图。这对于 TanStack Router 等路由架构中的 SEO 优化特别有用：
+
+```typescript fileName="src/routes/sitemap.xml.ts"
+import { createFileRoute } from "@tanstack/react-router";
+import { generateSitemap } from "intlayer";
+
+const SITE_URL = (
+  import.meta.env.VITE_SITE_URL ?? "http://localhost:3000"
+).replace(/\/$/, "");
+
+export const Route = createFileRoute("/sitemap.xml")({
+  server: {
+    handlers: {
+      GET: async () => {
+        const sitemap = generateSitemap(
+          [
+            { path: "/", changefreq: "daily", priority: 1.0 },
+            { path: "/about", changefreq: "monthly", priority: 0.8 },
+          ],
+          { siteUrl: SITE_URL }
+        );
+
+        return new Response(sitemap, {
+          headers: { "Content-Type": "application/xml" },
+        });
+      },
+    },
+  },
+});
+```
+
+---
+
 ## 从 v7 的迁移说明
 
 ### 配置更改

package/docs/zh/releases/v9.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-14
+updatedAt: 2026-06-23
 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, Variants, and Dynamic Records.
 keywords:
@@ -204,6 +204,42 @@ At build time, `@intlayer/swc` and `@intlayer/babel` scan your files and replace
 
 ---
 
+## Vite Plugin: 捆绑编译器和代理
+
+`intlayer()` Vite 插件现在直接捆绑了**编译器**和**区域设置路由代理**，因此大多数项目只需在 `vite.config.ts` 中使用单个插件：
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+- **Compiler**: 当 `compiler.enabled` 被设置且配置了 `compiler.output` 路径时，自动激活。您不再需要单独注册 `intlayerCompiler()`。
+- **Proxy**: 根据新的 `routing.enableProxy` 选项自动激活（默认为 `true`）。它在开发、预览和生产 SSR 中连接区域设置检测 / 重定向 / 重写中间件。您不再需要单独注册 `intlayerProxy()`。
+
+### `routing.enableProxy` 选项
+
+新的 `routing.enableProxy` 选项控制是否启用区域语言路由代理。默认值为 `true`。当您想自己处理区域语言路由时，可以禁用它：
+
+```ts fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  routing: {
+    enableProxy: false, // 默认值: true
+  },
+};
+
+export default config;
+```
+
+独立的 `intlayerCompiler()` 和 `intlayerProxy()` 插件仍然可用于高级设置。将它们与 `intlayer()` 一起注册是安全的 — 每个插件会自动去重并且仅运行一次。
+
+---
+
 ## Migration notes from v8
 
 If you are upgrading from v8, note that the v9 does not include breaking changes. But here are the key changes:

package/docs/zh/roadmap.md

@@ -29,6 +29,12 @@ Intlayer 是一个内容管理和国际化解决方案，旨在简化您在应
 
 ---
 
+## 目录
+
+<TOC/>
+
+---
+
 ## 当前功能
 
 ### 1. 内容声明

package/docs/zh/vs_code_extension.md

@@ -119,13 +119,6 @@ Intlayer 建议将您的 AI API 密钥，以及 Intlayer 客户端 ID 和密钥
 - **非破坏性**：不会覆盖已有的 `process.env` 值。
 - **作用域**：文件从配置的基础目录解析（默认为工作区根目录）。
 
-#### 选择活动环境
-
-- **命令面板**：打开命令面板并运行 `Intlayer: Select Environment`，然后选择环境（例如，`development`、`staging`、`production`）。扩展将尝试加载上述优先级列表中第一个可用的文件，并显示类似“已从 `.env.<env>.local` 加载环境”的通知。
-- **设置**：进入 `设置 → 扩展 → Intlayer`，并设置：
-  - **环境**：用于解析 `.env.<env>*` 文件的环境名称。
-  - （可选）**环境文件**：显式指定一个 `.env` 文件路径。提供后，该路径优先于推断的列表。
-
 #### Monorepos 和自定义目录
 
 - **命令面板**：打开命令面板并运行 `Intlayer: Select Environment`，然后选择环境（例如，`development`、`staging`、`production`）。扩展将尝试加载上述优先列表中的第一个可用文件，并显示类似“已从 `.env.<env>.local` 加载环境”的通知。

package/docs/zh-TW/intlayer_with_angular_21.md

@@ -85,28 +85,44 @@ author: aymericzip
 
 使用npm安裝必要的套件：
 
+```bash packageManager="npm"
+npx intlayer-cli init --interactive
+```
+
+```bash packageManager="pnpm"
+pnpm dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="yarn"
+yarn dlx intlayer-cli init --interactive
+```
+
+```bash packageManager="bun"
+bunx intlayer-cli init --interactive
+```
+
+> `--interactive` 標誌是可選的。如果您是 AI 代理，請使用 `intlayer-cli init`。
+
+> 此命令將偵測您的環境並安裝所需的套件。例如：
+
 ```bash packageManager="npm"
 npm install intlayer angular-intlayer
 npm install @angular-builders/custom-esbuild --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer angular-intlayer
 pnpm add @angular-builders/custom-esbuild --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer angular-intlayer
 yarn add @angular-builders/custom-esbuild --save-dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer angular-intlayer
 bun add @angular-builders/custom-esbuild --dev
-bun x intlayer init
 ```
 
 - **intlayer**