@intlayer/docs 7.0.4-canary.0 → 7.0.5

package/docs/vi/plugins/sync-json.md

@@ -0,0 +1,244 @@
+---
+createdAt: 2025-03-13
+updatedAt: 2025-10-05
+title: Plugin Đồng bộ JSON
+description: Đồng bộ từ điển Intlayer với các tệp JSON i18n của bên thứ ba (i18next, next-intl, react-intl, vue-i18n và nhiều hơn nữa). Giữ nguyên i18n hiện có của bạn trong khi sử dụng Intlayer để quản lý, dịch và kiểm tra các thông điệp của bạn.
+keywords:
+  - Intlayer
+  - Đồng bộ JSON
+  - i18next
+  - next-intl
+  - react-intl
+  - vue-i18n
+  - next-translate
+  - nuxt-i18n
+  - LinguiJS
+  - Polyglot.js
+  - Solid-i18next
+  - svelte-i18n
+  - i18n
+  - bản dịch
+slugs:
+  - doc
+  - plugin
+  - sync-json
+history:
+  - version: 6.1.6
+    date: 2025-10-05
+    changes: Tài liệu Plugin Đồng bộ JSON ban đầu
+---
+
+# Đồng bộ JSON (cầu nối i18n)
+
+Sử dụng Intlayer như một tiện ích bổ sung cho bộ công cụ i18n hiện có của bạn. Plugin này giữ cho các thông điệp JSON của bạn đồng bộ với từ điển Intlayer để bạn có thể:
+
+- Giữ nguyên i18next, next-intl, react-intl, vue-i18n, next-translate, nuxt-i18n, Solid-i18next, svelte-i18n, v.v.
+- Quản lý và dịch các thông điệp của bạn với Intlayer (CLI, CI, nhà cung cấp, CMS), mà không cần tái cấu trúc ứng dụng của bạn.
+- Phát hành các hướng dẫn và nội dung SEO nhắm mục tiêu từng hệ sinh thái, đồng thời đề xuất Intlayer như lớp quản lý JSON.
+
+Ghi chú và phạm vi hiện tại:
+
+- Việc ngoại hóa sang CMS hoạt động cho cả bản dịch và văn bản cổ điển.
+- Chưa hỗ trợ chèn, số nhiều/ICU, hoặc các tính năng runtime nâng cao của các thư viện khác.
+- Trình chỉnh sửa trực quan chưa được hỗ trợ cho các đầu ra i18n của bên thứ ba.
+
+### Khi nào nên sử dụng plugin này
+
+- Bạn đã sử dụng một thư viện i18n và lưu trữ các thông điệp trong các tệp JSON.
+- Bạn muốn hỗ trợ điền bằng AI, kiểm tra trong CI, và vận hành nội dung mà không thay đổi runtime kết xuất của bạn.
+
+## Cài đặt
+
+```bash
+pnpm add -D @intlayer/sync-json-plugin
+# hoặc
+npm i -D @intlayer/sync-json-plugin
+```
+
+## Bắt đầu nhanh
+
+Thêm plugin vào `intlayer.config.ts` của bạn và trỏ nó đến cấu trúc JSON hiện có của bạn.
+
+```ts fileName="intlayer.config.ts"
+import { defineConfig, Locales } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default defineConfig({
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // Giữ cho các tệp JSON hiện tại của bạn đồng bộ với từ điển Intlayer
+  plugins: [
+    syncJSON({
+      // Bố cục theo từng locale, từng namespace (ví dụ: next-intl, i18next với namespaces)
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+    }),
+  ],
+});
+```
+
+Phương án thay thế: một tệp duy nhất cho mỗi locale (thường dùng với i18next/react-intl):
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale }) => `./locales/${locale}.json`,
+  }),
+];
+```
+
+### Cách hoạt động
+
+- Đọc: plugin phát hiện các tệp JSON từ builder `source` của bạn và tải chúng như các từ điển Intlayer.
+- Ghi: sau khi build và điền, plugin ghi các tệp JSON đã được bản địa hóa trở lại cùng đường dẫn (với một dòng mới cuối cùng để tránh lỗi định dạng).
+- Tự động điền: plugin khai báo một đường dẫn `autoFill` cho mỗi từ điển. Chạy lệnh `intlayer fill` sẽ chỉ cập nhật các bản dịch còn thiếu trong các tệp JSON của bạn theo mặc định.
+
+API:
+
+```ts
+syncJSON({
+  source: ({ key, locale }) => string, // bắt buộc
+  location?: string, // nhãn tùy chọn, mặc định: "plugin"
+  priority?: number, // ưu tiên tùy chọn để giải quyết xung đột, mặc định: 0
+});
+```
+
+## Nhiều nguồn JSON và ưu tiên
+
+Bạn có thể thêm nhiều plugin `syncJSON` để đồng bộ các nguồn JSON khác nhau. Điều này hữu ích khi bạn có nhiều thư viện i18n hoặc các cấu trúc JSON khác nhau trong dự án của mình.
+
+### Hệ thống ưu tiên
+
+Khi nhiều plugin cùng nhắm tới cùng một khóa từ điển, tham số `priority` sẽ quyết định plugin nào được ưu tiên:
+
+- Số ưu tiên cao hơn thắng số ưu tiên thấp hơn
+- Ưu tiên mặc định của các tệp `.content` là `0`
+- Ưu tiên mặc định của các tệp nội dung plugin là `-1`
+- Các plugin có cùng mức ưu tiên sẽ được xử lý theo thứ tự xuất hiện trong cấu hình
+
+```ts fileName="intlayer.config.ts"
+import { defineConfig, Locales } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default defineConfig({
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // Nguồn JSON chính (ưu tiên cao nhất)
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      location: "main-translations",
+      priority: 10,
+    }),
+
+    // Nguồn JSON dự phòng (ưu tiên thấp hơn)
+    syncJSON({
+      source: ({ locale }) => `./fallback-locales/${locale}.json`,
+      location: "fallback-translations",
+      priority: 5,
+    }),
+
+    // Nguồn JSON kế thừa (ưu tiên thấp nhất)
+    syncJSON({
+      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.json`,
+      location: "legacy-translations",
+      priority: 1,
+    }),
+  ],
+});
+```
+
+### Giải quyết xung đột
+
+Khi cùng một khóa dịch tồn tại trong nhiều nguồn JSON:
+
+1. Plugin có mức ưu tiên cao nhất sẽ quyết định giá trị cuối cùng
+2. Các nguồn có mức ưu tiên thấp hơn được sử dụng làm phương án dự phòng cho các khóa bị thiếu
+3. Điều này cho phép bạn duy trì các bản dịch kế thừa trong khi dần dần chuyển sang các cấu trúc mới
+
+## Tích hợp
+
+Dưới đây là các ánh xạ phổ biến. Giữ nguyên runtime của bạn; chỉ cần thêm plugin.
+
+### i18next
+
+Bố cục tệp điển hình: `./public/locales/{locale}/{namespace}.json` hoặc `./locales/{locale}/{namespace}.json`.
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`, // nguồn tệp JSON đồng bộ theo khóa và ngôn ngữ
+    }),
+  ],
+};
+```
+
+### next-intl
+
+Các thông điệp JSON theo từng ngôn ngữ (thường là `./messages/{locale}.json`) hoặc theo từng namespace.
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale, key }) => `./messages/${locale}/${key}.json`, // nguồn tệp JSON đồng bộ theo ngôn ngữ và khóa
+  }),
+];
+```
+
+Xem thêm: `docs/vi/intlayer_with_next-intl.md`.
+
+### react-intl
+
+Thông thường có một tệp JSON duy nhất cho mỗi ngôn ngữ:
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale }) => `./locales/${locale}.json`, // nguồn tệp JSON đồng bộ theo ngôn ngữ
+  }),
+];
+```
+
+### vue-i18n
+
+Có thể là một tệp duy nhất cho mỗi ngôn ngữ hoặc theo từng namespace:
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`, // nguồn tệp JSON đồng bộ theo khóa và ngôn ngữ
+  }),
+];
+```
+
+## CLI
+
+Các tệp JSON được đồng bộ sẽ được coi như các tệp `.content` khác. Điều đó có nghĩa là tất cả các lệnh intlayer sẽ có sẵn cho các tệp JSON được đồng bộ. Bao gồm:
+
+- `intlayer content test` để kiểm tra xem có bản dịch nào bị thiếu không
+- `intlayer content list` để liệt kê các tệp JSON được đồng bộ
+- `intlayer content fill` để điền các bản dịch bị thiếu
+- `intlayer content push` để đẩy các tệp JSON được đồng bộ lên
+- `intlayer content pull` để kéo các tệp JSON được đồng bộ về
+
+Xem [Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/intlayer_cli.md) để biết thêm chi tiết.
+
+## Hạn chế (hiện tại)
+
+- Không hỗ trợ chèn hoặc số nhiều/ICU khi nhắm mục tiêu các thư viện bên thứ ba.
+- Trình chỉnh sửa trực quan chưa có sẵn cho các runtime không phải Intlayer.
+- Chỉ đồng bộ JSON; không hỗ trợ các định dạng danh mục không phải JSON.
+
+## Tại sao điều này quan trọng
+
+- Chúng ta có thể đề xuất các giải pháp i18n đã được thiết lập và định vị Intlayer như một tiện ích bổ sung.
+- Chúng ta tận dụng SEO/từ khóa của họ với các hướng dẫn kết thúc bằng việc gợi ý sử dụng Intlayer để quản lý JSON.
+- Mở rộng đối tượng người dùng từ “dự án mới” sang “bất kỳ nhóm nào đã sử dụng i18n”.

