@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.10

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

@@ -14,6 +14,9 @@ slugs:
   - vue-intlayer
   - exports
 history:
+  - version: 10.0.0
+    date: 2026-06-23
+    changes: "添加 usePathname 实用程序"
   - version: 8.0.0
     date: 2026-01-21
     changes: "统一了所有导出的文档"
@@ -52,16 +55,17 @@ import "vue-intlayer";
 import "vue-intlayer";
 ```
 
-| 组合函数               | 说明                                                                             | 相关文档                                                                                                              |
-| ---------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `useIntlayer`          | 基于 `useDictionary`，但注入来自生成声明的经过优化的字典版本。                   | -                                                                                                                     |
-| `useDictionary`        | 处理类似字典的对象（key、content）。它会处理 `t()` 翻译、枚举等。                | -                                                                                                                     |
-| `useDictionaryAsync`   | 与 `useDictionary` 相同，但处理异步字典。                                        | -                                                                                                                     |
-| `useDictionaryDynamic` | 与 `useDictionary` 相同，但处理动态字典。                                        | -                                                                                                                     |
-| `useLocale`            | 返回当前 locale 以及用于设置它的函数。                                           | -                                                                                                                     |
-| `useRewriteURL`        | 客户端 composable，用于管理 URL 重写。如果存在本地化的重写规则，会自动更新 URL。 | [useRewriteURL](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vue-intlayer/useRewriteURL.md) |
-| `useIntl`              | 返回当前 locale 的 Intl 对象。                                                   | -                                                                                                                     |
-| `useLoadDynamic`       | 用于加载动态字典的 composable。                                                  | -                                                                                                                     |
+| 组合函数               | 说明                                                                                                   | 相关文档                                                                                                              |
+| ---------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `useIntlayer`          | 基于 `useDictionary`，但注入来自生成声明的经过优化的字典版本。                                         | -                                                                                                                     |
+| `useDictionary`        | 处理类似字典的对象（key、content）。它会处理 `t()` 翻译、枚举等。                                      | -                                                                                                                     |
+| `useDictionaryAsync`   | 与 `useDictionary` 相同，但处理异步字典。                                                              | -                                                                                                                     |
+| `useDictionaryDynamic` | 与 `useDictionary` 相同，但处理动态字典。                                                              | -                                                                                                                     |
+| `useLocale`            | 返回当前 locale 以及用于设置它的函数。                                                                 | -                                                                                                                     |
+| `usePathname`          | 返回当前路径名（pathname）作为 `ComputedRef<string>`，并已移除 locale 片段。对 `popstate` 具有响应式。 | [usePathname](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vue-intlayer/usePathname.md)     |
+| `useRewriteURL`        | 客户端 composable，用于管理 URL 重写。如果存在本地化的重写规则，会自动更新 URL。                       | [useRewriteURL](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/vue-intlayer/useRewriteURL.md) |
+| `useIntl`              | 返回当前 locale 的 Intl 对象。                                                                         | -                                                                                                                     |
+| `useLoadDynamic`       | 用于加载动态字典的 composable。                                                                        | -                                                                                                                     |
 
 ### 函数
 

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/plugins/sync-json.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-12-13
+updatedAt: 2026-06-21
 title: 同步 JSON 插件
 description: 将 Intlayer 字典与第三方 i18n JSON 文件（如 i18next、next-intl、react-intl、vue-i18n 等）同步。保持您现有的 i18n，同时使用 Intlayer 管理、翻译和测试您的消息。
 keywords:
@@ -24,6 +24,9 @@ slugs:
   - sync-json
 youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
 history:
+  - version: 9.0.0
+    date: 2026-06-21
+    changes: "添加 splitKeys 选项（每个顶级命名空间键一个字典），用于 next-intl / react-intl 单文件布局"
   - version: 7.5.0
     date: 2025-12-13
     changes: "添加 ICU 和 i18next 格式支持"
@@ -62,7 +65,62 @@ pnpm add -D @intlayer/sync-json-plugin
 npm i -D @intlayer/sync-json-plugin
 ```
 
