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

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,63 @@ 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({
+      format: "i18next",
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      priority: 0,
+      format: "i18next",
+    }),
+  ],
+};
+
+export default config;
+```
+
+## `syncJSON` plugin
+
+### Quick start
 
 将插件添加到您的 `intlayer.config.ts` 中，并指向您现有的 JSON 结构。
 
@@ -81,6 +140,7 @@ const config: IntlayerConfig = {
     syncJSON({
       // 每个语言环境，每个命名空间的布局（例如，next-intl，带命名空间的 i18next）
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      format: "icu",
     }),
   ],
 };
@@ -91,14 +151,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 +185,7 @@ syncJSON({
   location?: string, // 可选标签，默认值："plugin"
   priority?: number, // 可选优先级，用于冲突解决，默认值：0
   format?: 'intlayer' | 'icu' | 'i18next', // 可选格式化器，用于 Intlayer 运行时兼容性
+  splitKeys?: boolean, // 可选，将单个文件拆分为每个顶级键一个字典（自动检测）
 });
 ```
 
@@ -136,11 +210,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 +295,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 +441,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-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**

package/docs/zh-TW/packages/intlayer/comparePaths.md

@@ -0,0 +1,173 @@
+---
+createdAt: 2026-06-22
+updatedAt: 2026-06-22
+title: comparePaths 函式文件 | intlayer
+description: 了解如何使用 intlayer 套件中的 comparePaths 函式
+keywords:
+  - comparePaths
+  - normalizePath
+  - 活躍連結
+  - 導覽
+  - Intlayer
+  - intlayer
+  - 國際化
+  - 文件
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - comparePaths
+history:
+  - version: 9.0.0
+    date: 2026-06-22
+    changes: "初始文件"
+author: aymericzip
+---
+
+# 文件: `intlayer` 中的 `comparePaths` 函式
+
+## 描述
+
+`comparePaths` 函式在忽略語言設定（locale）區段、通訊協定/主機名稱、查詢字串、雜湊值和結尾斜線的情況下，比較兩個 URL 或路徑是否相等。這是判斷導覽連結是否指向目前頁面的推薦方法（例如，用於標示目前活動的連結），而無需撰寫自己（容易出錯）的正規化邏輯。
+
+它在內部重複使用了 [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh-TW/packages/intlayer/getPathWithoutLocale.md) 來移除語言設定區段，因此它會遵循您配置的路由模式和語言設定。
+
+該套件還匯出了底層的 [`normalizePath`](#normalizepath) 輔助函式，它會回傳用於比較的、與語言設定無關的正規路徑名稱。
+
+**主要功能：**
+
+- 與語言設定無關的比較（`/zh-TW/about` 與 `/about` 匹配）
+- 適用於絕對 URL 和相對路徑
+- 忽略查詢字串、雜湊值和結尾斜線
+- 容許缺少前導斜線和空值（正規化為 `/`）
+- 輕量級 — 建構在 `getPathWithoutLocale` 之上
+
+---
+
+## 函式簽名
+
+```typescript
+comparePaths(
+  pathname: string,  // 必填
+  href: string,      // 必填
+  locales?: Locales[] // 選填
+): boolean
+
+normalizePath(
+  inputUrl: string,   // 必填
+  locales?: Locales[] // 選填
+): string
+```
+
+---
+
+## 參數
+
+- `pathname: string`
+  - **描述**: 要比較的第一個 URL 字串或路徑名稱（通常是目前路徑）。
+  - **型別**: `string`
+  - **必填**: 是
+
+- `href: string`
+  - **描述**: 要比較的第二個 URL 字串或路徑名稱（通常是導覽連結的 `href`）。
+  - **型別**: `string`
+  - **必填**: 是
+
+- `locales: Locales[]`
+  - **描述**: 支援的語言設定的選填陣列。預設為專案中設定的語言。
+  - **型別**: `Locales[]`
+  - **必填**: 否 (選填)
+
+### 回傳值
+
+- **型別**: `boolean`
+- **描述**: 當兩個輸入都解析為相同的與語言設定無關的路徑時回傳 `true`，否則回傳 `false`。
+
+---
+
+## 範例用法
+
+### 基本用法
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { comparePaths } from "intlayer";
+
+comparePaths("/ru/path", "/path"); // true
+comparePaths("/ru/path/", "/path"); // true
+comparePaths("/ru/path", "/path/"); // true
+comparePaths("/ru/", "/"); // true
+comparePaths("/ru", "/"); // true
+comparePaths("ru/path", "/path"); // true
+comparePaths("", "/"); // true
+comparePaths("/ru", ""); // true
+comparePaths("/ru/path", "/other"); // false
+```
+
+### 絕對和相對 URL
+
+```typescript
+import { comparePaths } from "intlayer";
+
+comparePaths("https://example.com/ru/path", "/path"); // true
+```
+
+### 標示活動的導覽連結
+
+```tsx
+import { comparePaths } from "intlayer";
+import { useLocation } from "react-router";
+
+const NavLink = ({ href, children }) => {
+  const { pathname } = useLocation();
+  const isActive = comparePaths(pathname, href);
+
+  return (
+    <a href={href} aria-current={isActive ? "page" : undefined}>
+      {children}
+    </a>
+  );
+};
+```
+
+---
+
+## normalizePath
+
+`normalizePath` 回傳由 `comparePaths` 使用的、與語言設定無關的正規路徑名稱。它移除了語言設定區段、通訊協定/主機、查詢字串和雜湊，確保單個前導斜線，刪除任何結尾斜線（根目錄除外），對於空值則回退為 `/`。
+
+```typescript codeFormat={["typescript", "esm", "commonjs"]}
+import { normalizePath } from "intlayer";
+
+normalizePath("/ru/path"); // "/path"
+normalizePath("/ru/path/"); // "/path"
+normalizePath("ru/path"); // "/path"
+normalizePath("/ru/"); // "/"
+normalizePath("/ru"); // "/"
+normalizePath(""); // "/"
+normalizePath("https://example.com/ru/path"); // "/path"
+```
+
+---
+
+## 相關函式
+
+- [`getPathWithoutLocale`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh-TW/packages/intlayer/getPathWithoutLocale.md): 從 URL 或路徑中刪除語言設定區段。
+- [`getPrefix`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh-TW/packages/intlayer/getPrefix.md): 取得給定語言設定的 URL 前綴。
+- [`getLocalizedUrl`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh-TW/packages/intlayer/getLocalizedUrl.md): 為特定語言設定生成本地化 URL。
+
+---
+
+## TypeScript
+
+```typescript
+function normalizePath(inputUrl: string, locales?: Locales[]): string;
+
+function comparePaths(
+  pathname: string,
+  href: string,
+  locales?: Locales[]
+): boolean;
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/docs",
-  "version": "9.0.0-canary.2",
+  "version": "9.0.0-canary.4",
   "private": false,
   "description": "Intlayer documentation",
   "keywords": [
@@ -73,14 +73,14 @@
     "watch": "webpack --config ./webpack.config.ts --watch"
   },
   "dependencies": {
-    "@intlayer/config": "9.0.0-canary.2",
-    "@intlayer/core": "9.0.0-canary.2",
-    "@intlayer/types": "9.0.0-canary.2"
+    "@intlayer/config": "9.0.0-canary.4",
+    "@intlayer/core": "9.0.0-canary.4",
+    "@intlayer/types": "9.0.0-canary.4"
   },
   "devDependencies": {
-    "@intlayer/api": "9.0.0-canary.2",
-    "@intlayer/cli": "9.0.0-canary.2",
-    "@types/node": "25.9.3",
+    "@intlayer/api": "9.0.0-canary.4",
+    "@intlayer/cli": "9.0.0-canary.4",
+    "@types/node": "25.9.4",
     "@utils/ts-config": "1.0.4",
     "@utils/ts-config-types": "1.0.4",
     "@utils/tsdown-config": "1.0.4",