@intlayer/docs 8.0.0 → 8.0.1-canary.0

package/docs/zh/packages/adonis-intlayer/exports.md

@@ -0,0 +1,50 @@
+---
+createdAt: 2026-01-30
+updatedAt: 2026-01-30
+title: adonis-intlayer 包文档
+description: 用于 Intlayer 的 AdonisJS 中间件，提供翻译函数和语言区域检测。
+keywords:
+  - adonis-intlayer
+  - adonisjs
+  - middleware
+  - 国际化
+  - i18n
+slugs:
+  - doc
+  - packages
+  - adonis-intlayer
+  - exports
+history:
+  - version: 8.0.0
+    date: 2026-01-30
+    changes: 初始文档
+---
+
+# adonis-intlayer 包
+
+`adonis-intlayer` 包为 AdonisJS 应用程序提供了一个处理国际化的中间件。它检测用户的语言区域并提供翻译函数。
+
+## 安装
+
+```bash
+npm install adonis-intlayer
+```
+
+## 导出
+
+### 中间件
+
+该包提供了一个 AdonisJS 中间件来处理国际化。
+
+| 函数                 | 描述                                                                                                                                                                                         | 相关文档                                                                                                       |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `IntlayerMiddleware` | AdonisJS 中间件，检测用户的语言区域并使用 Intlayer 数据填充请求上下文。它还设置了一个 CLS (Async Local Storage) 命名空间用于请求生命周期访问，从而启用 `t`、`getIntlayer` 等全局函数的使用。 | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/adonis-intlayer/intlayer.md) |
+
+### 函数
+
+| 函数            | 描述                                                                                                                            | 相关文档                                                                                               |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `t`             | 获取当前语言区域内容的翻译函数。在由 `intlayer` 中间件管理的请求生命周期内工作。使用 CLS (Async Local Storage) 访问请求上下文。 | [translation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/translation.md) |
+| `getIntlayer`   | 通过生成声明中的键检索字典，并返回指定语言区域的内容。`getDictionary` 的优化版本。使用 CLS 访问请求上下文。                     | -                                                                                                      |
+| `getDictionary` | 处理字典对象并返回指定语言区域的内容。处理 `t()` 翻译、枚举、markdown、HTML 等。使用 CLS 访问请求上下文。                       | -                                                                                                      |
+| `getLocale`     | 使用 CLS 从请求上下文中检索当前语言区域。                                                                                       | -                                                                                                      |

package/docs/zh/packages/adonis-intlayer/intlayer.md

@@ -0,0 +1,54 @@
+---
+createdAt: 2026-01-30
+updatedAt: 2026-01-30
+title: intlayer AdonisJS 中间件文档 | adonis-intlayer
+description: 了解如何为 adonis-intlayer 包使用 intlayer 中间件
+keywords:
+  - intlayer
+  - adonisjs
+  - 中间件
+  - Intlayer
+  - 国际化
+  - 文档
+slugs:
+  - doc
+  - packages
+  - adonis-intlayer
+  - intlayer
+history:
+  - version: 8.0.0
+    date: 2026-01-30
+    changes: 初始文档
+---
+
+# intlayer AdonisJS 中间件文档
+
+用于 AdonisJS 的 `intlayer` 中间件检测用户的语言区域，并通过请求上下文提供翻译函数。它还允许在请求流中使用全局翻译函数。
+
+## 用法
+
+```ts fileName="start/kernel.ts"
+router.use([() => import("adonis-intlayer/middleware")]);
+```
+
+```ts fileName="start/routes.ts"
+import router from "@adonisjs/core/services/router";
+import { t } from "adonis-intlayer";
+
+router.get("/", async () => {
+  return t({
+    en: "Hello",
+    fr: "Bonjour",
+  });
+});
+```
+
+## 描述
+
+该中间件执行以下任务：
+
+1. **语言区域检测**：它分析请求（标头、cookie 等）以确定用户的首选语言区域。
+2. **上下文设置**：它使用语言区域信息填充请求上下文。
+3. **Async Local Storage**：它使用 `cls-hooked` 管理异步上下文，允许全局 Intlayer 函数（如 `t`、`getIntlayer` 和 `getDictionary`）访问请求特定的语言区域，而无需手动传递。
+
+> 注意：要使用 cookie 进行语言区域检测，请确保在您的应用程序中配置并使用了 `@adonisjs/cookie`。