-## 快速开始
+## Plugins
+
+This package provides two plugins:
+
+- `loadJSON`: Load JSON files into Intlayer dictionaries.
+  - This plugin is used to load JSON files from a source and will be loaded into Intlayer dictionaries. It can scan all the codebase and search for specific JSON files.
+    This plugin can be used
+    - if you use an i18n library that impose a specific location for your JSON to be loaded (ex: `next-intl`, `i18next`, `react-intl`, `vue-i18n`, etc.), but you want to place your content declaration where you want in your code base.
+    - It can also be used if you want to fetch your messages from a remote source (ex: a CMS, a API, etc.) and store your messages in JSON files.
+
+  > Under the hood, this plugin will scan all the codebase and search for specific JSON files and load them into Intlayer dictionaries.
+  > Note that this plugin will not write the output and translations back to the JSON files.
+
+- `syncJSON`: Synchronize JSON files with Intlayer dictionaries.
+  - This plugin is used to synchronize JSON files with Intlayer dictionaries. It can scan the given location and load the JSON that match the pattern for specific JSON files. This plugin is useful if you want to get the benefits of Intlayer while using another i18n library.
+
+## Using both plugins
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON, syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Keep your current JSON files in sync with Intlayer dictionaries
+  plugins: [
+    /**
+     * Will load all the JSON files in the src that match the pattern {key}.i18n json
+     */
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      locale: Locales.ENGLISH,
+      priority: 1, // Ensures these JSON files take precedence over files at `./locales/en/${key}.json`
+      format: "intlayer", // Format of the JSON content
+    }),
+    /**
+     * Will load, and write the output and translations back to the JSON files in the locales directory
+     */
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      priority: 0,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
+```
+
+## `syncJSON` plugin
+
+### Quick start
 
 将插件添加到您的 `intlayer.config.ts` 中，并指向您现有的 JSON 结构。
 
@@ -81,6 +139,7 @@ const config: IntlayerConfig = {
     syncJSON({
       // 每个语言环境，每个命名空间的布局（例如，next-intl，带命名空间的 i18next）
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "icu",
     }),
   ],
 };
@@ -91,14 +150,27 @@ export default config;
 替代方案：每个语言环境一个文件（常见于 i18next/react-intl 设置）：
 
 ```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale }) => `./locales/${locale}.json`,