package/docs/zh/plugins/sync-json.md

@@ -0,0 +1,244 @@
+---
+createdAt: 2025-03-13
+updatedAt: 2025-10-05
+title: 同步 JSON 插件
+description: 将 Intlayer 字典与第三方 i18n JSON 文件（如 i18next、next-intl、react-intl、vue-i18n 等）同步。保持您现有的 i18n，同时使用 Intlayer 管理、翻译和测试您的消息。
+keywords:
+  - Intlayer
+  - 同步 JSON
+  - i18next
+  - next-intl
+  - react-intl
+  - vue-i18n
+  - next-translate
+  - nuxt-i18n
+  - LinguiJS
+  - Polyglot.js
+  - Solid-i18next
+  - svelte-i18n
+  - i18n
+  - 翻译
+slugs:
+  - doc
+  - plugin
+  - sync-json
+history:
+  - version: 6.1.6
+    date: 2025-10-05
+    changes: 初始同步 JSON 插件文档
+---
+
+## 同步 JSON（i18n 桥接）
+
+将 Intlayer 作为您现有 i18n 体系的附加组件使用。此插件可使您的 JSON 消息与 Intlayer 字典保持同步，从而您可以：
+
+- 继续使用 i18next、next-intl、react-intl、vue-i18n、next-translate、nuxt-i18n、Solid-i18next、svelte-i18n 等。
+- 使用 Intlayer（CLI、CI、提供者、CMS）管理和翻译您的消息，而无需重构您的应用程序。
+- 发布针对各生态系统的教程和 SEO 内容，同时推荐 Intlayer 作为 JSON 管理层。
+
+注意事项及当前范围：
+
+- 外部化到 CMS 适用于翻译和经典文本。
+- 目前尚不支持插入、复数/ICU 或其他库的高级运行时功能。
+- 视觉编辑器尚不支持第三方 i18n 输出。
+
+### 何时使用此插件
+
+- 您已经使用了一个 i18n 库并将消息存储在 JSON 文件中。
+- 您希望在不更改渲染运行时的情况下，实现 AI 辅助填充、CI 测试和内容运营。
+
+## 安装
+
+```bash
+pnpm add -D @intlayer/sync-json-plugin
+# 或者
+npm i -D @intlayer/sync-json-plugin
+```
+
+## 快速开始
+
+将插件添加到您的 `intlayer.config.ts` 中，并指向您现有的 JSON 结构。
+
+```ts fileName="intlayer.config.ts"
+import { defineConfig, Locales } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default defineConfig({
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  // 保持您当前的 JSON 文件与 Intlayer 字典同步
+  plugins: [
+    syncJSON({
+      // 每个语言环境，每个命名空间的布局（例如，next-intl，带命名空间的 i18next）
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+    }),
+  ],
+});
+```
+
+替代方案：每个语言环境一个文件（常见于 i18next/react-intl 设置）：
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale }) => `./locales/${locale}.json`,
+  }),
+];
+```
+
+### 工作原理
+
+- 读取：插件从您的 `source` 构建器发现 JSON 文件，并将其加载为 Intlayer 字典。
+- 写入：在构建和填充之后，它将本地化的 JSON 写回相同路径（末尾带有换行符以避免格式问题）。
+- 自动填充：该插件为每个词典声明一个 `autoFill` 路径。运行 `intlayer fill` 默认只会更新 JSON 文件中缺失的翻译。
+
+API：
+
+```ts
+syncJSON({
+  source: ({ key, locale }) => string, // 必填
+  location?: string, // 可选标签，默认值："plugin"
+  priority?: number, // 可选优先级，用于冲突解决，默认值：0
+});
+```
+
+## 多个 JSON 源和优先级
+
+你可以添加多个 `syncJSON` 插件来同步不同的 JSON 源。当你的项目中使用多个 i18n 库或有不同的 JSON 结构时，这非常有用。
+
+### 优先级系统
+
+当多个插件针对同一个词典键时，`priority` 参数决定哪个插件优先：
+
+- 数值越高的优先级胜出
+- `.content` 文件的默认优先级是 `0`
+- 插件内容文件的默认优先级是 `-1`
+- 具有相同优先级的插件按它们在配置中出现的顺序处理
+
+```ts fileName="intlayer.config.ts"
+import { defineConfig, Locales } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default defineConfig({
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+
+  plugins: [
+    // 主要 JSON 源（最高优先级）
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+      location: "main-translations",
+      priority: 10,
+    }),
+
+    // 备用 JSON 源（较低优先级）
+    syncJSON({
+      source: ({ locale }) => `./fallback-locales/${locale}.json`,
+      location: "fallback-translations",
+      priority: 5,
+    }),
+
+    // 旧版 JSON 源（最低优先级）
+    syncJSON({
+      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.json`,
+      location: "legacy-translations",
+      priority: 1,
+    }),
+  ],
+});
+```
+
+### 冲突解决
+
+当相同的翻译键存在于多个 JSON 源中时：
+
+1. 优先级最高的插件决定最终的值
+2. 优先级较低的源作为缺失键的备用
+3. 这允许您在逐步迁移到新结构的同时，保持旧版翻译
+
+## 集成
+
+以下是常见的映射。保持您的运行时不变；只需添加插件。
+
+### i18next
+
+典型的文件布局：`./public/locales/{locale}/{namespace}.json` 或 `./locales/{locale}/{namespace}.json`。
+
+```ts fileName="intlayer.config.ts"
+import { syncJSON } from "@intlayer/sync-json-plugin";
+
+export default {
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+    }),
+  ],
+};
+```
+
+### next-intl
+
+每个语言环境的 JSON 消息（通常是 `./messages/{locale}.json`）或按命名空间划分。
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,
+  }),
+];
+```
+
+另见：`docs/zh/intlayer_with_next-intl.md`。
+
+### react-intl
+
+每个语言环境单个 JSON 文件较为常见：
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ locale }) => `./locales/${locale}.json`,
+  }),
+];
+```
+
+### vue-i18n
+
+每个语言环境使用单个文件或每个命名空间使用单个文件：
+
+```ts fileName="intlayer.config.ts"
+plugins: [
+  syncJSON({
+    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,
+  }),
+];
+```
+
+## CLI
+
+同步的 JSON 文件将被视为其他 `.content` 文件。这意味着所有 intlayer 命令都可以用于同步的 JSON 文件，包括：
+
+- `intlayer content test` 用于测试是否有缺失的翻译
+- `intlayer content list` 用于列出同步的 JSON 文件
+- `intlayer content fill` 用于填充缺失的翻译
+- `intlayer content push` 用于推送同步的 JSON 文件
+- `intlayer content pull` 用于拉取同步的 JSON 文件
+
+请参阅[Intlayer CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_cli.md)了解更多详情。
+
+## 限制（当前）
+
+- 针对第三方库时不支持插入或复数/ICU。
+- 非 Intlayer 运行时尚不支持可视化编辑器。
+- 仅支持 JSON 同步；不支持非 JSON 目录格式。
+
+## 重要性
+
+- 我们可以推荐成熟的 i18n 解决方案，并将 Intlayer 定位为附加组件。
+- 通过教程利用它们的 SEO/关键词，教程最后建议使用 Intlayer 来管理 JSON。
+- 将可覆盖的用户群从“新项目”扩展到“任何已经使用 i18n 的团队”。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/docs",
-  "version": "7.0.4-canary.0",
+  "version": "7.0.5",
   "private": false,
   "description": "Intlayer documentation",
   "keywords": [
@@ -69,17 +69,17 @@
     "watch": "webpack --config ./webpack.config.ts --watch"
   },
   "dependencies": {
-    "@intlayer/config": "workspace:*",
-    "@intlayer/core": "workspace:*",
-    "@intlayer/types": "workspace:*"
+    "@intlayer/config": "7.0.5",
+    "@intlayer/core": "7.0.5",
+    "@intlayer/types": "7.0.5"
   },
   "devDependencies": {
-    "@intlayer/api": "workspace:*",
-    "@intlayer/cli": "workspace:*",
+    "@intlayer/api": "7.0.5",
+    "@intlayer/cli": "7.0.5",
     "@types/node": "24.9.2",
-    "@utils/ts-config": "workspace:*",
-    "@utils/ts-config-types": "workspace:*",
-    "@utils/tsdown-config": "workspace:*",
+    "@utils/ts-config": "7.0.5",
+    "@utils/ts-config-types": "7.0.5",
+    "@utils/tsdown-config": "7.0.5",
     "fast-glob": "3.3.3",
     "rimraf": "6.0.1",
     "tsdown": "0.15.11",
@@ -87,11 +87,11 @@
     "vitest": "4.0.5"
   },
   "peerDependencies": {
-    "@intlayer/api": "workspace:*",
-    "@intlayer/cli": "workspace:*",
-    "@intlayer/config": "workspace:*",
-    "@intlayer/core": "workspace:*",
-    "@intlayer/types": "workspace:*"
+    "@intlayer/api": "7.0.5",
+    "@intlayer/cli": "7.0.5",
+    "@intlayer/config": "7.0.5",
+    "@intlayer/core": "7.0.5",
+    "@intlayer/types": "7.0.5"
   },
   "engines": {
     "node": ">=14.18"