@intlayer/docs 8.11.2 → 8.11.3

package/docs/zh/introduction.md

@@ -1,34 +1,34 @@
 ---
-createdAt: 2024-08-11
-updatedAt: 2025-06-29
-title: 介绍
-description: 了解 Intlayer 的工作原理。查看 Intlayer 在您的应用程序中使用的步骤。了解不同包的功能。
+createdAt: 2025-08-23
+updatedAt: 2025-08-23
+title: 简介
+description: 了解 Intlayer 的工作原理。查看 Intlayer 在您的应用程序中使用的步骤。了解不同的包各自的功能。
 keywords:
-  - 介绍
+  - 简介
   - 入门
   - Intlayer
   - 应用程序
-  - 包
+  - 软件包
 slugs:
   - doc
   - get-started
 history:
   - version: 5.5.10
     date: 2025-06-29
-    changes: "初始化历史"
+    changes: "Init history"
 ---
 
 # Intlayer 文档
 
-欢迎来到官方 Intlayer 文档！在这里，您将找到集成、配置和掌握 Intlayer 所需的一切，无论您使用的是 Next.js、React、Vite、Express 还是其他 JavaScript 环境，满足您所有的国际化（i18n）需求。
+欢迎来到官方的 Intlayer 文档！在这里，您将找到整合、配置和掌握 Intlayer 以满足所有国际化 (i18n) 需求所需的全部内容，无论您是使用 Next.js、React、Vite、Express 还是其他 JavaScript 环境。
 
-## 介绍
+## 简介
 
 ### 什么是 Intlayer？
 
-**Intlayer** 是一个专为 JavaScript 开发者设计的国际化库。它允许您在代码中的任何地方声明内容。它将多语言内容的声明转换为结构化的字典，方便您轻松地集成到代码中。通过使用 TypeScript，**Intlayer** 使您的开发更加稳健和高效。
+**Intlayer** 是一个专门为 JavaScript 开发者设计的国际化库。它允许在代码的任何位置声明您的内容。它将多语言内容的声明转换为结构化的字典，以便轻松集成到您的代码中。通过使用 TypeScript，**Intlayer** 使您的开发更加强大和高效。
 
-Intlayer 还提供了一个可选的可视化编辑器，允许您轻松编辑和管理内容。这个编辑器对于喜欢使用可视化界面进行内容管理的开发者，或者不想担心代码的团队来说尤其有用。
+Intlayer 还提供了一个可选的可视化编辑器，允许您轻松编辑和管理您的内容。该编辑器对于那些更喜欢使用可视化界面进行内容管理的开发者，或者对于在生成内容时不需要关注代码的团队来说特别有用。
 
 ### 使用示例
 
@@ -50,9 +50,10 @@ const componentContent = {
       en: "Hello World",
       es: "Hola Mundo",
       fr: "Bonjour le monde",
+      zh: "你好，世界",
     }),
   },
-} satisfies Dictionary; // 满足 Dictionary 类型
+} satisfies Dictionary;
 
 export default componentContent;
 ```
@@ -67,7 +68,8 @@ export default componentContent;
       "translation": {
         "en": "Hello World",
         "fr": "Bonjour le monde",
-        "es": "Hola Mundo"
+        "es": "Hola Mundo",
+        "zh": "你好，世界"
       }
     }
   }
@@ -85,67 +87,104 @@ export const MyComponent: FC = () => {
 };
 ```
 
-## 主要功能
+## 主要特性
 
-Intlayer 提供了多种功能，专为满足现代网页开发的需求而设计。以下是主要功能，并附有详细文档链接：
+Intlayer 提供了多种功能，旨在满足现代 Web 开发的需求。以下是主要功能，以及每个功能的详细文档链接：
 
-- **国际化支持**：通过内置的国际化支持，提升您的应用程序的全球影响力。
-- **可视化编辑器**：使用为 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/cli/index.md)。
+- **国际化支持**：通过内置的国际化支持，增强应用程序的全球覆盖范围。
+- **可视化编辑器**：使用专为 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) 中详细说明的广泛配置选项，自定义您的设置。
+- **高级 CLI 工具**：使用 Intlayer 的命令行界面高效管理您的项目。在 [CLI 工具文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/index.md) 中探索相关功能。
 
 ## 核心概念
 
 ### 字典
 
-将您的多语言内容组织在代码附近，保持内容一致且易于维护。
+将多语言内容整理到离代码较近的位置，以保持所有内容的一致性和可维护性。
 
