@intlayer/docs 5.5.9 → 5.5.11

package/docs/zh/introduction.md

@@ -0,0 +1,208 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-06-29
+title: 介绍
+description: 了解 Intlayer 的工作原理。查看 Intlayer 在您的应用程序中使用的步骤。了解不同包的功能。
+keywords:
+  - 介绍
+  - 入门
+  - Intlayer
+  - 应用程序
+  - 包
+slugs:
+  - doc
+  - get-started
+---
+
+# Intlayer 文档
+
+欢迎来到官方 Intlayer 文档！在这里，您将找到集成、配置和掌握 Intlayer 所需的一切，无论您使用的是 Next.js、React、Vite、Express 还是其他 JavaScript 环境，满足您所有的国际化（i18n）需求。
+
+## 介绍
+
+### 什么是 Intlayer？
+
+**Intlayer** 是一个专为 JavaScript 开发者设计的国际化库。它允许您在代码中的任何地方声明内容。它将多语言内容的声明转换为结构化的字典，方便您轻松地集成到代码中。通过使用 TypeScript，**Intlayer** 使您的开发更加稳健和高效。
+
+Intlayer 还提供了一个可选的可视化编辑器，允许您轻松编辑和管理内容。这个编辑器对于喜欢使用可视化界面进行内容管理的开发者，或者不想担心代码的团队来说尤其有用。
+
+### 使用示例
+
+```bash
+.
+└── Components
+    └── MyComponent
+        ├── index.content.cjs
+        └── index.mjs
+```
+
+```tsx fileName="src/components/MyComponent/index.content.ts" contentDeclarationFormat="typescript"
+import { t, type Dictionary } from "intlayer";
+
+const componentContent = {
+  key: "component-key",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+  },
+} satisfies Dictionary; // 满足 Dictionary 类型
+
+export default componentContent;
+```
+
+```javascript fileName="src/components/MyComponent/index.content.mjs" contentDeclarationFormat="esm"
+import { t } from "intlayer";
+
+/** @type {import('intlayer').Dictionary} */
+const componentContent = {
+  key: "component-key",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+  },
+};
+
+export default componentContent;
+```
+
+```javascript fileName="src/components/MyComponent/index.content.cjs" contentDeclarationFormat="commonjs"
+const { t } = require("intlayer");
+
+/** @type {import('intlayer').Dictionary} */
+// 组件内容的字典定义
+const componentContent = {
+  key: "component-key",
+  content: {
+    myTranslatedContent: t({
+      en: "Hello World",
+      fr: "Bonjour le monde",
+      es: "Hola Mundo",
+    }),
+  },
+};
+
+module.exports = componentContent;
+```
+
+```json fileName="src/components/MyComponent/index.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "component-key",
+  "content": {
+    "myTranslatedContent": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "Hello World",
+        "fr": "Bonjour le monde",
+        "es": "Hola Mundo"
+      }
+    }
+  }
+}
+```
+
+```tsx fileName="src/components/MyComponent/index.tsx" codeFormat="typescript"
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+export const MyComponent: FC = () => {
+  const { myTranslatedContent } = useIntlayer("component-key");
+
+  return <span>{myTranslatedContent}</span>;
+};
+```
+
+```jsx fileName="src/components/MyComponent/index.mjx" codeFormat="esm"
+import { useIntlayer } from "react-intlayer";
+
+const MyComponent = () => {
+  const { myTranslatedContent } = useIntlayer("component-key");
+
+  return <span>{myTranslatedContent}</span>;
+};
+```
+
+```jsx fileName="src/components/MyComponent/index.csx" codeFormat="commonjs"
+const { useIntlayer } = require("react-intlayer");
+
+const MyComponent = () => {
+  const { myTranslatedContent } = useIntlayer("component-key");
+
+  return <span>{myTranslatedContent}</span>;
+};
+```
+
+## 主要功能
+
+Intlayer 提供了多种功能，专为满足现代网页开发的需求而设计。以下是主要功能，并附有详细文档链接：
+
+- **国际化支持**：通过内置的国际化支持，提升您的应用程序的全球影响力。
+- **可视化编辑器**：使用为 Intlayer 设计的编辑器插件，优化您的开发工作流程。请查看 [可视化编辑器指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md)。
+- **配置灵活性**：通过详尽的配置选项自定义您的设置，详见[配置指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
+- **高级命令行工具**：使用 Intlayer 的命令行界面高效管理您的项目。探索其功能请参阅[命令行工具文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_cli.md)。
+
+## 核心概念
+
+### 字典
+
+将您的多语言内容组织在代码附近，保持内容一致且易于维护。
+
+- **[入门指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/get_started.md)**  
+  学习在 Intlayer 中声明内容的基础知识。
+
+- **[翻译](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/translation.md)**  
+  了解翻译内容如何在您的应用中生成、存储和使用。
+
+- **[枚举](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/enumeration.md)**  
+  轻松管理跨多语言的重复或固定数据集。
+
+- **[条件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/conditional.md)**  
+  学习如何在 Intlayer 中使用条件逻辑来创建动态内容。
+
+- **[插入](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/insertion.md)**  
+  了解如何使用插入占位符在字符串中插入值。
+
+- **[函数获取](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/function_fetching.md)**  
+  了解如何使用自定义逻辑动态获取内容，以匹配您的项目工作流程。
+
+- **[Markdown](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/markdown.md)**  
+  学习如何在 Intlayer 中使用 Markdown 创建丰富的内容。
+
+- **[文件嵌入](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/file_embeddings.md)**  
+  发现如何在 Intlayer 中嵌入外部文件，以便在内容编辑器中使用它们。
+
+- **[嵌套](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/nesting.md)**  
+  理解如何在 Intlayer 中嵌套内容，以创建复杂的结构。
+
+### 环境与集成
+
+我们在设计 Intlayer 时充分考虑了灵活性，提供了与流行框架和构建工具的无缝集成：
+
+- **[Intlayer 与 Next.js 15 集成](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_nextjs_15.md)**
+- **[Intlayer 与 Next.js 14（App Router）集成](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_nextjs_14.md)**
+- **[Intlayer 与 Next.js 页面路由集成](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_nextjs_page_router.md)**
+- **[Intlayer 与 React CRA 集成](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_create_react_app.md)**
+- **[Intlayer 与 Vite + React 集成](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_vite+react.md)**
+- **[Intlayer 与 React Native 和 Expo 集成](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_react_native+expo.md)**
+- **[Intlayer 与 Lynx 和 React 集成](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_lynx+react.md)**
+- **[Intlayer 与 Express 集成](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_express.md)**
+
+每个集成指南都包含使用 Intlayer 功能的最佳实践，如 **服务器端渲染**、**动态路由** 或 **客户端渲染**，帮助您保持应用的高速、SEO 友好且高度可扩展。
+
+## 贡献与反馈
+
+我们重视开源和社区驱动开发的力量。如果您想提出改进建议、添加新的指南，或纠正文档中的任何问题，欢迎随时提交 Pull Request 或在我们的 [GitHub 仓库](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh) 中打开 issue。
+
+**准备好更快更高效地翻译您的应用了吗？** 立即深入阅读我们的文档，开始使用 Intlayer。体验一种强大且简化的国际化方法，帮助您保持内容有序，提高团队生产力。
+
+---
+
+## 文档历史
+
+- 5.5.10 - 2025-06-29：初始化历史

package/docs/zh/mcp_server.md

@@ -0,0 +1,175 @@
+---
+createdAt: 2025-06-07
+updatedAt: 2025-06-07
+title: MCP 服务器文档
+description: 探索 MCP 服务器的功能和设置，优化您的服务器管理和操作。
+keywords:
+  - MCP 服务器
+  - 服务器管理
+  - 优化
+  - Intlayer
+  - 文档
+  - 设置
+  - 功能
+slugs:
+  - doc
+  - mcp-server
+---
+
+# Intlayer MCP 服务器
+
+**Intlayer MCP（模型上下文协议）服务器** 提供了针对 Intlayer 生态系统量身定制的 AI 驱动 IDE 辅助。该服务器专为现代开发环境设计，如 **Cursor**、**GitHub Copilot 工作区**，以及任何支持 MCP 协议的 IDE，基于您的项目设置，提供上下文相关的实时支持。
+
+## 为什么使用 Intlayer MCP 服务器？
+
+通过在您的 IDE 中启用 Intlayer MCP 服务器，您将获得：
+
+- **智能 CLI 集成**  
+  直接从您的 IDE 界面访问并运行 Intlayer CLI 命令。完整的命令和选项列表请参阅 [Intlayer CLI 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_cli.md)。
+
+- **上下文感知文档**  
+  MCP 服务器会加载并展示与您项目中使用的 Intlayer 版本对应的文档。这确保了代码建议、命令选项和说明始终是最新且相关的。
+
+- **AI 辅助开发**  
+  通过项目感知的建议和自动补全，AI 助手可以解释您的代码，推荐 CLI 用法，或根据您当前的文件建议如何使用 Intlayer 的特定功能。
+
+- **轻量且即时设置**  
+  无需服务器维护或繁重安装。只需配置您的 `.cursor/mcp.json` 或等效的 MCP 配置文件，即可开始使用。
+
+---
+
+## 设置 Cursor
+
+在您的项目根目录下，添加以下 `.cursor/mcp.json` 配置文件：
+
+```json
+{
+  "mcpServers": {
+    "intlayer": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@intlayer/mcp"]
+    }
+  }
+}
+```
+
+这告诉您的 IDE 使用 `npx` 启动 Intlayer MCP 服务器，确保始终使用最新可用版本，除非您进行了版本固定。
+
+---
+
+## 设置 VS Code
+
+要在 VS Code 中使用 Intlayer MCP 服务器，您需要在工作区或用户设置中进行配置。
+
+### 工作区配置
+
+在项目根目录下创建 `.vscode/mcp.json` 文件：
+
+```json
+{
+  "servers": {
+    "intlayer": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@intlayer/mcp"]
+    }
+  }
+}
+```
+
+### 在 VS Code 中使用 MCP 服务器
+
+1. **启用代理模式**：打开聊天视图（Mac 上为 ⌃⌘I，Windows/Linux 上为 Ctrl+Alt+I），并从下拉菜单中选择 **代理** 模式。
+
+2. **访问工具**：点击 **工具** 按钮以查看可用的 Intlayer 工具。您可以根据需要选择或取消选择特定工具。
+
+3. **直接引用工具**：在提示中通过输入 `#` 后跟工具名称，直接引用工具。
+
+4. **工具确认**：默认情况下，VS Code 会在运行工具前请求确认。使用 **继续** 按钮的选项，可以自动确认当前会话、工作区或所有未来调用的工具。
+
+### 管理服务器
+
+- 从命令面板运行 **MCP: 列出服务器** 以查看已配置的服务器
+- 根据需要启动、停止或重启 Intlayer MCP 服务器
+- 通过选择服务器并选择 **显示输出** 来查看服务器日志以进行故障排除
+
+有关 VS Code MCP 集成的更多详细信息，请参阅[官方 VS Code MCP 文档](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)。
+
+---
+
+## 通过 CLI 使用 MCP 服务器
+
+您也可以直接从命令行运行 Intlayer MCP 服务器，以便进行测试、调试或与其他工具集成。
+
+### 安装 MCP 服务器
+
+首先，全局安装 MCP 服务器包，或通过 npx 使用：
+
+```bash
+# 全局安装
+npm install -g @intlayer/mcp
+
+# 或直接使用 npx（推荐）
+npx @intlayer/mcp
+```
+
+### 启动服务器
+
+要启动带有调试和测试用检查器的 MCP 服务器：
+
+```bash
+# 使用内置的启动命令
+npm run start
+
+# 或直接使用 npx
+npx @modelcontextprotocol/inspector npx @intlayer/mcp
+```
+
+这将启动带有检查器界面的 MCP 服务器，允许您：
+
+- 测试 MCP 协议通信
+- 调试服务器响应
+- 验证工具和资源的实现
+- 监控服务器性能
+
+### 开发使用
+
+出于开发和测试目的，您可以以多种模式运行服务器：
+
+```bash
+# 构建并以开发模式启动
+npm run dev
+
+# 使用自定义配置运行
+node dist/cjs/index.cjs
+
+# 测试服务器功能
+npm test
+```
+
+服务器将公开 Intlayer 特定的工具和资源，任何兼容 MCP 的客户端都可以使用，而不仅限于 Cursor 或其他 IDE。
+
+---
+
+## 功能概览
+
+| Feature    | Description                                    |
+| ---------- | ---------------------------------------------- |
+| CLI 支持   | 运行 `intlayer` 命令，获取使用提示和内联参数   |
+| 版本化文档 | 自动检测并加载与您当前 Intlayer 版本匹配的文档 |
+| 自动补全   | 输入时智能提供命令和配置建议                   |
+| 插件兼容   | 兼容支持 MCP 标准的 IDE 和工具                 |
+
+---
+
+## 有用链接
+
+- [Intlayer CLI 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_cli.md)
+- [Intlayer GitHub 仓库](https://github.com/aymericzip/intlayer)
+
+---
+
+## 文档历史
+
+- 5.5.10 - 2025-06-29: 初始化历史

package/docs/zh/packages/@intlayer/api/index.md

@@ -0,0 +1,56 @@
+---
+createdAt: 2025-02-07
+updatedAt: 2025-06-29
+title: @intlayer/api - Intlayer API 集成的 SDK
+description: 提供与 Intlayer API 交互的软件开发工具包（SDK）的 NPM 包，用于内容审核、组织、项目和用户管理。
+keywords:
+  - intlayer
+  - API
+  - SDK
+  - 集成
+  - 内容审核
+  - 组织
+  - 项目
+  - JavaScript
+slugs:
+  - doc
+  - packages
+  - intlayer
+  - api
+---
+
+# @intlayer/api：与 Intlayer API 交互的 NPM 包
+
+**Intlayer** 是一套专为 JavaScript 开发者设计的包集合。它兼容 React、React 和 Express.js 等框架。
+
+**`@intlayer/api`** 包是一个用于与 Intlayer API 交互的软件开发工具包（SDK）。它提供了一组函数，用于审核内容声明、与组织、项目和用户进行交互等。
+
+## 使用方法
+
+```ts
+import { intlayerAPI } from "@intlayer/api";
+
+intlayerAPI.user.getUser({
+  ids: ["user-id-1", "user-id-2"],
+});
+```
+
+## 安装
+
+使用您喜欢的包管理器安装所需的包：
+
+```bash packageManager="npm"
+npm install @intlayer/api
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/api
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/api
+```
+
+## 文档历史
+
+- 5.5.10 - 2025-06-29: 初始化历史

package/docs/zh/packages/@intlayer/chokidar/index.md

@@ -0,0 +1,55 @@
+---
+createdAt: 2025-02-07
+updatedAt: 2025-06-29
+title: @intlayer/chokidar - Intlayer 国际化的文件监视
+description: 提供文件监视功能的 NPM 包，支持 Intlayer，实现国际化内容的自动更新和热重载。
+keywords:
+  - intlayer
+  - chokidar
+  - 文件监视
+  - 热重载
+  - i18n
+  - JavaScript
+  - NPM
+  - 开发
+slugs:
+  - doc
+  - package
+  - @intlayer_chokidar
+---
+
+# @intlayer/chokidar：用于扫描并构建 Intlayer 声明文件为字典的 NPM 包
+
+**Intlayer** 是一套专为 JavaScript 开发者设计的包集合。它兼容 React、React Native 和 Express.js 等框架。
+
+**`@intlayer/chokidar`** 包用于使用 [chokidar](https://github.com/paulmillr/chokidar) 并根据 [Intlayer 配置](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md) 扫描并构建 Intlayer 声明文件为字典。
+
+## 使用方法
+
+```ts
+import { watch, prepareIntlayer } from "@intlayer/chokidar";
+
+await prepareIntlayer(); // 构建 Intlayer 字典
+
+watch({ persistent: true }); // 监视配置文件的更改
+```
+
+## 安装
+
+使用您喜欢的包管理器安装所需的包：
+
+```bash packageManager="npm"
+npm install @intlayer/chokidar
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/chokidar
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/chokidar
+```
+
+## 文档历史
+
+- 5.5.10 - 2025-06-29：初始化历史

package/docs/zh/packages/@intlayer/cli/index.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2025-02-07
+updatedAt: 2025-06-29
+title: @intlayer/cli - Intlayer 的命令行界面包
+description: 提供 Intlayer CLI 命令脚本的 NPM 包，确保所有国际化管理命令行界面的一致性。
+keywords:
+  - intlayer
+  - CLI
+  - 命令行
+  - 脚本
+  - i18n
+  - JavaScript
+  - NPM
+  - 工具
+slugs:
+  - doc
+  - package
+  - @intlayer_cli
+---
+
+# @intlayer/cli：用于使用 intlayer CLI 提供的脚本的 NPM 包
+
+**Intlayer** 是一套专为 JavaScript 开发者设计的包集合。它兼容 React、React 和 Express.js 等框架。
+
+**`@intlayer/cli`** 包是一个 NPM 包，用于声明与 intlayer 命令行接口相关的脚本。它确保所有 intlayer CLI 命令的一致性。该包主要被 [intlayer-cli](https://github.com/aymericzip/intlayer/tree/main/docs/docs/zh/packages/intlayer-cli/index.md) 和 [intlayer](https://github.com/aymericzip/intlayer/tree/main/docs/docs/zh/packages/intlayer/index.md) 包所使用。
+
+## 安装
+
+使用您喜欢的包管理器安装所需的包：
+
+```bash packageManager="npm"
+npm install @intlayer/cli
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/cli
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/cli
+```
+
+## 文档历史
+
+- 5.5.10 - 2025-06-29：初始化历史

package/docs/zh/packages/@intlayer/config/index.md

@@ -0,0 +1,140 @@
+---
+createdAt: 2025-02-07
+updatedAt: 2025-06-29
+title: @intlayer/config - Intlayer 的配置管理
+description: 用于检索 Intlayer 配置并定义跨不同环境的国际化设置环境变量的 NPM 包。
+keywords:
+  - intlayer
+  - 配置
+  - 环境
+  - 设置
+  - i18n
+  - JavaScript
+  - NPM
+  - 变量
+slugs:
+  - doc
+  - package
+  - @intlayer_config
+---
+
+# @intlayer/config：用于检索 Intlayer 配置的 NPM 包
+
+**Intlayer** 是一套专为 JavaScript 开发者设计的包集合。它兼容 React、React Native 和 Express.js 等框架。
+
+**`@intlayer/config`** 包是一个 NPM 包，允许您检索 Intlayer 的配置并定义与当前环境相关的环境变量。
+
+## 安装
+
+使用您喜欢的包管理器安装所需的包：
+
+```bash packageManager="npm"
+npm install @intlayer/config
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/config
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/config
+```
+
+## 使用方法
+
+### 使用文件系统读取 Intlayer 配置
+
+示例：
+
+```ts
+import { getConfiguration, type IntlayerConfig } from "@intlayer/config";
+
+const config: IntlayerConfig = getConfiguration();
+
+console.log(config);
+// 输出：
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+> 此函数使用 `fs` 包，仅在服务器端运行。
+
+### 使用环境变量读取 Intlayer 配置
+
+示例：
+
+```ts
+import { getConfiguration, type IntlayerConfig } from "@intlayer/config/client";
+
+const config: IntlayerConfig = getConfiguration({
+  env: "production",
+});
+
+console.log(config);
+// 输出：
+// {
+//   internationalization: { ... },
+//   middleware: { ... },
+//   content: { ... },
+//   editor: { ... }
+// }
+```
+
+> 如果环境变量未定义，此函数不会返回任何内容。
+
+### 定义环境变量
+
+1. 创建一个配置文件。
+
+```ts fileName="intlayer.config.ts"
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    /* ... */
+  },
+  middleware: {
+    /* ... */
+  },
+  content: {
+    /* ... */
+  },
+  editor: {
+    /* ... */
+  },
+};
+
+export default config;
+```
+
+> 详情请参阅 [Intlayer 配置文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/configuration.md)。
+
+2. 定义环境变量。
+
+```ts
+import { getConfiguration } from "@intlayer/config";
+
+const intlayerConfig = getConfiguration();
+
+// 将所有配置值格式化为环境变量
+const env = formatEnvVariable();
+
+// 将每个格式化后的环境变量设置到 process.env 中
+Object.assign(process.env, env);
+```
+
+3. 导入配置文件。
+
+```ts
+import { getConfiguration } from "@intlayer/config/client";
+
+const intlayerConfig = getConfiguration();
+```
+
+## 文档历史
+
+- 5.5.10 - 2025-06-29: 初始化历史