package/docs/zh/packages/adonis-intlayer/t.md

@@ -0,0 +1,149 @@
+---
+createdAt: 2026-01-30
+updatedAt: 2026-01-30
+title: t 函数文档 | adonis-intlayer
+description: 了解如何为 adonis-intlayer 包使用 t 函数
+keywords:
+  - t
+  - 翻译
+  - Intlayer
+  - 国际化
+  - 文档
+  - AdonisJS
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - adonis-intlayer
+  - t
+history:
+  - version: 8.0.0
+    date: 2026-01-30
+    changes: 初始文档
+---
+
+# 文档：`adonis-intlayer` 中的 `t` 函数
+
+`adonis-intlayer` 包中的 `t` 函数是在 AdonisJS 应用程序中提供本地化响应的核心工具。它通过根据用户的首选语言动态选择内容，简化了国际化 (i18n) 过程。
+
+---
+
+## 概述
+
+`t` 函数用于定义和检索一组给定语言的翻译。它根据客户端的请求设置（如 `Accept-Language` 标头）自动确定要返回的相应语言。如果首选语言不可用，它会优雅地回退到配置中指定的默认语言区域。
+
+---
+
+## 关键特性
+
+- **动态本地化**：自动为客户端选择最合适的翻译。
+- **回退到默认语言区域**：如果客户端的首选语言不可用，则回退到默认语言区域，确保用户体验的连续性。
+- **异步上下文**：使用 Async Local Storage 在 AdonisJS 请求生命周期内无缝工作。
+- **TypeScript 支持**：为您的翻译强制执行类型安全。
+
+---
+
+## 函数签名
+
+```typescript
+t(translations: Record<string, any>): any;
+```
+
+### 参数
+
+- `translations`：一个对象，其键为语言区域代码（例如 `en`、`fr`、`es`），值为相应的翻译内容。
+
+### 返回值
+
+- 代表客户端首选语言的内容。
+
+---
+
+## 加载中间件
+
+为了确保 `t` 函数正常工作，您**必须**在 AdonisJS 应用程序中注册 `intlayer` 中间件。
+
+```typescript fileName="start/kernel.ts"
+router.use([() => import("adonis-intlayer/middleware")]);
+```
+
+---
+
+## 使用示例
+
+### 基础示例
+
+```typescript fileName="start/routes.ts"
+import router from "@adonisjs/core/services/router";
+import { t } from "adonis-intlayer";
+
+router.get("/", async () => {
+  return t({
+    en: "Welcome!",
+    fr: "Bienvenue !",
+    es: "¡Bienvenido!",
+  });
+});
+```
+
+### 在控制器中使用
+
+```typescript fileName="app/controllers/example_controller.ts"
+import type { HttpContext } from "@adonisjs/core/http";
+import { t } from "adonis-intlayer";
+
+export default class ExampleController {
+  async index({ response }: HttpContext) {
+    return response.send(
+      t({
+        en: "Hello from controller",
+        fr: "Bonjour 來自控制器",
+      })
+    );
+  }
+}
+```
+
+---
+
+## 高级主题
+
+### 回退机制
+
+如果首选语言区域不可用，`t` 函数将回退到 `intlayer.config.ts` 中定义的默认语言区域。
+
+```typescript
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [
+      Locales.ENGLISH,
+      Locales.RUSSIAN,
+      Locales.JAPANESE,
+      Locales.FRENCH,
+      Locales.KOREAN,
+      Locales.CHINESE,
+      Locales.SPANISH,
+      Locales.GERMAN,
+      Locales.ARABIC,
+      Locales.ITALIAN,
+      Locales.ENGLISH_UNITED_KINGDOM,
+      Locales.PORTUGUESE,
+      Locales.HINDI,
+      Locales.TURKISH,
+      Locales.POLISH,
+      Locales.INDONESIAN,
+      Locales.VIETNAMESE,
+      Locales.UKRAINIAN,
+    ],
+    defaultLocale: Locales.ENGLISH,
+  },
+};
+
+export default config;
+```
+
+### TypeScript 集成
+
+当与定义的字典一起使用时，`t` 函数是类型安全的。有关更多详细信息，请参阅 [TypeScript 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。

package/docs/zh/packages/hono-intlayer/exports.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-01-29
+updatedAt: 2026-01-29
+title: hono-intlayer 包文档
+description: 用于 Intlayer 的 Hono 中间件，提供翻译函数和语言检测。
+keywords:
+  - hono-intlayer
+  - hono
+  - 中间件
+  - 国际化
+  - i18n
+slugs:
+  - doc
+  - packages
+  - hono-intlayer
+  - exports
+history:
+  - version: 8.0.0
+    date: 2026-01-29
+    changes: 统一所有导出的文档
+---
+
+# hono-intlayer 包
+
+`hono-intlayer` 包为 Hono 应用程序提供了一个处理国际化的中间件。它检测用户的语言并填充上下文对象。
+
+## 安装
+
+```bash
+npm install hono-intlayer
+```
+
+## 导出
+
+### 中间件
+
+导入：
+
+```tsx
+import { intlayer } from "hono-intlayer";
+```
+
+| 函数       | 描述                                                                                                                                                                                                     | 相关文档                                                                                                     |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `intlayer` | 将 Intlayer 集成到 Hono 应用程序中的 Hono 中间件。处理来自存储（cookie、标头）的语言检测，使用 `t`、`getIntlayer` 和 `getDictionary` 填充上下文，并设置 CLS 命名空间以便在请求生命周期内进行程序化访问。 | [intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/packages/hono-intlayer/intlayer.md) |
+
+### 函数
+
+导入：
+
+```tsx
+import { t, getIntlayer, getDictionary } from "hono-intlayer";
+```
+
+| 函数            | 描述                                                                                                                                       | 相关文档                                                                                               |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| `t`             | 获取 Hono 中当前语言内容的全局翻译函数。利用 CLS（异步本地存储），必须在由 `intlayer` 中间件管理的请求上下文中使用。也可以通过上下文访问。 | [translation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/translation.md) |
+| `getIntlayer`   | 通过生成声明中的键检索字典，并返回指定语言的内容。`getDictionary` 的优化版本。使用 CLS 访问请求上下文。也可以通过上下文访问。              | -                                                                                                      |
+| `getDictionary` | 处理字典对象并返回指定语言的内容。处理 `t()` 翻译、枚举、markdown、HTML 等。使用 CLS 访问请求上下文。也可以通过上下文访问。                | -                                                                                                      |

package/docs/zh/packages/hono-intlayer/intlayer.md

@@ -0,0 +1,60 @@
+---
+createdAt: 2026-01-29
+updatedAt: 2026-01-29
+title: intlayer Hono 中间件文档 | hono-intlayer
+description: 了解如何为 hono-intlayer 包使用 intlayer 中间件
+keywords:
+  - intlayer
+  - hono
+  - 中间件
+  - Intlayer
+  - 国际化
+  - 文档
+slugs:
+  - doc
+  - packages
+  - hono-intlayer
+  - intlayer
+history:
+  - version: 8.0.0
+    date: 2026-01-29
+    changes: 初始化文档
+---
+
+# intlayer Hono 中间件文档
+
+用于 Hono 的 `intlayer` 中间件可检测用户的语言并使用 Intlayer 函数填充上下文对象。它还允许在请求上下文中使用全局翻译函数。
+
+## 用法
+
+```ts
+import { Hono } from "hono";
+import { intlayer } from "hono-intlayer";
+
+const app = new Hono();
+
+app.use("*", intlayer());
+
+app.get("/", async (c) => {
+  const t = c.get("t");
+  const content = t({
+    en: "Hello",
+    fr: "Bonjour",
+    zh: "你好",
+  });
+
+  return c.text(content);
+});
+```
+
+## 说明
+
+该中间件执行以下任务：
+
+1. **语言检测**：分析请求（标头、cookie 等）以确定用户的首选语言。
+2. **上下文填充**：将 Intlayer 数据添加到 Hono 上下文，可通过 `c.get()` 访问。这包括：
+   - `locale`：检测到的语言。
+   - `t`：翻译函数。
+   - `getIntlayer`：检索字典的函数。
+   - `getDictionary`：处理字典对象的函数。
+3. **上下文管理**：使用 `cls-hooked` 管理异步上下文，允许全局 Intlayer 函数（`t`、`getIntlayer`、`getDictionary`）访问特定于请求的语言，而无需传递上下文对象。

package/docs/zh/packages/hono-intlayer/t.md

@@ -0,0 +1,294 @@
+---
+createdAt: 2024-12-02
+updatedAt: 2025-06-29
+title: t 函数文档 | hono-intlayer
+description: 了解如何为 hono-intlayer 包使用 t 函数
+keywords:
+  - t
+  - 翻译
+  - Intlayer
+  - 国际化
+  - 文档
+  - Hono
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - hono-intlayer
+  - t
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: 初始化历史记录
+---
+
+# 文档：`hono-intlayer` 中的 `t` 函数
+
+`hono-intlayer` 包中的 `t` 函数是为您在 Hono 应用程序中提供本地化响应的核心工具。它通过根据用户的首选语言动态选择内容来简化国际化 (i18n)。
+
+---
+
+## 概述
+
+`t` 函数用于定义和检索一组给定语言的翻译。它根据客户端的请求设置（如 `Accept-Language` 标头）自动确定要返回的适当语言。如果首选语言不可用，它会优雅地回退到配置中指定的默认语言。
+
+---
+
+## 核心特性
+
+- **动态本地化**：自动为客户端选择最合适的翻译。
+- **回退到默认语言**：如果客户端的首选语言不可用，则回退到默认语言，确保用户体验的连续性。
+- **轻量且快速**：专为高性能应用程序设计，确保最小的开销。
+- **严格模式支持**：强制严格遵守声明的语言，以获得可靠的行为。
+
+---
+
+## 函数签名
+
+```typescript
+t(translations: Record<string, string>): string;
+```
+
+### 参数
+
+- `translations`：一个对象，其中的键是语言代码（例如 `en`、`fr`、`zh`），值是相应的翻译字符串。
+
+### 返回值
+
+- 一个表示客户端首选语言内容的字符串。
+
+---
+
+## 加载国际化请求处理器
+
+为了确保 `hono-intlayer` 提供的国际化功能正常工作，您**必须**在 Hono 应用程序的开头加载国际化中间件。这会启用 `t` 函数并确保正确处理语言检测和翻译。
+
+将 `app.use("*", intlayer())` 中间件放置在应用程序的**任何路由之前**，以确保所有路由都受益于国际化：
+
+```typescript {6} fileName="src/index.ts" codeFormat="typescript"
+import { Hono } from "hono";
+import { intlayer } from "hono-intlayer";
+
+const app = new Hono();
+
+// 加载国际化请求处理器
+app.use("*", intlayer());
+
+// 在加载中间件后定义路由
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+      zh: "你好，世界！",
+    })
+  );
+});
+```
+
+```javascript {6} fileName="src/index.mjs" codeFormat="esm"
+import { Hono } from "hono";
+import { intlayer } from "hono-intlayer";
+
+const app = new Hono();
+
+// 加载国际化请求处理器
+app.use("*", intlayer());
+
+// 在加载中间件后定义路由
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+      zh: "你好，世界！",
+    })
+  );
+});
+```
+
+```javascript {6} fileName="src/index.cjs" codeFormat="commonjs"
+const { Hono } = require("hono");
+const { intlayer, t } = require("hono-intlayer");
+
+const app = new Hono();
+
+// 加载国际化请求处理器
+app.use("*", intlayer());
+
+// 在加载中间件后定义路由
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Hello, World!",
+      fr: "Bonjour le monde!",
+      es: "¡Hola, Mundo!",
+      zh: "你好，世界！",
+    })
+  );
+});
+```
+
+### 为什么这是必需的
+
+- **语言检测**：`intlayer` 中间件处理传入请求，根据标头、cookie 或其他配置方法检测用户的首选语言。
+- **翻译上下文**：设置 `t` 函数正常运行所需的上下文，确保以正确的语言返回翻译。
+- **防止错误**：如果没有此中间件，使用 `t` 函数将导致运行时错误，因为必要的语言信息将不可用。
+
+---
+
+## 使用示例
+
+### 基础示例
+
+提供不同语言的本地化内容：
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Welcome!",
+      fr: "Bienvenue!",
+      zh: "欢迎！",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.mjs" codeFormat="esm"
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Welcome!",
+      fr: "Bienvenue!",
+      zh: "欢迎！",
+    })
+  );
+});
+```
+
+```javascript fileName="src/index.cjs" codeFormat="commonjs"
+app.get("/", (c) => {
+  return c.text(
+    t({
+      en: "Welcome!",
+      fr: "Bienvenue!",
+      zh: "欢迎！",
+    })
+  );
+});
+```
+
+**客户端请求：**
+
+- `Accept-Language: fr` 的客户端将收到 `Bienvenue!`。
+- `Accept-Language: zh` 的客户端将收到 `欢迎！`。
+- `Accept-Language: de` 的客户端将收到 `Welcome!`（默认语言）。
+
+### 处理错误
+
+提供多种语言的错误消息：
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/error", (c) => {
+  return c.text(
+    t({
+      en: "An unexpected error occurred.",
+      fr: "Une erreur inattendue s'est produite.",
+      zh: "发生意外错误。",
+    }),
+    500
+  );
+});
+```
+
+---
+
+### 使用语言变体
+
+为特定语言变体指定翻译：
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+app.get("/greet", (c) => {
+  return c.text(
+    t({
+      en: "Hello!",
+      "en-GB": "Hello, mate!",
+      fr: "Bonjour!",
+      zh: "你好！",
+      "zh-CN": "你好！",
+      "zh-TW": "你好！",
+    })
+  );
+});
+```
+
+---
+
+## 进阶主题
+
+### 回退机制
+
+如果首选语言不可用，`t` 函数将回退到配置中定义的默认语言：
+
+```typescript {5-6} fileName="intlayer.config.ts" codeFormat="typescript"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.CHINESE],
+    defaultLocale: Locales.ENGLISH,
+  },
+} satisfies IntlayerConfig;
+
+export default config;
+```
+
+---
+
+### 严格模式强制执行
+
+配置 `t` 函数以强制严格遵守声明的语言：
+
+| 模式        | 行为                                                 |
+| ----------- | ---------------------------------------------------- |
+| `strict`    | 所有声明的语言必须提供翻译。缺失语言将抛出错误。     |
+| `inclusive` | 声明的语言必须有翻译。缺失语言会触发警告但会被接受。 |
+| `loose`     | 接受任何现有的语言，即使未声明。                     |
+
+---
+
+### TypeScript 集成
+
+使用 TypeScript 时，`t` 函数是类型安全的。定义一个类型安全的翻译对象：
+
+```typescript fileName="src/index.ts" codeFormat="typescript"
+import { type LanguageContent } from "hono-intlayer";
+
+const translations: LanguageContent<string> = {
+  en: "Good morning!",
+  fr: "Bonjour!",
+  zh: "早上好！",
+};
+
+app.get("/morning", (c) => {
+  return c.text(t(translations));
+});
+```
+
+---
+
+### 常见错误与排查
+
+| 问题             | 原因                                       | 解决方案                                          |
+| ---------------- | ------------------------------------------ | ------------------------------------------------- |
+| `t` 函数不起作用 | 未加载中间件                               | 确保在路由之前添加了 `app.use("*", intlayer())`。 |
+| 缺失翻译错误     | 在未提供所有语言翻译的情况下启用了严格模式 | 提供所有必需的翻译。                              |
+
+---
+
+## 结论
+
+`t` 函数是后端国际化的强大工具。通过有效地使用它，您可以为全球受众创建一个更具包容性和用户友好的应用程序。有关进阶用法和详细配置选项，请参阅[文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/configuration.md)。

package/package.json

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