-  }),
-];
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  plugins: [
+    syncJSON({
+      format: "i18next",
+      source: ({ locale }) => `./locales/${locale}.json`,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
 ```
 
-### 工作原理
+#### 工作原理
 
 - 读取：插件从您的 `source` 构建器发现 JSON 文件，并将其加载为 Intlayer 字典。
 - 写入：在构建和填充之后，它将本地化的 JSON 写回相同路径（末尾带有换行符以避免格式问题）。
@@ -112,6 +184,7 @@ syncJSON({
   location?: string, // 可选标签，默认值："plugin"
   priority?: number, // 可选优先级，用于冲突解决，默认值：0
   format?: 'intlayer' | 'icu' | 'i18next', // 可选格式化器，用于 Intlayer 运行时兼容性
+  splitKeys?: boolean, // 可选，将单个文件拆分为每个顶级键一个字典（自动检测）
 });
 ```
 
@@ -136,11 +209,43 @@ syncJSON({
 }),
 ```
 
-## 多个 JSON 源和优先级
+#### `splitKeys` (boolean)
+
+控制单个 JSON 文件（其**第一级键是命名空间**）是否应拆分为每个顶级键一个字典，而不是将整个文件作为一个字典。
+
+这与 `next-intl` 和 `react-intl` 等库的命名空间模型相匹配，其中一个 `messages/{locale}.json` 文件通过其第一级键将多个命名空间分组，每个命名空间独立寻址（例如 `useTranslations('Hero')` 解析为 `Hero` 字典）。
+
+- `undefined` (默认)：**自动检测** — 当 `source` 模式没有 `{key}` 段时（一个文件包含所有命名空间），文件将被拆分；否则（每个键一个文件），文件将保持为单个字典。
+- `true`：始终将每个顶级键拆分为其自己的字典。
+- `false`：从不拆分；整个文件将成为一个字典。
+
+给定一个 `messages/{locale}.json` 文件：
+
+```json fileName="messages/en.json"
+{
+  "Hero": { "title": "Full-stack developer" },
+  "Nav": { "work": "Work", "about": "About" },
+  "About": { "lead": "I build apps end to end." }
+}
+```
+
+```ts fileName="intlayer.config.ts"
+syncJSON({
+  format: "icu",
+  source: ({ locale }) => `./messages/${locale}.json`,
+  // splitKeys: true, // 隐含，因为模式没有 `{key}` 段
+}),
+```
+
+这将生成三个字典 — `Hero`、`Nav` 和 `About` — 因此 `useTranslations('Hero')` (next-intl) 可以正确解析。在写回时，所有命名空间将重新组装到同一个按语言环境的文件中。
+
+> 当您在 `source` 中保留显式的 `{key}` 段时（例如 `./locales/${locale}/${key}.json`），每个文件已经是一个命名空间，因此默认禁用拆分。
+
+### 多个 JSON 源和优先级
 
 你可以添加多个 `syncJSON` 插件来同步不同的 JSON 源。当你的项目中使用多个 i18n 库或有不同的 JSON 结构时，这非常有用。
 
-### 优先级系统
+#### 优先级系统
 
 当多个插件针对同一个词典键时，`priority` 参数决定哪个插件优先：
 
@@ -189,73 +294,140 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-### 冲突解决
+## Load JSON plugin
 
-当相同的翻译键存在于多个 JSON 源中时：
+### Quick start
 
-1. 优先级最高的插件决定最终的值
-2. 优先级较低的源作为缺失键的备用
-3. 这允许您在逐步迁移到新结构的同时，保持旧版翻译
+将插件添加到您的 `intlayer.config.ts` 以将现有 JSON 文件作为 Intlayer 字典导入。此插件是只读的（不写入磁盘）：
 
-## 集成
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
 
-以下是常见的映射。保持您的运行时不变；只需添加插件。
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // Ingest JSON messages located anywhere in your source tree
+    loadJSON({
+      source: ({ key }) => `./src/**/${key}.i18n.json`,
+      // Load a single locale per plugin instance (defaults to the config defaultLocale)
+      locale: Locales.ENGLISH,
+      priority: 0,
+    }),
+  ],
+};
 
-### i18next
+export default config;
+```
 
-典型的文件布局：`./public/locales/{locale}/{namespace}.json` 或 `./locales/{locale}/{namespace}.json`。
+替代方案：按语言环境布局，仍然是只读的（只加载选定的语言环境）：
 
 ```ts fileName="intlayer.config.ts"
-import { syncJSON } from "@intlayer/sync-json-plugin";
+import { Locales, type IntlayerConfig } from "intlayer";
+import { loadJSON } from "@intlayer/sync-json-plugin";
 
-export default {
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
   plugins: [
-    syncJSON({
-      format: "i18next",
+    loadJSON({
+      // Only files for Locales.FRENCH will be loaded from this pattern
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      locale: Locales.FRENCH,
     }),
   ],
 };
+
+export default config;
 ```
 
-### next-intl
+### How it works
 
-每个语言环境的 JSON 消息（通常是 `./messages/{locale}.json`）或按命名空间划分。
+- 发现：从您的 `source` 构建器构建一个 glob 并收集匹配的 JSON 文件。
+- 导入：将每个 JSON 文件作为 Intlayer 字典加载，并使用提供的 `locale`。
+- 只读：不写入或格式化输出文件；如果您需要往返同步，请使用 `syncJSON`。
+- 自动填充就绪：定义一个 `fill` 模式，以便 `intlayer content fill` 可以在您选择时填充缺失的键。
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,
-  }),
-];
+### API
+
+```ts
+loadJSON({
+  // Build paths to your JSON. `locale` is optional if your structure has no locale segment
+  source: ({ key, locale }) => string,
+
+  // Target locale for the dictionaries loaded by this plugin instance
+  // Defaults to configuration.internationalization.defaultLocale
+  locale?: Locale,
+
+  // Optional label to identify the source
+  location?: string, // default: "plugin"
+
+  // Priority used for conflict resolution against other sources
+  priority?: number, // default: 0
+
+  // Optional formatter for the JSON content
+  format?: 'intlayer' | 'icu' | 'i18next', // default: 'intlayer'
+
+  // Split a single file into one dictionary per top-level key (auto-detected)
+  splitKeys?: boolean,
+});
 ```
 
