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

package/blog/vi/intlayer_with_react-intl.md

@@ -61,24 +61,40 @@ Hướng dẫn này sẽ chỉ cho bạn cách tận dụng hệ thống khai b
 
 Cài đặt các gói cần thiết:
 
+```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
+```
+
+> cờ `--interactive` là tùy chọn. Sử dụng `intlayer-cli init` nếu bạn là tác nhân AI.
+
+> Lệnh này sẽ phát hiện môi trường của bạn và cài đặt các gói cần thiết. Ví dụ:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Mô tả các gói:**

package/blog/vi/intlayer_with_vue-i18n.md

@@ -63,24 +63,40 @@ Hướng dẫn này sẽ chỉ cho bạn cách tận dụng hệ thống khai b
 
 Cài đặt các gói cần thiết bằng trình quản lý gói bạn ưa thích:
 
+```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
+```
+
+> cờ `--interactive` là tùy chọn. Sử dụng `intlayer-cli init` nếu bạn là tác nhân AI.
+
+> Lệnh này sẽ phát hiện môi trường của bạn và cài đặt các gói cần thiết. Ví dụ:
+
 ```bash packageManager="npm"
 npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
 ```
 
 ```bash packageManager="bun"
 bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
 ```
 
 **Giải thích các gói:**

package/blog/vi/rag_powered_documentation_assistant.md

@@ -317,3 +317,16 @@ Và nếu bạn cũng đang thử nghiệm với RAG, tôi rất muốn nghe cá
 </Step>
 
 </Steps>
