@modern-js/main-doc 2.69.5 → 3.0.0-alpha.0

package/docs/zh/guides/advanced-features/international/locale-detection.mdx

@@ -0,0 +1,304 @@
+---
+title: 语言检测
+---
+
+# 语言检测
+
+插件支持多种语言检测方式，可以组合使用以满足不同的业务需求。
+
+## 检测方式
+
+### 1. URL 路径检测（localePathRedirect）
+
+当 `localePathRedirect` 设置为 `true` 时，插件会从 URL 路径中检测语言。
+
+**示例**：
+
+- `/zh/about` → 检测到语言：`zh`
+- `/en/about` → 检测到语言：`en`
+- `/about` → 如果没有语言前缀，会重定向到默认语言路径
+
+**配置**：
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    languages: ['zh', 'en'],
+    fallbackLanguage: 'en',
+  },
+});
+```
+
+**路由配置**（约定式路由）：
+
+使用约定式路由时，需要在 `routes/` 目录下创建 `[lang]` 目录来表示语言参数：
+
+```bash
+routes/
+├── [lang]/
+│   ├── layout.tsx    # 布局组件
+│   ├── page.tsx      # 首页
+│   └── about/
+│       └── page.tsx  # About 页面
+```
+
+**routes/[lang]/layout.tsx**:
+
+```tsx
+import { Outlet } from '@modern-js/runtime/router';
+
+export default function Layout() {
+  return <Outlet />;
+}
+```
+
+**routes/[lang]/page.tsx**:
+
+```tsx
+export default function Home() {
+  return <div>Home</div>;
+}
+```
+
+**routes/[lang]/about/page.tsx**:
+
+```tsx
+export default function About() {
+  return <div>About</div>;
+}
+```
+
+:::info
+
+如果使用自定义路由（`modern.routes.ts`），需要在路由配置中添加 `:lang` 动态参数。约定式路由会自动根据文件结构生成对应的路由。
+
+:::
+
+### 2. i18next 语言检测器
+
+当 `i18nextDetector` 设置为 `true` 时，会启用 i18next 的语言检测器，支持从以下位置检测语言：
+
+- **Cookie**：从 Cookie 中读取语言设置
+- **LocalStorage**：从浏览器 LocalStorage 中读取
+- **查询参数**：从 URL 查询参数中读取（如 `?lng=en`）
+- **请求头**：从 HTTP 请求头中读取（如 `Accept-Language`）
+- **HTML 标签**：从 HTML 标签的 `lang` 属性读取
+- **子域名**：从子域名中读取（如 `en.example.com`）
+
+**配置**：
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    i18nextDetector: true,
+    detection: {
+      order: ['cookie', 'querystring', 'header'],
+      lookupCookie: 'i18next',
+      lookupQuerystring: 'lng',
+      lookupHeader: 'accept-language',
+      caches: ['cookie'],
+    },
+  },
+});
+```
+
+### 3. 自定义检测配置
+
+通过 `detection` 选项可以自定义检测行为：
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    i18nextDetector: true,
+    detection: {
+      // 检测顺序
+      order: ['path', 'cookie', 'querystring', 'header'],
+
+      // Cookie 相关
+      lookupCookie: 'i18next',
+      cookieExpirationDate: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000), // 1年后过期
+      cookieDomain: '.example.com',
+
+      // 查询参数相关
+      lookupQuerystring: 'lng',
+
+      // 请求头相关
+      lookupHeader: 'accept-language',
+
+      // 缓存配置
+      caches: ['cookie', 'localStorage'],
+    },
+  },
+});
+```
+
+## 检测优先级
+
+插件的语言检测遵循以下优先级顺序（从高到低）：
+
+1. **SSR 数据**（最高优先级）：从 `window._SSR_DATA` 中读取服务端渲染时设置的语言，适用于 SSR 和 CSR 项目
+2. **路径检测**：如果 `localePathRedirect` 为 `true`，从 URL 路径中检测语言前缀
+3. **i18next 检测器**：按照 `detection.order` 配置的顺序执行检测（Cookie、LocalStorage、查询参数、请求头等）
+4. **用户配置语言**：使用 `initOptions.lng` 中配置的语言
+5. **回退语言**：使用 `fallbackLanguage` 作为最终回退
+
+:::info
+
+SSR 数据检测优先级最高，这是为了确保客户端能够使用服务端渲染时检测到的语言，避免客户端重新检测导致的语言闪烁问题。
+
+:::
+
+**示例**：
+
+```ts
+// 配置的检测顺序（仅影响 i18next 检测器内部的优先级）
+detection: {
+  order: ['path', 'cookie', 'querystring', 'header'],
+}
+
+// 实际检测流程：
+// 1. 首先检查 SSR 数据（window._SSR_DATA）
+// 2. 然后检查 URL 路径（如果启用 localePathRedirect）
+// 3. 然后按照 order 顺序检查 i18next 检测器：
+//    - Cookie
+//    - 查询参数
+//    - 请求头
+// 4. 然后使用 initOptions.lng（如果配置）
+// 5. 最后使用 fallbackLanguage
+```
+
+## 检测选项说明
+
+### order（检测顺序）
+
+指定 i18next 检测器内部的检测顺序，可选值：
+
+- `path`：从 URL 路径检测（需要 `localePathRedirect` 为 `true`）
+- `querystring`：从查询参数检测（如 `?lng=en`）
+- `cookie`：从 Cookie 检测
+- `localStorage`：从 LocalStorage 检测（仅浏览器环境）
+- `sessionStorage`：从 SessionStorage 检测（仅浏览器环境）
+- `navigator`：从浏览器语言设置检测（仅浏览器环境）
+- `htmlTag`：从 HTML 标签的 `lang` 属性检测（仅浏览器环境）
+- `header`：从 HTTP 请求头检测（如 `Accept-Language`）
+- `subdomain`：从子域名检测（如 `en.example.com`）
+
+**默认检测顺序**：
+
+如果不配置 `order`，插件会使用以下默认顺序：
+
+```ts
+order: [
+  'querystring', // 查询参数优先级最高
+  'cookie', // 然后是 Cookie
+  'localStorage', // 然后是 LocalStorage
+  'header', // 然后是请求头
+  'navigator', // 然后是浏览器语言
+  'htmlTag', // 然后是 HTML 标签
+  'path', // 然后是路径
+  'subdomain', // 最后是子域名
+];
+```
+
+:::warning
+
+`path` 检测需要 `localePathRedirect` 为 `true`，`localStorage`、`sessionStorage`、`navigator`、`htmlTag` 仅在浏览器环境可用。
+
+:::
+
+:::info
+
+注意：`order` 配置只影响 i18next 检测器内部的优先级。实际的检测优先级还包括 SSR 数据和路径检测，它们有更高的优先级（见上面的"检测优先级"章节）。
+
+:::
+
+### caches（缓存方式）
+
+指定检测到的语言应该缓存在哪里，可选值：
+
+- `false`：不缓存
+- `['cookie']`：缓存到 Cookie
+- `['localStorage']`：缓存到 LocalStorage（仅浏览器）
+- `['cookie', 'localStorage']`：同时缓存到 Cookie 和 LocalStorage
+
+### lookupQuerystring、lookupCookie、lookupLocalStorage、lookupSession、lookupHeader
+
+指定从查询参数、Cookie、LocalStorage、SessionStorage 或请求头中读取语言时使用的键名：
+
+- `lookupQuerystring`：默认 `'lng'`，例如 `?lng=en`
+- `lookupCookie`：默认 `'i18next'`
+- `lookupLocalStorage`：默认 `'i18nextLng'`（仅浏览器环境）
+- `lookupSession`：SessionStorage 的键名（仅浏览器环境）
+- `lookupHeader`：默认 `'accept-language'`
+
+### lookupFromPathIndex
+
+指定从 URL 路径的哪个位置开始检测语言（当 `order` 中包含 `'path'` 时）：
+
+- `lookupFromPathIndex`：路径段索引，默认为 `0`（第一个路径段）
+
+**示例**：
+
+```ts
+// URL: /api/v1/en/users
+// 如果 lookupFromPathIndex = 2，则从第三个路径段（'en'）开始检测
+detection: {
+  order: ['path'],
+  lookupFromPathIndex: 2,
+}
+```
+
+### cookieMinutes、cookieExpirationDate
+
+控制 Cookie 的过期时间：
+
+- `cookieMinutes`：Cookie 过期时间（分钟），默认 `525600`（1 年）
+- `cookieExpirationDate`：Cookie 过期日期（Date 对象），优先级高于 `cookieMinutes`
+
+**示例**：
+
+```ts
+detection: {
+  cookieMinutes: 60 * 24 * 7, // 7天后过期
+  // 或
+  cookieExpirationDate: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // 7天后过期
+}
+```
+
+### ignoreRedirectRoutes
+
+指定哪些路由应该忽略自动语言重定向。这对于 API 路由、静态资源等不需要语言前缀的路径非常有用。
+
+**配置方式**：
+
+```ts
+i18nPlugin({
+  localeDetection: {
+    localePathRedirect: true,
+    languages: ['zh', 'en'],
+    fallbackLanguage: 'en',
+    // 字符串数组：支持精确匹配和前缀匹配
+    ignoreRedirectRoutes: ['/api', '/admin', '/static'],
+    // 或使用函数进行更灵活的判断
+    ignoreRedirectRoutes: pathname => {
+      return pathname.startsWith('/api') || pathname.startsWith('/admin');
+    },
+  },
+});
+```
+
+**匹配规则**：
+
+- 字符串数组：支持精确匹配（`'/api'`）和前缀匹配（`'/api'` 会匹配 `/api` 和 `/api/users`）
+- 函数：接收路径名（已去除语言前缀），返回 `true` 表示忽略重定向
+
+**示例**：
+
+```ts
+// 忽略所有 API 路由和静态资源
+ignoreRedirectRoutes: ['/api', '/static', '/assets'];
+
+// 使用函数忽略所有以 /api 开头的路径
+ignoreRedirectRoutes: pathname => pathname.startsWith('/api');
+```

package/docs/zh/guides/advanced-features/international/quick-start.mdx

@@ -0,0 +1,149 @@
+---
+title: 快速开始
+---
+
+# 快速开始
+
+本指南将帮助你快速在 Modern.js 项目中集成国际化功能。
+
+## 安装插件
+
+首先，安装必要的依赖：
+
+import InstallCommand from '@site-docs/components/international/install-command';
+
+<InstallCommand />
+
+## 基础配置
+
+### 在 `modern.config.ts` 中注册插件
+
+```ts
+import { appTools, defineConfig } from '@modern-js/app-tools';
+import { i18nPlugin } from '@modern-js/plugin-i18n';
+
+export default defineConfig({
+  server: {
+    publicDir: './locales', // 必需：指定资源文件目录
+  },
+  plugins: [
+    appTools(),
+    i18nPlugin({
+      localeDetection: {
+        languages: ['zh', 'en'], // 支持的语言列表
+        fallbackLanguage: 'en', // 默认语言
+      },
+      backend: {
+        enabled: true, // 启用后端资源加载
+        // loadPath 默认为 '/locales/{{lng}}/{{ns}}.json'，通常无需修改
+        // 注意：你也可以省略 'enabled'，只需配置 'loadPath' 或 'addPath'，
+        // 或者完全省略 backend 配置，让插件自动检测 locales 目录
+      },
+    }),
+  ],
+});
+```
+
+:::info
+`server.publicDir` 是必需配置，用于指定资源文件的实际存放位置。即使使用默认的 `loadPath` 路径，也需要配置此项。
+
+:::
+
+### 在 `src/modern.runtime.ts` 中配置运行时选项
+
+创建 `src/modern.runtime.ts` 文件并配置 i18n 运行时选项：
+
+```ts
+import { defineRuntimeConfig } from '@modern-js/runtime';
+import i18next from 'i18next';
+
+// 建议创建一个新的 i18next 实例，避免使用全局默认实例
+const i18nInstance = i18next.createInstance();
+
+export default defineRuntimeConfig({
+  i18n: {
+    i18nInstance: i18nInstance,
+    initOptions: {
+      fallbackLng: 'en',
+      supportedLngs: ['zh', 'en'],
+    },
+  },
+});
+```
+
+:::info
+`modern.runtime.ts` 是运行时配置文件，用于配置 i18next 的初始化选项。即使是最基础的配置，也建议创建此文件以确保插件正常工作。
+
+建议使用 `i18next.createInstance()` 创建一个新的实例，而不是直接使用默认导出的 `i18next`，这样可以避免全局状态污染，并确保每个应用都有独立的 i18n 实例。
+
+:::
+
+### 创建语言资源文件
+
+在项目根目录创建 `locales` 文件夹，并按语言组织资源文件：
+
+```
+locales/
+├── en/
+│   └── translation.json
+└── zh/
+    └── translation.json
+```
+
+**locales/en/translation.json**:
+
+```json
+{
+  "hello": "Hello",
+  "world": "World",
+  "welcome": "Welcome to Modern.js"
+}
+```
+
+**locales/zh/translation.json**:
+
+```json
+{
+  "hello": "你好",
+  "world": "世界",
+  "welcome": "欢迎使用 Modern.js"
+}
+```
+
+### 在组件中使用
+
+```tsx
+import { useModernI18n } from '@modern-js/plugin-i18n/runtime';
+import { useTranslation } from 'react-i18next';
+
+function App() {
+  const { language, changeLanguage, supportedLanguages } = useModernI18n();
+  const { t } = useTranslation();
+
+  return (
+    <div>
+      <h1>{t('welcome')}</h1>
+      <p>当前语言: {language}</p>
+      <div>
+        {supportedLanguages.map(lang => (
+          <button
+            key={lang}
+            onClick={() => changeLanguage(lang)}
+            disabled={lang === language}
+          >
+            {lang}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export default App;
+```
+
+## 下一步
+
+- 了解详细的[配置说明](./configuration)
+- 学习[语言检测](./locale-detection)的多种方式
+- 查看[资源加载](./resource-loading)的配置选项