-另见：`docs/zh/intlayer_with_next-intl.md`。
+#### `format` ('intlayer' | 'icu' | 'i18next')
 
-### react-intl
+指定在加载 JSON 文件时用于字典内容的格式化器。这允许使用与各种 i18n 库兼容的不同消息格式化语法。
 
-每个语言环境单个 JSON 文件较为常见：
+- `'intlayer'`：默认的 Intlayer 格式化器（默认值）。
+- `'icu'`：使用 ICU 消息格式化（与 react-intl、vue-i18n 等库兼容）。
+- `'i18next'`：使用 i18next 消息格式化（与 i18next、next-i18next、Solid-i18next 兼容）。
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ locale }) => `./locales/${locale}.json`,
-  }),
-];
+**示例：**
+
+```ts
+loadJSON({
+  source: ({ key }) => `./src/**/${key}.i18n.json`,
+  locale: Locales.ENGLISH,
+  format: "icu", // 使用 ICU 格式化以保持兼容性
+}),
 ```
 
-### vue-i18n
+#### `splitKeys` (boolean)
 
-每个语言环境使用单个文件或每个命名空间使用单个文件：
+与 [`syncJSON`](#splitkeys-boolean) 中的行为相同：当单个 JSON 文件通过其第一级键将多个命名空间分组时，每个顶级键都将成为其自己的字典。
 
-```ts fileName="intlayer.config.ts"
-plugins: [
-  syncJSON({
-    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,
-  }),
-];
+- `undefined` (默认)：**自动检测** — 当 `source` 模式没有 `{key}` 段时拆分，否则为单个字典。
+- `true` / `false`：强制或禁用拆分。
+
+```ts
+loadJSON({
+  source: ({ locale }) => `./messages/${locale}.json`,
+  format: "icu",
+  // splitKeys 自动启用：`Hero`、`Nav`、`About` 等每个都成为一个字典
+}),
 ```
 
+### Behavior and conventions
+
+- 如果您的 `source` 掩码包含语言环境占位符，则只导入所选 `locale` 的文件。
+- 如果您的掩码中没有 `{key}` 段，则文件的每个顶级键默认会成为其自己的字典（请参阅 [`splitKeys`](#splitkeys-boolean)）。将 `splitKeys: false` 设置为将整个文件加载为单个 `index` 字典。
+- 键通过替换 `source` 构建器中的 `{key}` 占位符从文件路径派生。
+- 插件只使用发现的文件，不制造缺失的语言环境或键。
+- `fill` 路径从您的 `source` 推断，并用于在您选择时通过 CLI 更新缺失值。
+
+## Conflict resolution
+
+当相同的翻译键存在于多个 JSON 源中时：
+
+1. 优先级最高的插件决定最终的值
+2. 优先级较低的源作为缺失键的备用
+3. 这允许您在逐步迁移到新结构的同时，保持旧版翻译
+
 ## CLI
 
 同步的 JSON 文件将被视为其他 `.content` 文件。这意味着所有 intlayer 命令都可以用于同步的 JSON 文件，包括：
@@ -268,13 +440,13 @@ plugins: [
 
 请参阅[Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md)了解更多详情。
 
-## 限制（当前）
+## Limitations (current)
 
 - 针对第三方库时不支持插入或复数/ICU。
 - 非 Intlayer 运行时尚不支持可视化编辑器。
 - 仅支持 JSON 同步；不支持非 JSON 目录格式。
 
-## 重要性
+## Why this matters
 
 - 我们可以推荐成熟的 i18n 解决方案，并将 Intlayer 定位为附加组件。
 - 通过教程利用它们的 SEO/关键词，教程最后建议使用 Intlayer 来管理 JSON。

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)