+## Kết luận
+
+RAG là một trong những cách đơn giản nhất và mạnh mẽ nhất để làm cho các LLM trở nên thực tế. Bằng cách kết hợp **retrieval + generation**, bạn có thể biến các tài liệu tĩnh thành một **trợ lý thông minh** và cùng lúc đó, thu được một luồng thông tin sản phẩm liên tục.
+
+Đối với tôi, dự án này chứng tỏ rằng RAG không chỉ là một thủ thuật kỹ thuật. Đó là một cách để biến đổi tài liệu thành:
+
+- một hệ thống hỗ trợ tương tác
+- một kênh phản hồi
+- một công cụ chiến lược sản phẩm
+
+👉 [Hãy thử bản demo tại đây](https://intlayer.org/doc/why) 👉 [Xem mẫu mã trên GitHub](https://github.com/aymericzip/smart_doc_RAG)
+
+Và nếu bạn cũng đang thử nghiệm RAG, tôi rất muốn biết cách bạn đang sử dụng nó.

package/blog/zh/intlayer_with_i18next.md

@@ -34,6 +34,10 @@ author: aymericzip
 
 <iframe title="如何使用 Intlayer 自动化您的 i18next JSON 翻译" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/MpGMxniDHNg?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
 
+## 目录
+
+<TOC/>
+
 ## 什么是 Intlayer？
 
 **Intlayer** 是一个创新的开源国际化库，旨在解决传统 i18n 解决方案的不足。它为 JavaScript 应用程序中的内容管理提供了一种现代化的方法。
@@ -57,37 +61,6 @@ author: aymericzip
 
 <TOC/>
 
-## 使用 i18next 设置 Intlayer 的分步指南
-
-### 第一步：安装依赖
-
-安装必要的软件包：
-
-```bash packageManager="npm"
-npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
-```
-
-```bash packageManager="pnpm"
-pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
-```
-
-```bash packageManager="yarn"
-yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
-```
-
-```bash packageManager="bun"
-bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
-```
-
-**软件包说明：**
-
-- **intlayer**：国际化管理、内容声明和构建的核心库
-- **@intlayer/sync-json-plugin**：用于将 Intlayer 内容声明导出为兼容 i18next 的 JSON 格式的插件
-
 ### 第2步：实现 Intlayer 插件以封装 JSON
 
 创建一个 Intlayer 配置文件以定义支持的语言环境：

package/blog/zh/intlayer_with_next-i18next.md

@@ -34,17 +34,6 @@ author: aymericzip
 
 <TOC/>
 
-## 什么是 next-i18next？
-
-**next-i18next** 是 Next.js 应用中最流行的国际化（i18n）框架之一。它构建于强大的 **i18next** 生态系统之上，为管理 Next.js 项目的翻译、本地化和语言切换提供了全面的解决方案。
-
-然而，next-i18next 也存在一些挑战：
-
-- **配置复杂**：设置 next-i18next 需要多个配置文件，并且需要仔细配置服务器端和客户端的 i18n 实例。
-- **翻译文件分散**：翻译文件通常存储在与组件分开的目录中，导致维护一致性更加困难。
-- **手动命名空间管理**：开发者需要手动管理命名空间，并确保翻译资源的正确加载。
-- **类型安全有限**：TypeScript 支持需要额外配置，且不提供翻译的自动类型生成。
-
 ## 什么是 Intlayer？
 
 **Intlayer** 是一个创新的开源国际化库，旨在解决传统 i18n 解决方案的不足。它为 Next.js 应用提供了一种现代化的内容管理方法。
@@ -65,37 +54,6 @@ author: aymericzip
 
 ---
 
-## 使用 next-i18next 设置 Intlayer 的分步指南
-
-### 第一步：安装依赖
-
-使用你喜欢的包管理器安装必要的包：
-
-```bash packageManager="npm"
-npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
-```
-
-```bash packageManager="pnpm"
-pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
-```
-
-```bash packageManager="yarn"
-yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
-```
-
-```bash packageManager="bun"
-bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
-```
-
-**包说明：**
-
-- **intlayer**：内容声明和管理的核心库
-- **@intlayer/sync-json-plugin**：用于将 Intlayer 内容声明同步为 i18next JSON 格式的插件
-
 ### 第2步：实现 Intlayer 插件以封装 JSON
 
 创建一个 Intlayer 配置文件以定义你支持的语言环境：

package/blog/zh/intlayer_with_next-intl.md

@@ -29,6 +29,10 @@ author: aymericzip
 
 <iframe title="如何使用 Intlayer 自动化您的 next-intl JSON 翻译" class="m-auto aspect-16/9 w-full overflow-hidden rounded-lg border-0" allow="autoplay; gyroscope;" loading="lazy" width="1080" height="auto" src="https://www.youtube.com/embed/MpGMxniDHNg?autoplay=0&amp;origin=https://intlayer.org&amp;controls=0&amp;rel=1"/>
 
+# 目录
+
+<TOC/>
+
 ## 什么是 Intlayer？
 
 **Intlayer** 是一个创新的开源国际化库，旨在解决传统 i18n 解决方案的不足。它为 Next.js 应用提供了一种现代化的内容管理方法。
@@ -51,37 +55,6 @@ author: aymericzip
 
 <TOC/>
 
-## 使用 next-intl 设置 Intlayer 的分步指南
-
-### 第一步：安装依赖
-
-安装必要的包：
-
-```bash packageManager="npm"
-npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
-```
-
-```bash packageManager="pnpm"
-pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
-```
-
-```bash packageManager="yarn"
-yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
-```
-
-```bash packageManager="bun"
-bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
-```
-
-**包描述：**
-
-- **intlayer**：国际化管理、内容声明和构建的核心库
-- **@intlayer/sync-json-plugin**：用于将 Intlayer 内容声明导出为 next-intl 兼容 JSON 格式的插件
-
 ### 第2步：实现 Intlayer 插件以封装 JSON
 
 创建一个 Intlayer 配置文件以定义支持的语言环境：

package/blog/zh/intlayer_with_react-i18next.md

@@ -55,37 +55,6 @@ author: aymericzip
 
 <TOC/>
 
-## 使用 Intlayer 配合 react-i18next 的逐步指南
-
-### 第一步：安装依赖
-
-安装所需的包：
-
-```bash packageManager="npm"
-npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
-```
-
-```bash packageManager="pnpm"
-pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
-```
-
-```bash packageManager="yarn"
-yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
-```
-
-```bash packageManager="bun"
-bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
-```
-
-**包描述：**
-
-- **intlayer**：用于国际化管理、内容声明和构建的核心库
-- **@intlayer/sync-json-plugin**：用于将 Intlayer 内容声明导出为兼容 react-i18next 的 JSON 格式的插件
-
 ### 第 2 步：实现 Intlayer 插件以包装 JSON
 
 创建一个 Intlayer 配置文件以定义支持的语言环境：

package/blog/zh/intlayer_with_react-intl.md

@@ -53,37 +53,6 @@ author: aymericzip
 
 本指南将向您展示如何利用 Intlayer 优越的内容声明系统，同时保持与 react-intl 的兼容性。
 
-## 使用 react-intl 设置 Intlayer 的分步指南
-
-### 第一步：安装依赖
-
-安装所需的包：
-
-```bash packageManager="npm"
-npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
-```
-
-```bash packageManager="pnpm"
-pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
-```
-
-```bash packageManager="yarn"
-yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
-```
-
-```bash packageManager="bun"
-bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
-```
-
-**包说明：**
-
-- **intlayer**：用于国际化管理、内容声明和构建的核心库
-  /// **@intlayer/sync-json-plugin**：用于将 Intlayer 内容声明导出为兼容 react-intl 的 JSON 格式的插件
-
 ### 第 2 步：实现 Intlayer 插件以包装 JSON
 
 创建一个 Intlayer 配置文件以定义您支持的语言环境：

package/blog/zh/intlayer_with_vue-i18n.md

@@ -55,37 +55,6 @@ author: aymericzip
 
 ---
 
-## 使用 vue-i18n 设置 Intlayer 的分步指南
-
-### 第一步：安装依赖
-
-使用您喜欢的包管理器安装必要的包：
-
-```bash packageManager="npm"
-npm install intlayer @intlayer/sync-json-plugin --save-dev
-npx intlayer init
-```
-
-```bash packageManager="pnpm"
-pnpm add intlayer @intlayer/sync-json-plugin --save-dev
-pnpm intlayer init
-```
-
-```bash packageManager="yarn"
-yarn add intlayer @intlayer/sync-json-plugin --dev
-yarn intlayer init
-```
-
-```bash packageManager="bun"
-bun add intlayer @intlayer/sync-json-plugin --dev
-bun x intlayer init
-```
-
-**包说明：**
-
-- **intlayer**：内容声明和管理的核心库
-- **@intlayer/sync-json-plugin**：用于将 Intlayer 内容声明同步到 vue-i18n JSON 格式的插件
-
 ### 第2步：实现 Intlayer 插件以封装 JSON
 
 创建一个 Intlayer 配置文件以定义您支持的语言环境：

package/blog/zh/next-i18next_vs_next-intl_vs_intlayer.md

@@ -63,14 +63,6 @@ author: aymericzip
 
 ---
 
-## 并排功能比较（以 Next.js 为重点）
-
-| 功能 | `next-intlayer` (Intlayer) | `next-intl` | `next-i18next` |
-
-> 徽章会自动更新。快照会随时间变化。
-
----
-
 ## 并排功能对比（以 Next.js 为重点）
 
 | 功能                                   | `next-intlayer` (Intlayer)                                                     | `next-intl`                                                  | `next-i18next`                                               |
@@ -212,24 +204,6 @@ Next.js 为你内置了国际化路由支持（例如区域段）。但该功能
 
 ---
 
-## 缺失翻译处理
-
-**next-intl**
-
-- 依赖**运行时回退**（例如显示键名或默认语言）。构建不会失败。
-
-**next-i18next**
-
-- 依赖**运行时回退**（例如显示键名或默认语言）。构建不会失败。
-
-**intlayer**
-
-- **构建时检测**，对缺失的语言或键发出**警告/错误**。
-
-**重要原因：** 在构建时捕获缺口，防止生产环境出现“神秘字符串”，并符合严格的发布门控。
-
----
-
 ## 路由、中间件与 URL 策略
 
 <Columns>
@@ -1186,6 +1160,127 @@ export default robots;
 
 ---
 
+### 本地化路由的中间件
+
+<Tabs defaultTab="next-intl" group='techno'>
+  <Tab label="next-i18next" value="next-i18next">
+
+添加中间件以处理本地化检测和路由：
+
+```ts fileName="src/middleware.ts"
+import { NextResponse, type NextRequest } from "next/server";
+import { defaultLocale, locales } from "@/i18n.config";
+
+const PUBLIC_FILE = /\.[^/]+$/; // 排除带扩展名的文件
+
+export function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl;
+
+  if (
+    pathname.startsWith("/_next") ||
+    pathname.startsWith("/api") ||
+    pathname.startsWith("/static") ||
+    PUBLIC_FILE.test(pathname)
+  ) {
+    return;
+  }
+
+  const hasLocale = locales.some(
+    (l) => pathname === "/" + l || pathname.startsWith("/" + l + "/")
+  );
+  if (!hasLocale) {
+    const locale = defaultLocale;
+    const url = request.nextUrl.clone();
+    url.pathname = "/" + locale + (pathname === "/" ? "" : pathname);
+    return NextResponse.redirect(url);
+  }
+}
+
+export const config = {
+  matcher: [
+    // 匹配所有路径，除了以这些开头的路径和带扩展名的文件
+    "/((?!api|_next|static|.*\\..*).*)",
+  ],
+};
+```
+
+  </Tab>
+  <Tab label="next-intl" value="next-intl">
+
+添加中间件以处理本地化检测和路由：
+
+```ts fileName="src/middleware.ts"
+import createMiddleware from "next-intl/middleware";
+import { locales, defaultLocale } from "@/i18n";
+
+export default createMiddleware({
+  locales: [...locales],
+  defaultLocale,
+  localeDetection: true,
+});
+
+export const config = {
+  // 跳过 API、Next 内部文件和静态资源
+  matcher: ["/((?!api|_next|.*\\..*).*)"],
+};
+```
+
+  </Tab>
+  <Tab label="intlayer" value="intlayer">
+
+Intlayer 通过 `next-intlayer` package 配置提供内置的中间件处理。
+
+```ts fileName="src/middleware.ts"
+import { intlayerProxy } from "next-intlayer/proxy";
+
+export const middleware = intlayerProxy();
+
+// 仅将此中间件应用于 app 目录中的文件
+export const config = {
+  matcher: "/((?!api|_next|static|.*\\..*).*)",
+};
+```
+
+中间件的设置集中在 `intlayer.config.ts` 文件中。
+
+  </Tab>
+</Tabs>
+
+### 设置检查清单和最佳实践
+
+<Tabs defaultTab="next-intl" group='techno'>
+  <Tab label="next-i18next" value="next-i18next">
+
+- 确保在 `src/app/[locale]/layout.tsx` 中的根 `<html>` 上设置了 `lang` 和 `dir`。
+- 在 `src/locales/<locale>/` 下将翻译内容分割为命名空间（例如 `common.json`、`about.json`）。
+- 仅在客户端组件中使用 `useTranslation('<ns>')` 加载所需的命名空间，并通过相同的命名空间范围界定 `I18nProvider`。
+- 尽可能保持页面静态：在页面上导出 `export const dynamic = 'force-static'`；设置 `dynamicParams = false` 并实现 `generateStaticParams`。
+- 使用同步服务器组件嵌套在客户端边界下，通过传递预先计算的字符串或 `t` 函数和 `locale`。
+- 对于 SEO，在元数据中设置 `alternates.languages`，在 `sitemap.ts` 中列出本地化的 URL，并在 `robots.ts` 中禁止重复的本地化路由。
+- 优先使用区域感知的格式化程序（例如 `Intl.NumberFormat(locale)`），如果使用 React < 19，在客户端上对其进行 memoize。
+
+  </Tab>
+  <Tab label="next-intl" value="next-intl">
+
+- **设置 html `lang` 和 `dir`**：在 `src/app/[locale]/layout.tsx` 中，通过 `getLocaleDirection(locale)` 计算 `dir`，并设置 `<html lang={locale} dir={dir}>`。
+- **按命名空间分割消息**：按区域和命名空间组织 JSON（例如 `common.json`、`about.json`）。
+- **最小化客户端负载**：在页面上，仅将所需的命名空间发送到 `NextIntlClientProvider`（例如 `pick(messages, ['common', 'about'])`）。
+- **优先使用静态页面**：导出 `export const dynamic = 'force-static'` 并为所有 `locales` 生成静态参数。
+- **同步服务器组件**：通过传递预先计算的字符串（翻译后的标签、格式化的数字）而不是异步调用或不可序列化的函数，保持服务器组件的同步。
+
+  </Tab>
+  <Tab label="intlayer" value="intlayer">
+
+- **模块化内容**：使用 `.content.{ts|js|json}` 文件将内容字典与组件共同定位。
+- **类型安全**：利用 TypeScript 集成进行编译时内容验证。
+- **构建时优化**：使用 Intlayer 的构建工具进行自动 tree-shaking 和 bundle 优化。
+- **集成工具**：利用内置的路由、SEO 辅助工具和可视化编辑器支持。
+
+  </Tab>
+</Tabs>
+
+---
+
 ## 胜者是…
 
 这并不简单。每个选项都有权衡。以下是我的看法：

package/blog/zh/nextjs-multilingual-seo-comparison.md

@@ -177,36 +177,6 @@ export function abs(locale: string, path: string) {
 }
 ```
 
-```tsx fileName="src/app/[locale]/about/layout.tsx"
-    rules: { userAgent: "*", allow: ["/"], disallow },
-    host: origin,
-    sitemap: `${origin}/sitemap.xml`,
-  };
-}
-```
-
-### **next-i18next**
-
-  </Tab>
-  <Tab label="next-i18next">
-
-```ts fileName="i18n.config.ts"
-export const locales = ["en", "fr"] as const;
-export type Locale = (typeof locales)[number];
-export const defaultLocale: Locale = "en";
-
-/** 除非是默认语言，否则为路径添加语言前缀 */
-export function localizedPath(locale: string, path: string) {
-  return locale === defaultLocale ? path : `/${locale}${path}`;
-}
-
-/** 绝对 URL 辅助函数 */
-const ORIGIN = "https://example.com";
-export function abs(locale: string, path: string) {
-  return `${ORIGIN}${localizedPath(locale, path)}`;
-}
-```
-
 ```tsx fileName="src/app/[locale]/about/layout.tsx"
 import type { Metadata } from "next";
 import { locales, defaultLocale, localizedPath } from "@/i18n.config";