@intlayer/docs 7.3.15 → 7.5.0-canary.0

package/docs/zh/intlayer_with_next-i18next.md

@@ -581,6 +581,7 @@ const config: IntlayerConfig = {
   },
   plugins: [
     syncJSON({
+      format: "i18next",
       source: ({ locale }) => `./locales/${locale}.json`,
     }),
   ],

package/docs/zh/intlayer_with_next-intl.md

@@ -421,6 +421,7 @@ const config: IntlayerConfig = {
   plugins: [
     // 保持每个命名空间的文件夹结构与 Intlayer 同步
     syncJSON({
+      format: "icu",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
     }),
   ],

package/docs/zh/intlayer_with_tanstack.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-09-09
-updatedAt: 2025-09-09
+updatedAt: 2025-12-11
 title: 如何翻译您的Tanstack Start应用 – i18n指南 2025
 description: 学习如何使用 Intlayer 为您的 Tanstack Start 应用添加国际化 (i18n)。按照本综合指南，使您的应用支持多语言并具备基于区域设置的路由功能。
 keywords:
@@ -19,9 +19,12 @@ slugs:
 applicationTemplate: https://github.com/aymericzip/intlayer-tanstack-start-template
 youtubeVideo: https://www.youtube.com/watch?v=_XTdKVWaeqg
 history:
+  - version: 7.4.0
+    date: 2025-12-11
+    changes: 引入 validatePrefix 并添加步骤 14: 处理带有本地化路由的 404 页面。
   - version: 7.3.9
     date: 2025-12-05
-    changes: Add step 13: Retrieve the locale in your server actions (Optional)
+    changes: 添加步骤 13: 在您的 server actions 中获取 locale (可选)
   - version: 5.8.1
     date: 2025-09-09
     changes: 为 Tanstack Start 添加支持
@@ -591,7 +594,123 @@ export const getLocaleServer = createServerFn().handler(async () => {
 
 ---
 
-### 第14步：配置 TypeScript（可选）
+### 第14步：管理未找到的页面（可选）
+
+当用户访问不存在的页面时，您可以显示自定义的未找到页面，并且区域设置前缀可能会影响未找到页面的触发方式。
+
+#### 了解 TanStack Router 使用区域设置前缀的 404 处理
+
+在 TanStack Router 中，使用本地化路由处理 404 页面需要采用多层方法：
+
+1. **专用 404 路由**：用于显示 404 UI 的特定路由
+2. **路由级验证**：验证区域设置前缀并将无效的前缀重定向到 404
+3. **捕获所有路由**：捕获区域设置段内任何不匹配的路径
+
+```tsx fileName="src/routes/{-$locale}/404.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+
+// 这将创建一个专用的 /[locale]/404 路由
+// 它既作为直接路由使用，也可以在其他文件中作为组件导入
+export const Route = createFileRoute("/{-$locale}/404")({
+  component: NotFoundComponent,
+});
+
+// 单独导出，以便可以在 notFoundComponent 和 catch-all 路由中重用
+export function NotFoundComponent() {
+  return (
+    <div>
+      <h1>404</h1>
+    </div>
+  );
+}
+```
+
+```tsx fileName="src/routes/{-$locale}/route.tsx"
+import { createFileRoute, Outlet, redirect } from "@tanstack/react-router";
+import { validatePrefix } from "intlayer";
+import { IntlayerProvider, useLocale } from "react-intlayer";
+
+import { LocaleSwitcher } from "@/components/locale-switcher";
+import { NotFoundComponent } from "./404";
+
+export const Route = createFileRoute("/{-$locale}")({
+  // beforeLoad 在路由渲染之前运行（在服务器和客户端上）
+  // 这是验证区域设置前缀的理想位置
+  beforeLoad: ({ params }) => {
+    // 从路由参数获取区域设置（不是从服务器标头，因为 beforeLoad 在客户端和服务器上都会运行）
+    const localeParam = params.locale;
+
+    // validatePrefix 检查区域设置是否根据您的 intlayer 配置有效
+    // 返回: { isValid: boolean, localePrefix: string }
+    // - isValid: 如果前缀匹配配置的区域设置（或当前缀可选时为空），则为 true
+    // - localePrefix: 已验证的前缀或用于重定向的默认区域设置前缀
+    const { isValid, localePrefix } = validatePrefix(localeParam);
+
+    if (isValid) {
+      // 区域设置有效，允许路由正常渲染
+      return;
+    }
+
+    // 无效的区域设置前缀（例如，/xyz/about 其中 "xyz" 不是有效的区域设置）
+    // 重定向到具有有效区域设置前缀的 404 页面
+    // 这确保 404 页面仍然正确本地化
+    throw redirect({
+      to: "/{-$locale}/404",
+      params: { locale: localePrefix },
+    });
+  },
+  component: RouteComponent,
+  // notFoundComponent 在子路由不存在时被调用
+  // 例如，/en/不存在的页面 在 /en 布局内触发此操作
+  notFoundComponent: NotFoundLayout,
+});
+
+function RouteComponent() {
+  const { defaultLocale } = useLocale();
+  const { locale } = Route.useParams();
+
+  return (
+    // 用 IntlayerProvider 包装整个区域设置段
+    // 当区域设置参数为 undefined 时回退到 defaultLocale（可选前缀模式）
+    <IntlayerProvider locale={locale ?? defaultLocale}>
+      <Outlet />
+    </IntlayerProvider>
+  );
+}
+
+// NotFoundLayout 用 IntlayerProvider 包装 404 组件
+// 这确保翻译在 404 页面上仍然有效
+function NotFoundLayout() {
+  const { defaultLocale } = useLocale();
+  const { locale } = Route.useParams();
+
+  return (
+    <IntlayerProvider locale={locale ?? defaultLocale}>
+      <NotFoundComponent />
+      {/* 包含 LocaleSwitcher，以便用户即使在 404 页面上也可以更改语言 */}
+      <LocaleSwitcher />
+    </IntlayerProvider>
+  );
+}
+```
+
+```tsx fileName="src/routes/{-$locale}/$.tsx"
+import { createFileRoute } from "@tanstack/react-router";
+
+import { NotFoundComponent } from "./404";
+
+// $ (splat/catch-all) 路由匹配任何与其他路由不匹配的路径
+// 例如，/en/某个/深度/嵌套/无效/路径
+// 这确保区域设置内所有不匹配的路径都显示 404 页面
+// 没有这个，不匹配的深层路径可能会显示空白页面或错误
+export const Route = createFileRoute("/{-$locale}/$")({
+  component: NotFoundComponent,
+});
+```
+
+---
+
+### 第15步：配置 TypeScript（可选）
 
 Intlayer 使用模块增强来利用 TypeScript 的优势，使您的代码库更健壮。
 

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

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-03-13
-updatedAt: 2025-10-05
+updatedAt: 2025-12-13
 title: 同步 JSON 插件
 description: 将 Intlayer 字典与第三方 i18n JSON 文件（如 i18next、next-intl、react-intl、vue-i18n 等）同步。保持您现有的 i18n，同时使用 Intlayer 管理、翻译和测试您的消息。
 keywords:
@@ -24,12 +24,15 @@ slugs:
   - sync-json
 youtubeVideo: https://www.youtube.com/watch?v=MpGMxniDHNg
 history:
+  - version: 7.5.0
+    date: 2025-12-13
+    changes: 添加 ICU 和 i18next 格式支持
   - version: 6.1.6
     date: 2025-10-05
     changes: 初始同步 JSON 插件文档
 ---
 
-## 同步 JSON（i18n 桥接）
+# 同步 JSON（i18n 桥接）- 支持 ICU / i18next 的同步 JSON
 
 <iframe title="如何保持您的 JSON 翻译与 Intlayer 同步" 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=http://intlayer.org&amp;controls=0&amp;rel=1"/>
 
@@ -105,9 +108,27 @@ syncJSON({
   source: ({ key, locale }) => string, // 必填
   location?: string, // 可选标签，默认值："plugin"
   priority?: number, // 可选优先级，用于冲突解决，默认值：0
+  format?: 'intlayer' | 'icu' | 'i18next', // 可选格式化器，默认值：'intlayer'
 });
 ```
 
+#### `format` ('intlayer' | 'icu' | 'i18next')
+
+指定在同步 JSON 文件时用于字典内容的格式化器。这允许使用与各种 i18n 库兼容的不同消息格式化语法。
+
+- `'intlayer'`: 默认的 Intlayer 格式化器（默认值）。
+- `'icu'`: 使用 ICU 消息格式化（与 react-intl、vue-i18n 等库兼容）。
+- `'i18next'`: 使用 i18next 消息格式化（与 i18next、next-i18next、Solid-i18next 兼容）。
+
+**示例：**
+
+```ts
+syncJSON({
+  source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
+  format: "i18next", // 使用 i18next 格式化以保持兼容性
+}),
+```
+
 ## 多个 JSON 源和优先级
 
 你可以添加多个 `syncJSON` 插件来同步不同的 JSON 源。当你的项目中使用多个 i18n 库或有不同的 JSON 结构时，这非常有用。
@@ -134,6 +155,7 @@ export default defineConfig({
   plugins: [
     // 主要 JSON 源（最高优先级）
     syncJSON({
+      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
       location: "main-translations",
       priority: 10,
@@ -141,6 +163,7 @@ export default defineConfig({
 
     // 备用 JSON 源（较低优先级）
     syncJSON({
+      format: "i18next",
       source: ({ locale }) => `./fallback-locales/${locale}.json`,
       location: "fallback-translations",
       priority: 5,
@@ -148,6 +171,7 @@ export default defineConfig({
 
     // 旧版 JSON 源（最低优先级）
     syncJSON({
+      format: "i18next",
       source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.json`,
       location: "legacy-translations",
       priority: 1,
@@ -178,6 +202,7 @@ import { syncJSON } from "@intlayer/sync-json-plugin";
 export default {
   plugins: [
     syncJSON({
+      format: "i18next",
       source: ({ key, locale }) => `./locales/${locale}/${key}.json`,
     }),
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/docs",
-  "version": "7.3.15",
+  "version": "7.5.0-canary.0",
   "private": false,
   "description": "Intlayer documentation",
   "keywords": [
@@ -73,13 +73,13 @@
     "watch": "webpack --config ./webpack.config.ts --watch"
   },
   "dependencies": {
-    "@intlayer/config": "7.3.15",
-    "@intlayer/core": "7.3.15",
-    "@intlayer/types": "7.3.15"
+    "@intlayer/config": "7.5.0-canary.0",
+    "@intlayer/core": "7.5.0-canary.0",
+    "@intlayer/types": "7.5.0-canary.0"
   },
   "devDependencies": {
-    "@intlayer/api": "7.3.15",
-    "@intlayer/cli": "7.3.15",
+    "@intlayer/api": "7.5.0-canary.0",
+    "@intlayer/cli": "7.5.0-canary.0",
     "@types/node": "24.10.1",
     "@utils/ts-config": "1.0.4",
     "@utils/ts-config-types": "1.0.4",