-- **[入门指南](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.md)**  
+- **[快速入门](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/content_file.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/condition.md)**  
-  学习如何在 Intlayer 中使用条件逻辑来创建动态内容。
+  了解如何在 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/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 创建丰富的内容。
+  了解如何在 Intlayer 中使用 Markdown 来创建富文本内容。
 
 - **[文件嵌入](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/file.md)**  
-  发现如何在 Intlayer 中嵌入外部文件，以便在内容编辑器中使用它们。
+  发现如何在 Intlayer 中嵌入外部文件，以便在内容编辑器中使用。
 
 - **[嵌套](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/dictionary/nesting.md)**  
-  理解如何在 Intlayer 中嵌套内容，以创建复杂的结构。
+  了解如何在 Intlayer 中嵌套内容以创建复杂的结构。
 
 ### 环境与集成
 
-我们在设计 Intlayer 时充分考虑了灵活性，提供了与流行框架和构建工具的无缝集成：
+我们在构建 Intlayer 时考虑到了灵活性，提供了在主流框架和构建工具中的无缝集成：
+
+- **[Intlayer 与 Next.js 16](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_nextjs_16.md)**
+- **[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 Page Router](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 Router v7](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_react_router_v7.md)**
+- **[Intlayer 与 Tanstack Start](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_tanstack.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 与 Vite + Preact](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_vite+preact.md)**
+- **[Intlayer 与 Vite + Vue](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_vite+vue.md)**
+- **[Intlayer 与 Nuxt](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_nuxt.md)**
+- **[Intlayer 与 Vite + Svelte](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_vite+svelte.md)**
+- **[Intlayer 与 SvelteKit](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_svelte_kit.md)**
+- **[Intlayer 与 Express](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_express.md)**
+- **[Intlayer 与 NestJS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_nestjs.md)**
+- **[Intlayer 与 Hono](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_hono.md)**
+- **[Intlayer 与 Angular](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_with_angular_21.md)**
+
+每篇集成指南都包含了使用 Intlayer 功能的最佳实践，例如 **服务端渲染**、**动态路由** 或 **客户端渲染**，以便您可以维护一个快速、SEO 友好且高度可扩展的应用程序。
 
-- **[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) 中提出 Issue。
 
-## 贡献与反馈
+**准备好更快速、更高效地翻译您的应用程序了吗？** 立即深入我们的文档，开始使用 Intlayer。体验一个强大且精简的国际化方法，让您的内容井井有条，并提高您的团队工作效率。
 
-我们重视开源和社区驱动开发的力量。如果您想提出改进建议、添加新的指南，或纠正文档中的任何问题，欢迎随时提交 Pull Request 或在我们的 [GitHub 仓库](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh) 中打开 issue。
+### 为什么选择 Intlayer 而不是其他替代方案？
 
-**准备好更快更高效地翻译您的应用了吗？** 立即深入阅读我们的文档，开始使用 Intlayer。体验一种强大且简化的国际化方法，帮助您保持内容有序，提高团队生产力。
+与 `next-intl` 或 `i18next` 等主流解决方案相比，Intlayer 是一个自带多项集成的优化方案，例如：
 
----
+**捆绑体积 (Bundle Size)**
+
+您无需在页面中加载庞大的 JSON 文件，而是只加载所需的内容。Intlayer 可以帮助 **将您的捆绑包和页面大小减小多达 50%**。
+
+**可维护性**
+
+将您的应用程序内容局限在相应范围内，**有助于维护**大规模的应用程序。您可以复制或删除单个功能文件夹，而不会有审查整个内容代码库的心理负担。此外，Intlayer 是 **完全类型化 (fully typed)** 的，这能够确保您的内容的准确性。
+
+**AI Agent 支持**
+
+将内容同位放置 **减少了所需的上下文**，这非常适合大型语言模型 (LLM)。Intlayer 还附带一套工具，例如用于测试缺失翻译的 **CLI**、**[LSP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/lsp.md)**、**[MCP](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/mcp_server.md)** 以及 **[Agent Skills](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/agent_skills.md)**，旨在让 AI 代理的开发者体验 (DX) 变得更加顺畅。
+
+**自动化**
+
+使用您选择的 LLM 并在由您的 AI 提供商承担费用的情况下，通过自动化在您的 CI/CD 管道中进行翻译。Intlayer 还提供了一个 **编译器**，可自动提取内容；并配备了一个 [Web 平台](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md) 以帮助您 **在后台执行翻译**。
+
+**性能表现 (Performance)**
+
+将庞大的 JSON 文件连接到组件，可能会导致性能与响应式问题。Intlayer 会在构建时优化您的内容加载。
+
+**无需开发人员的规模化运作 (Scaling with non-dev)**
+
+Intlayer 不仅仅是一个简单的 i18n 解决方案。它还提供了一个 **支持自托管的[可视化编辑器](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_visual_editor.md)** 以及一个 **[完整的 CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/intlayer_CMS.md)**。借此，您可以 **实时** 管理多语言内容，并让译者、文案及其他团队成员之间的协作变得无缝。内容可以存储在本地和/或远程服务器上。

package/docs/zh/lsp.md

@@ -0,0 +1,351 @@
+---
+createdAt: 2025-06-07
+updatedAt: 2026-05-31
+title: Intlayer LSP 服务器
+description: 了解 Intlayer 语言服务器如何为所有支持的编辑器中的 useIntlayer、getIntlayer 和相关调用提供“转到定义”和其他 IDE 功能。
+keywords:
+  - LSP
+  - 语言服务器
+  - 转到定义
+  - IDE
+  - Intlayer
+  - VS Code
+  - Neovim
+  - TypeScript
+slugs:
+  - doc
+  - lsp
+history:
+  - version: 8.12.0
+    date: 2026-06-01
+    changes: "Release LSP"
+---
+
+# Intlayer LSP 服务器
+
+**Intlayer 语言服务器**是一个 [语言服务器协议 (LSP)](https://microsoft.github.io/language-server-protocol/) 实现，可通过感知 Intlayer 的智能来增强您的 IDE。它当前为字典键调用提供**转到定义**（Go to Definition），使您能够直接从组件中的 `useIntlayer("my-key")` 跳转到声明它的 `.content.ts` 文件。
+
+---
+
+## 为什么使用 LSP？
+
+当您使用 Intlayer 时，像 `useIntlayer("homepage")` 这样的调用与其在 `src/homepage.content.ts` 中的声明之间的连接是隐式的。如果没有工具，您必须手动搜索文件。LSP 使该链接显式化：
+
+**AI 智能助手感知**
+
+AI 编码助手（Cursor、Windsurf、GitHub Copilot、Claude Code、Codex）依赖语言服务器来解析符号并理解跨文件关系。运行 Intlayer LSP 后，助手可以追溯 `useIntlayer("key")` 到其声明，从而获得有关可用内容键、每个字典的形状以及要读取或编辑哪些文件的准确上下文。
+
+**转到定义**
+
+将光标放在支持的 getter 调用中的任何字典键字符串上，然后按 `F12`（或 `Cmd/Ctrl+单击`）。编辑器将打开内容声明文件，并将光标定位在 `key:` 行上。
+
+**合并字典支持**
+
+一个键可以分割在多个内容文件中（Intlayer 会合并它们）。服务器为每个源文件返回一个 `Location`，以便您可以导航到每个声明。
+
+**随处运行**
+
+支持所有 `*-intlayer` 包 (`next-intlayer`、`react-intlayer`、`vue-intlayer`、`svelte-intlayer`、`solid-intlayer`、`preact-intlayer`、`angular-intlayer`、`lit-intlayer`、`express-intlayer`、`hono-intlayer`、`fastify-intlayer`、`adonis-intlayer`、`intlayer`)。
+
+### 支持的 getter 调用
+
+服务器检测以下函数调用，并提取第一个字符串字面量参数作为字典键：
+
+| 函数          | 示例                          |
+| ------------- | ----------------------------- |
+| `useIntlayer` | `useIntlayer("hero")`         |
+| `getIntlayer` | `getIntlayer("hero", locale)` |
+
+TypeScript 泛型和额外参数将被忽略 —— 只有键字符串重要。
+
+> `useDictionary` 和 `getDictionary` 接受一个已导入的 `Dictionary` 对象作为其第一个参数，而不是字符串键，因此它们无法享受“转到定义”的好处，且不受服务器跟踪。
+
+---
+
+## 安装
+
+LSP 服务器作为 `@intlayer/lsp` 的一部分进行分发：
+
+```bash packageManager="npm"
+npm install --save-dev @intlayer/lsp
+```
+
+```bash packageManager="yarn"
+yarn add --dev @intlayer/lsp
+```
+
+```bash packageManager="pnpm"
+pnpm add --save-dev @intlayer/lsp
+```
+
+```bash packageManager="bun"
+bun add --dev @intlayer/lsp
+```
+
+该包公开了 `intlayer-lsp` 二进制文件，编辑器将其用作服务器可执行文件。
+
+---
+
+## 设置为 Claude Code 插件
+
+Intlayer LSP 可以作为直接托管在 Intlayer GitHub 仓库中的 **Claude Code 插件**使用。安装它可以让 Claude Code 对您所有的 `useIntlayer` / `getIntlayer` 调用具有原生的“转到定义”感知。
+
+### 1. 安装语言服务器二进制文件
+
+```bash packageManager="npm"
+npm install -g @intlayer/lsp
+```
+
+```bash packageManager="yarn"
+yarn global add @intlayer/lsp
+```
+
+```bash packageManager="pnpm"
+pnpm add -g @intlayer/lsp
+```
+
+这会将 `intlayer-lsp` 二进制文件放入您的 PATH 中，这是插件的 `lspServers` 条目所调用的。
+
+### 2. 注册 Intlayer 市场并安装插件
+
+```bash
+claude plugin marketplace add intlayer@github:aymericzip/intlayer
+claude plugin install intlayer-lsp@intlayer
+claude plugin enable intlayer-lsp@intlayer
+```
+
+Claude Code 将把 `"intlayer-lsp@intlayer": true` 添加到您的 `enabledPlugins` 中，并在支持的文件类型（`.ts`、`.tsx`、`.js`、`.jsx`、`.vue`、`.svelte`）上自动启动语言服务器。
+
+### 3. 启用 LSP 工具（如果尚未激活）
+
+某些 Claude Code 版本需要设置 LSP 功能标志。如果在安装后“转到定义”不起作用，请将以下内容添加到 `~/.claude/settings.json` 中：
+
+```json fileName="~/.claude/settings.json"
+{
+  "env": {
+    "ENABLE_LSP_TOOL": "1"
+  }
+}
+```
+
+重启 Claude Code —— 在导航 Intlayer 代码库时，它现在将使用 `goToDefinition`、`findReferences` 和其他 LSP 操作，而不是回退到 `grep`。
+
+---
+
+## 在 VS Code 中设置（通过扩展程序 —— 推荐）
+
+如果安装了 [Intlayer VS Code 扩展程序](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension)，语言服务器将自动启动。无需其他配置。
+
+> 有关安装和其他功能，请参阅 [VS Code 扩展程序文档](https://intlayer.org/doc/vs-code-extension)。
+
+---
+
+## 在 VS Code 中手动设置
+
+如果您没有使用 Intlayer 扩展程序，可以使用通用的 LSP 客户端扩展程序（例如 [**vscode-glspc**](https://marketplace.visualstudio.com/items?itemName=sibiraj-s.vscode-scss-formatter)）或通过编写您自己的小型扩展程序来手动连接语言服务器。推荐的方法是使用 Intlayer 扩展程序。
+
+作为参考，服务器通过 stdio 上的 `intlayer-lsp` 二进制文件启动：
+
+```json fileName=".vscode/settings.json"
+{
+  "intlayer.languageServer.command": "npx",
+  "intlayer.languageServer.args": ["@intlayer/lsp"]
+}
+```
+
+Intlayer 扩展程序读取这些设置以启动服务器。如果您仅依赖该扩展程序，则不需要手动设置。
+
+---
+
+## 在 Cursor 中设置
+
+[Cursor](https://www.cursor.com/) 是一个具有内置 AI 功能的 VS Code 分支。它使用相同的扩展生态系统，因此 **Intlayer VS Code 扩展程序**无需任何额外配置即可工作 —— 安装一次，Cursor 就会自动加载它。
+
+如果您更喜欢手动配置，Cursor 也会从工作区根目录读取 `.vscode/settings.json`，因此上面的 VS Code 代码片段直接适用。
+
+---
+
+## 在 Windsurf 中设置
+
+[Windsurf](https://windsurf.com/)（由 Codeium 提供）是另一个基于 VS Code 的编辑器。从 VS Code 市场安装 Intlayer 扩展程序，语言服务器将自动激活，就像在 VS Code 和 Cursor 中一样。
+
+对于手动配置，在项目根目录下创建 `.vscode/settings.json`：
+
+```json fileName=".vscode/settings.json"
+{
+  "intlayer.languageServer.command": "npx",
+  "intlayer.languageServer.args": ["@intlayer/lsp"]
+}
+```
+
+---
+
+## 在 Zed 中设置
+
+[Zed](https://zed.dev/) 通过其语言设置具有原生的 LSP 支持。在您的 Zed 用户设置中添加一个条目（`~/.config/zed/settings.json`）：
+
+```json fileName="~/.config/zed/settings.json"
+{
+  "lsp": {
+    "intlayer-lsp": {
+      "binary": {
+        "path": "npx",
+        "arguments": ["--yes", "@intlayer/lsp"]
+      }
+    }
+  },
+  "languages": {
+    "TypeScript": {
+      "language_servers": ["intlayer-lsp", "..."]
+    },
+    "TSX": {
+      "language_servers": ["intlayer-lsp", "..."]
+    },
+    "JavaScript": {
+      "language_servers": ["intlayer-lsp", "..."]
+    },
+    "Vue.js": {
+      "language_servers": ["intlayer-lsp", "..."]
+    },
+    "Svelte": {
+      "language_servers": ["intlayer-lsp", "..."]
+    }
+  }
+}
+```
+
+`"..."` 占位符告诉 Zed 将其默认的语言服务器与 Intlayer 的语言服务器一起保留。
+
+---
+
+## 设置 AI 智能助手命令行界面（Claude Code、Codex 等）
+
+**Claude Code** 具有一流的 LSP 插件支持 —— 遵循上面的 [Claude Code 插件设置](#设置为-claude-code-插件)以直接在您的终端会话中获得完整的“转到定义”体验。
+
+**OpenAI Codex** 和其他基于终端的工具尚不能充当 LSP 客户端 —— 它们直接读取和写入文件，而不是维护持久的语言服务器会话。对于这些工具，运行 LSP 的价值是间接带来的：当服务器在伴侣编辑器（VS Code、Cursor、Windsurf……）中激活时，编辑器的实时索引可供任何能够通过编辑器提供的上下文（例如，Cursor Composer、Windsurf Cascade、GitHub Copilot Chat）查询它的 AI 助手使用。
+
+如果您完全在终端中工作且没有打开编辑器，则可以在后台启动语言服务器，以便它为以后连接到同一工作区的任何编辑器做好准备：
+
+```bash
+# 在后台保持服务器运行
+npx @intlayer/lsp &
+```
+
+---
+
+## 在 Neovim 中手动设置
+
+使用 [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig)，注册自定义服务器配置：
+
+```lua fileName="~/.config/nvim/init.lua"
+local lspconfig = require('lspconfig')
+local configs = require('lspconfig.configs')
+
+if not configs.intlayer_lsp then
+  configs.intlayer_lsp = {
+    default_config = {
+      -- 使用 npx 启动服务器，因此您不需要全局安装
+      cmd = { 'npx', '--yes', '@intlayer/lsp' },
+      filetypes = {
+        'typescript',
+        'typescriptreact',
+        'javascript',
+        'javascriptreact',
+        'vue',
+        'svelte',
+      },
+      root_dir = lspconfig.util.root_pattern(
+        'intlayer.config.ts',
+        'intlayer.config.js',
+        'package.json'
+      ),
+    },
+  }
+end
+
+lspconfig.intlayer_lsp.setup({})
+```
+
+重启 Neovim 后，在 Intlayer 键上按 `gd` 将调用“转到定义”。
+
+---
+
+## 在其他编辑器中手动设置
+
+任何支持语言服务器协议的编辑器都可以使用 `@intlayer/lsp`。服务器：
+
+- **传输** – Node.js IPC / stdio (标准)
+- **可执行文件** – `npx @intlayer/lsp` (或本地安装的 `intlayer-lsp` 二进制文件)
+- **能力** – `definitionProvider: true`, `textDocumentSync: Incremental`
+
+请参阅您的编辑器 LSP 文档以获取确切的配置格式（例如，[coc.nvim](https://github.com/neoclide/coc.nvim) 的 `languageserver.json`，或 [Helix](https://helix-editor.com) 中的 LSP 客户端设置）。
+
+### 示例：coc.nvim
+
+```json fileName="~/.config/nvim/coc-settings.json"
+{
+  "languageserver": {
+    "intlayer": {
+      "command": "npx",
+      "args": ["@intlayer/lsp"],
+      "filetypes": [
+        "typescript",
+        "typescriptreact",
+        "javascript",
+        "javascriptreact",
+        "vue",
+        "svelte"
+      ],
+      "rootPatterns": [
+        "intlayer.config.ts",
+        "intlayer.config.js",
+        "package.json"
+      ]
+    }
+  }
+}
+```
+
+### 示例：Helix
+
+```toml fileName="~/.config/helix/languages.toml"
+[[language]]
+name = "typescript"
+language-servers = ["intlayer-lsp", "typescript-language-server"]
+
+[[language]]
+name = "tsx"
+language-servers = ["intlayer-lsp", "typescript-language-server"]
+
+[language-server.intlayer-lsp]
+command = "npx"
+args = ["@intlayer/lsp"]
+```
+
+---
+
+## 工作原理
+
+当服务器启动时，它会使用 `getConfiguration()` 从工作区根目录解析 Intlayer 配置。这为它提供了查找已编译字典所需的 `build` 和 `system` 路径。
+
+在每个**转到定义**请求上：
+
+1. 服务器读取打开文档的全文。
+2. 它使用正则表达式扫描获取器调用（`useIntlayer`、`getIntlayer` 等）。
+3. 它检查光标位置是否落在这些调用之一的内部。
+4. 如果是，它将提取字典键（正则表达式的捕获组 3），并调用 `getUnmergedDictionaries()` 来定位声明该键的每个内容文件。
+5. 它读取每个匹配的文件，并找到包含 `key: "<key>"` 的确切行，以精确地定位光标。
+6. 它返回一个 `Location` 对象数组 —— 每个源文件一个。
+
+配置会被懒惰地解析并在每个会话中缓存；它在每个 `initialize` 请求（例如，当您打开一个新的工作区文件夹时）重置。
+
+---
+
+## 故障排除
+
+| 症状                     | 可能的原因       | 解决方法                                                    |
+| ------------------------ | ---------------- | ----------------------------------------------------------- |
+| 转到定义不起作用         | 服务器未运行     | 检查是否已安装 `@intlayer/lsp` 且编辑器正在启动它           |
+| 检测到错误的工作区根目录 | 多个工作区文件夹 | 确保包含 `intlayer.config.ts` 的文件夹是第一个工作区文件夹  |
+| 找不到键的定义           | 配置未解析       | 验证工作区根目录下是否存在 `intlayer.config.ts`（或 `.js`） |
+| 服务器在启动时崩溃       | Node.js 版本太旧 | 需要 Node.js ≥ 14.18                                        |

package/docs/zh/releases/v8.md

@@ -46,7 +46,7 @@ Intlayer v8 对富内容的处理方式进行了重大改进，引入了 **HTML
 我们为 Markdown 和 HTML 节点引入了 `.use()` 方法。此方法允许你自定义渲染过程中使用的 HTML 标签或组件。
 
 - **组件替换**：你可以轻松地将 HTML 标签或自定义组件替换为你自己的框架组件（例如，将 `<a>` 替换为 `NextLink`，或将 `<CustomCmp>` 替换为 React 组件）。
-- **类型安全**：所有提供组件的函数都是完全类型化的，确保你接收到正确的 props。
+- **类型安全**：所有提供组件的函数都是完全类型化 (fully typed)的，确保你接收到正确的 props。
 
 ### 默认渲染行为
 
@@ -754,7 +754,7 @@ export default {
 
 ## 内容 Schema 验证
 
-Intlayer v8 为字典引入了 schema 验证。你现在可以在配置中使用 Zod 定义可重用的验证 schema，并将其应用到你的内容文件中。这可以确保你的内容始终遵循预期的结构，并在构建时捕获错误。
+Intlayer v8 为字典引入了 schema 验证。你现在可以在配置中使用 Zod 定义可重用的验证 schema，并将其应用到你的内容文件中。这可以确保你的内容始终遵循预期的结构，并在构建时 (build time)捕获错误。
 
 ### 1. 定义 Schemas
 
@@ -1062,7 +1062,7 @@ Intlayer v8 为 Markdown 和 HTML 编译器引入了新的缓存层。这确保
 
 ### 模式
 
-- **`static`**（默认）：dictionary 在构建时被打包。性能最佳。
+- **`static`**（默认）：dictionary 在构建时 (build time)被打包。性能最佳。
 - **`dynamic`**：dictionary 在运行时加载（例如，通过 JSON fetch 或 suspense）。
 - **`fetch`**：dictionary 在运行时从 CMS/服务器 获取并同步。
 

package/docs/zh/roadmap.md

@@ -108,7 +108,7 @@ Intlayer 提供多种方法来插入和管理动态内容，确保内容交付
 
    Intlayer 允许将内容声明为函数，支持同步和异步内容获取。
 
-   同步函数：内容在构建时动态生成。
+   同步函数：内容在构建时 (build time)动态生成。
 
    异步函数：动态从外部来源（如 API、数据库）获取数据。