From ba80d4d9c12efc606cc115485bbd1b4168b7e077 Mon Sep 17 00:00:00 2001
From: groupguanfang <1203970284@qq.com>
Date: Tue, 22 Jul 2025 19:58:05 +0800
Subject: [PATCH 1/7] feat: add zh-cn translation (home page, core-concepts)

---
 astro.config.ts                               | 16 +++++-
 .../core-concepts/embedded-languages.mdx      | 12 +++++
 .../docs/zh-cn/core-concepts/volar-labs.mdx   | 26 +++++++++
 .../docs/zh-cn/core-concepts/why-volar.mdx    | 10 ++++
 src/content/docs/zh-cn/index.mdx              | 53 +++++++++++++++++++
 5 files changed, 115 insertions(+), 2 deletions(-)
 create mode 100644 src/content/docs/zh-cn/core-concepts/embedded-languages.mdx
 create mode 100644 src/content/docs/zh-cn/core-concepts/volar-labs.mdx
 create mode 100644 src/content/docs/zh-cn/core-concepts/why-volar.mdx
 create mode 100644 src/content/docs/zh-cn/index.mdx

diff --git a/astro.config.ts b/astro.config.ts
index 8834a22..51e0235 100644
--- a/astro.config.ts
+++ b/astro.config.ts
@@ -34,10 +34,11 @@ export default defineConfig({
       sidebar: [
         {
           label: "Core Concepts",
+          translations: { 'zh-CN': '核心概念' },
           items: [
             // Each item here is one entry in the navigation menu.
-            { label: "Why Volar?", link: "/core-concepts/why-volar" },
-            { label: "Embedded Languages", link: "/core-concepts/embedded-languages" },
+            { label: "Why Volar?", link: "/core-concepts/why-volar", translations: { 'zh-CN': '为什么选择 Volar?' } },
+            { label: "Embedded Languages", link: "/core-concepts/embedded-languages", translations: { 'zh-CN': '嵌入式语言' } },
             { label: "Volar Labs", link: "/core-concepts/volar-labs" },
           ],
           // TODO: Use `autogenerate` once it allows you to order the sidebar
@@ -54,6 +55,17 @@ export default defineConfig({
           autogenerate: { directory: "reference" },
         },
       ],
+      defaultLocale: 'en',
+      locales: {
+        en: {
+          label: 'English',
+          lang: 'en-US',
+        },
+        'zh-cn': {
+          label: '简体中文',
+          lang: 'zh-CN',
+        }
+      }
     }),
   ],
 });
diff --git a/src/content/docs/zh-cn/core-concepts/embedded-languages.mdx b/src/content/docs/zh-cn/core-concepts/embedded-languages.mdx
new file mode 100644
index 0000000..d28bd11
--- /dev/null
+++ b/src/content/docs/zh-cn/core-concepts/embedded-languages.mdx
@@ -0,0 +1,12 @@
+---
+title: 嵌入式语言
+description: VolarJS 对嵌入式语言提供了顶级支持，并可以大大简化在文件不同部分之间实现编辑功能所需的映射。
+---
+
+如今，许多编程语言都是由其他编程语言组成的。最著名的例子是 HTML, 在其中你会发现 JavaScript 和 CSS 分别位于 `<script>` 和 `<style>` 块中。除了这些，你甚至可以在 HTML 元素的 `style` 属性中找到一些内联 CSS, 在 HTML 元素的 `onclick`（和其他事件）属性中找到一些内联 JavaScript。
+
+实际上，这种行为的例子相当多，尤其是在 Web 上：[Vue 的单文件组件](https://vuejs.org/guide/scaling-up/sfc.html) 中不同的 Block, [Svelte 组件](https://svelte.dev/docs/svelte-components) 中的部分，[Astro 组件](https://docs.astro.build/en/core-concepts/astro-components/) 中的前置语法和基于 JSX 的组件模板，[Markdown](https://spec.commonmark.org/0.29/#fenced-code-blocks) 中的不同块（更不用说常见的 YAML 前置语法）, 等等。
+
+因此, Volar 是基于这样一个原则构建的: 你的语言很可能会有这样的嵌入式语言, 并且对它们提供了顶级支持。值得注意的是, Volar 可以大大简化在文件不同部分之间实现编辑功能所需的映射。
+
+**如果你的语言没有嵌入式语言：这完全没问题！** Volar 仍然可以很好地为你工作，并且如果有一天你决定向你的语言添加嵌入式语言，它将随时准备好。
diff --git a/src/content/docs/zh-cn/core-concepts/volar-labs.mdx b/src/content/docs/zh-cn/core-concepts/volar-labs.mdx
new file mode 100644
index 0000000..29ff77a
--- /dev/null
+++ b/src/content/docs/zh-cn/core-concepts/volar-labs.mdx
@@ -0,0 +1,26 @@
+---
+title: Volar Labs
+description: Volar Labs 是一个 vscode 扩展，用于帮助你调试基于 Volar 的语言服务器和客户端。
+---
+
+有一个通用的框架来构建编辑器工具有很多好处。它允许我们共享代码，允许我们共享知识，最重要的是，它允许我们分享构建编辑器工具的痛苦。
+
+那些恼人的时刻，你的映射偏移了一位，或者你不确定哪些文件被包含在你的项目中，或者你的生成的虚拟代码中有语法错误。我们都知道这些时刻，如果你不知道，你可能很快就会知道。
+
+Volar Labs 是一个 VS Code 扩展，用于帮助你调试基于 Volar 的语言服务器和客户端。**它是为那些制作编辑器工具的人提供的编辑器工具。**
+
+![一张 Volar Labs 的截图，显示了正在检查的文件不同部分之间的映射](../core-concepts/volar-labs-1.png)
+
+## 安装
+
+Volar Labs 可以在 VS Code Marketplace 中找到。你可以通过在 VS Code 的扩展选项卡中搜索 `volarjs-labs` 来安装它，或者通过 [点击这里](https://marketplace.visualstudio.com/items?itemName=johnsoncodehk.volarjs-labs) 来安装。
+
+## 功能
+
+- **列出 Volar 服务器** - 查看在你的 VS Code 实例中运行的所有 Volar 服务器。
+- **检查项目** - 查看包含在你的项目中的文件。
+- **检查虚拟文件** - 查看由你的服务器生成的虚拟源代码。
+- **虚拟源映射** - 查看虚拟源代码与原始源代码之间的映射。
+- **TS 内存使用情况** - 查看 TypeScript 使用了多少内存。
+- ... 更多！
+
diff --git a/src/content/docs/zh-cn/core-concepts/why-volar.mdx b/src/content/docs/zh-cn/core-concepts/why-volar.mdx
new file mode 100644
index 0000000..2304c4f
--- /dev/null
+++ b/src/content/docs/zh-cn/core-concepts/why-volar.mdx
@@ -0,0 +1,10 @@
+---
+title: 为什么选择 Volar?
+description: 介绍 Volar 的优势, 以及为什么你会想要使用它。
+---
+
+在过去的几年中，程序员越来越依赖他们的代码编辑器来提供有用的上下文信息和代码提示。悬停信息、诊断和自动补全等功能现在已经成为用户理所当然的期望，无论他们使用什么编程语言。
+
+然而，实现这些功能不仅不是一项简单的任务，而且通常也不是语言和框架作者的优先事项。即使你有时间和资源来实现这些功能，正确地做到这一点也很困难，需要相当多领域的知识，并且可能需要花费大量时间来维护。
+
+**Volar 旨在通过处理所有繁重的工作来解决这个问题。** Volar 为你提供了构建出色编辑体验所需的所有工具，而无需担心细节问题，这样你就可以专注于最重要的事情：让你的语言或框架变得更棒!
\ No newline at end of file
diff --git a/src/content/docs/zh-cn/index.mdx b/src/content/docs/zh-cn/index.mdx
new file mode 100644
index 0000000..62af9ba
--- /dev/null
+++ b/src/content/docs/zh-cn/index.mdx
@@ -0,0 +1,53 @@
+---
+title: Volar
+description: VolarJS 是一个现代嵌入式语言工具框架，旨在简化编辑器语言支持的开发。
+template: splash
+hero:
+  tagline: 嵌入式语言工具框架。
+  image:
+    file: ../../../assets/logo.svg
+  actions:
+    - text: 为什么选择Volar?
+      link: /zh-cn/core-concepts/why-volar
+      icon: right-arrow
+      variant: primary
+    - text: 入门项目
+      link: https://github.com/volarjs/starter
+      icon: right-arrow
+      variant: secondary
+    - text: 在 GitHub 上查看
+      link: https://github.com/volarjs
+      icon: external
+      variant: minimal
+---
+
+import Sponsors from "$components/Sponsors.astro";
+import { Card, CardGrid } from "@astrojs/starlight/components";
+import TeamMemberList from "$components/TeamMemberList.astro";
+import ModifyHeader from "$components/ModifyHeader.astro";
+
+<ModifyHeader />
+
+## Sponsors
+
+<Sponsors />
+
+<div class="card-cnt not-content">
+  <CardGrid stagger={true}>
+    <Card title="性能" icon="rocket">
+      专为性能而设计。从第一天起, Volar 就以性能为设计理念。
+    </Card>
+    <Card title="成熟" icon="rocket">
+      Volar 为数百万用户使用的工具提供支持, 例如 Vue、Astro 和 MDX 语言服务器, 最终下载总量超过 700 万次。
+    </Card>
+    <Card title="灵活" icon="puzzle">
+      Volar 被设计为可以灵活使用。它可以在任何编辑器中使用, 并支持任何语言。
+    </Card>
+  </CardGrid>
+</div>
+
+## 团队
+
+Volar 是由一群充满热情的开发者构建的，他们致力于为开发者提供最好的工具。
+
+<TeamMemberList />

From 8ccfed512c1ad817dac3ad58c4e98455902a8f93 Mon Sep 17 00:00:00 2001
From: groupguanfang <1203970284@qq.com>
Date: Tue, 22 Jul 2025 20:04:52 +0800
Subject: [PATCH 2/7] feat: change en-US as root language

---
 astro.config.ts | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/astro.config.ts b/astro.config.ts
index 51e0235..953458e 100644
--- a/astro.config.ts
+++ b/astro.config.ts
@@ -55,9 +55,8 @@ export default defineConfig({
           autogenerate: { directory: "reference" },
         },
       ],
-      defaultLocale: 'en',
       locales: {
-        en: {
+        root: {
           label: 'English',
           lang: 'en-US',
         },

From 8a51abf0daa291b7680b9310dbe47aa110fe838e Mon Sep 17 00:00:00 2001
From: groupguanfang <1203970284@qq.com>
Date: Tue, 22 Jul 2025 20:06:23 +0800
Subject: [PATCH 3/7] feat: move volar-lab-1.png to assets folder

---
 .../docs/core-concepts => assets}/volar-labs-1.png  | Bin
 src/content/docs/core-concepts/volar-labs.mdx       |   2 +-
 src/content/docs/zh-cn/core-concepts/volar-labs.mdx |   2 +-
 3 files changed, 2 insertions(+), 2 deletions(-)
 rename src/{content/docs/core-concepts => assets}/volar-labs-1.png (100%)

diff --git a/src/content/docs/core-concepts/volar-labs-1.png b/src/assets/volar-labs-1.png
similarity index 100%
rename from src/content/docs/core-concepts/volar-labs-1.png
rename to src/assets/volar-labs-1.png
diff --git a/src/content/docs/core-concepts/volar-labs.mdx b/src/content/docs/core-concepts/volar-labs.mdx
index 31c76cd..d1c4440 100644
--- a/src/content/docs/core-concepts/volar-labs.mdx
+++ b/src/content/docs/core-concepts/volar-labs.mdx
@@ -9,7 +9,7 @@ Those pesky times where your mappings are off by one, or you're not sure what fi
 
 Volar Labs is a VS Code extension to help you debug your Volar-powered language server and client. **It's the editor tooling for the people who make the editor tooling.**
 
-![A screenshot of Volar Labs, showing the mappings between the different parts of a file being inspected](./volar-labs-1.png)
+![A screenshot of Volar Labs, showing the mappings between the different parts of a file being inspected](../../../assets/volar-labs-1.png)
 
 ## Installation
 
diff --git a/src/content/docs/zh-cn/core-concepts/volar-labs.mdx b/src/content/docs/zh-cn/core-concepts/volar-labs.mdx
index 29ff77a..303a7a8 100644
--- a/src/content/docs/zh-cn/core-concepts/volar-labs.mdx
+++ b/src/content/docs/zh-cn/core-concepts/volar-labs.mdx
@@ -9,7 +9,7 @@ description: Volar Labs 是一个 vscode 扩展，用于帮助你调试基于 Vo
 
 Volar Labs 是一个 VS Code 扩展，用于帮助你调试基于 Volar 的语言服务器和客户端。**它是为那些制作编辑器工具的人提供的编辑器工具。**
 
-![一张 Volar Labs 的截图，显示了正在检查的文件不同部分之间的映射](../core-concepts/volar-labs-1.png)
+![一张 Volar Labs 的截图，显示了正在检查的文件不同部分之间的映射](../../../../assets/volar-labs-1.png)
 
 ## 安装
 

From 3240138f8242ff641855d5a6d1ba19f3dc78b23d Mon Sep 17 00:00:00 2001
From: groupguanfang <1203970284@qq.com>
Date: Wed, 23 Jul 2025 02:42:49 +0800
Subject: [PATCH 4/7] feat: add translations for sidebar

---
 astro.config.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/astro.config.ts b/astro.config.ts
index 953458e..d811caf 100644
--- a/astro.config.ts
+++ b/astro.config.ts
@@ -45,13 +45,15 @@ export default defineConfig({
         },
         {
           label: "Guides",
+          translations: { 'zh-CN': '指南' },
           items: [
-            { label: "Your First Volar Language Server", link: "/guides/first-server" },
-            { label: "File Structure", link: "/guides/file-structure" },
+            { label: "Your First Volar Language Server", link: "/guides/first-server", translations: { 'zh-CN': '你的第一个 Volar 语言服务器' } },
+            { label: "File Structure", link: "/guides/file-structure", translations: { 'zh-CN': '文件结构' } },
           ],
         },
         {
           label: "Reference",
+          translations: { 'zh-CN': '参考' },
           autogenerate: { directory: "reference" },
         },
       ],

From cb66b39a3e736b9b6bcb92b7bd7e471bb8f98918 Mon Sep 17 00:00:00 2001
From: groupguanfang <1203970284@qq.com>
Date: Wed, 23 Jul 2025 02:45:36 +0800
Subject: [PATCH 5/7] feat: add zh-cn translations for guides

---
 .../docs/zh-cn/guides/file-structure.mdx      |  63 ++
 .../docs/zh-cn/guides/first-server.mdx        | 575 ++++++++++++++++++
 2 files changed, 638 insertions(+)
 create mode 100644 src/content/docs/zh-cn/guides/file-structure.mdx
 create mode 100644 src/content/docs/zh-cn/guides/first-server.mdx

diff --git a/src/content/docs/zh-cn/guides/file-structure.mdx b/src/content/docs/zh-cn/guides/file-structure.mdx
new file mode 100644
index 0000000..13e38b2
--- /dev/null
+++ b/src/content/docs/zh-cn/guides/file-structure.mdx
@@ -0,0 +1,63 @@
+---
+title: Volar 项目的文件结构
+description: 一个 Volar 项目文件结构的指南。
+---
+
+本指南将向您展示 Volar 项目的组织方式以及项目中不同文件的作用。
+
+## 文件和目录结构
+
+由于需要多个包来运行语言服务器和 VS Code 扩展，Volar 项目通常位于 monorepo 中。这不是一个要求，但它是最常见的设置，也是设置 Volar 项目的推荐方式。
+
+### 服务器 (`packages/language-server`)
+
+与语言服务器相关的所有文件都位于 `packages/language-server` 目录中。
+
+- `package.json` — 语言服务器包的配置，包括其依赖项和主入口点。
+- `bin/server.js` — 语言服务器二进制文件的入口点。此文件负责启动语言服务器。
+- `src/index.ts` — 语言服务器的主文件，设置服务器及其功能。
+- `src/language.ts` — 定义语言功能并提供处理项目文件的方法。
+
+### 客户端 (`packages/vscode`)
+
+与 VS Code 扩展相关的所有文件都位于 `packages/vscode` 目录中。
+
+- `package.json` — VS Code 扩展包的配置，包括其依赖项、主入口点和激活事件。
+- `src/extension.ts` — VS Code 扩展的主文件，设置客户端并激活功能。
+- `scripts/build.js` — 用于构建 VS Code 扩展的脚本。
+
+## 完整示例
+
+您的 Volar 项目在大多数情况下将类似于以下内容：
+
+import { FileTree } from "@astrojs/starlight/components";
+
+<FileTree>
+
+- .vscode/
+  - launch.json
+  - tasks.json
+- packages/
+  - language-server/
+    - bin/
+      - server.js
+    - src/
+      - index.ts
+      - ...
+    - package.json
+    - tsconfig.json
+  - vscode/
+    - scripts/
+      - build.js
+    - src/
+      - extension.ts
+      - ...
+    - .vscodeignore
+    - package.json
+    - tsconfig.json
+- package.json
+- tsconfig.json
+
+</FileTree>
+
+一些通用文件，例如 `README.md`，为了简洁起见被省略了。
diff --git a/src/content/docs/zh-cn/guides/first-server.mdx b/src/content/docs/zh-cn/guides/first-server.mdx
new file mode 100644
index 0000000..2ecf27a
--- /dev/null
+++ b/src/content/docs/zh-cn/guides/first-server.mdx
@@ -0,0 +1,575 @@
+---
+title: 创建你的第一个 Volar 语言服务器
+description: 本指南将教你如何创建一个简单的 Volar 语言服务器。
+---
+
+> 这个页面正在编写中。想要为它贡献一些文档, 或者想要改进它吗？[在 GitHub 上编辑这个页面](https://github.com/volarjs/docs/blob/main/src/content/docs/guides/first-server.mdx)
+
+import { Tabs, TabItem, Aside, FileTree } from "@astrojs/starlight/components";
+
+在这个指南中, 你将学习如何创建一个简单的 Volar 语言服务器和 VS Code 客户端。为了保持简单, 这个语言将看起来非常像 HTML, 尽管有一个小变化: 只允许一个 `<style>` 标签。这个语言将被称为 `HTML1`。
+
+这个指南假设你对 TypeScript 和 Node.js 有基本的了解, 并且对什么是语言服务器有一定的了解。如果你不熟悉语言服务器, 你可能想要在继续之前阅读 [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) 首页上的“什么是语言服务器协议？”部分。
+
+> 💡 想要直接克隆模版项目吗？查看 GitHub 上的 [starter project](https://github.com/volarjs/starter) 。
+
+## 先决条件
+
+- [Visual Studio Code](https://code.visualstudio.com/) v1.55 或以上版本.
+- [Node.js](https://nodejs.org/en/) v14 或以上版本.
+- 对 JavaScript 和 Node.js 的基本了解.
+- （可选）为 VS Code 安装 [Volar Labs](https://volarjs.dev/core-concepts/volar-labs/) 扩展.
+
+## 开始
+
+首先创建一个新的项目目录并初始化一个新的 Node.js 项目: 
+
+<Tabs>
+<TabItem label="npm">
+
+```sh
+# 使用 npm 创建一个新项目
+npm init
+```
+
+</TabItem>
+<TabItem label="pnpm">
+
+```sh
+# 使用 pnpm 创建一个新项目
+pnpm init
+```
+
+</TabItem>
+<TabItem label="Yarn">
+
+```sh
+# 使用 Yarn 创建一个新项目
+yarn init .
+```
+
+</TabItem>
+</Tabs>
+
+为了能够在同一个仓库中同时拥有语言服务器和 VS Code 客户端, [语言服务器的常见模式](/guides/file-structure)是创建一个新的 `packages` 目录来包含这两个部分, 这实际上就是所谓的 monorepo (多包仓库)。
+
+<Tabs>
+<TabItem label="npm">
+
+```sh
+# 使用 npm 创建一个新 monorepo 项目
+npm init -w ./packages/server
+npm init -w ./packages/client
+```
+
+</TabItem>
+<TabItem label="pnpm">
+
+```sh
+# 使用 pnpm 创建一个新 monorepo 项目
+mkdir -p ./packages/server ./packages/client
+echo -e 'packages:\n  - "packages/*"' > pnpm-workspace.yaml
+# 进入 packages 中新创建的两个文件夹并运行 `pnpm init`
+```
+
+</TabItem>
+<TabItem label="Yarn">
+
+```sh
+# 使用 Yarn 创建一个新 monorepo 项目
+yarn init -w ./packages/server
+yarn init -w ./packages/client
+```
+
+</TabItem>
+</Tabs>
+
+<Aside type="note">
+下面假定你将客户端命名为 `vscode-html1`, 服务器端命名为 `@html1/language-server`。
+
+你可以根据自己的喜好命名它们, 但请确保在后续操作中相应地调整指南中的内容。
+
+</Aside>
+
+### 安装和配置 TypeScript
+
+在本指南的后面部分, 将使用 TypeScript 来编写语言服务器和客户端, 并将 TypeScript 代码编译为 JavaScript, 因此我们现在将其安装。
+
+<Tabs>
+<TabItem label="npm">
+
+```sh
+# 使用 npm 安装 TypeScript
+npm install --save-dev typescript
+```
+
+</TabItem>
+<TabItem label="pnpm">
+
+```sh
+# 使用 pnpm 安装 TypeScript
+pnpm add --save-dev typescript
+```
+
+</TabItem>
+<TabItem label="Yarn">
+
+```sh
+# 使用 Yarn 安装 TypeScript
+yarn add --dev typescript
+```
+
+</TabItem>
+</Tabs>
+
+此外, 我们将创建一个基础的 TypeScript 配置文件, 该文件将在服务器和客户端之间共享。此文件将用于设置两个项目部分的共同 TypeScript 编译器选项。
+
+```json title="tsconfig.base.json"
+{
+  "compilerOptions": {
+    "module": "nodenext"
+  }
+}
+```
+
+### 定义 VS Code 任务
+
+最后, 在项目根目录中创建一个 `.vscode` 目录, 并向其中添加一个 `launch.json` 文件。此文件定义了 [一个任务](https://code.visualstudio.com/docs/editor/tasks#_typescript-hello-world), 可以在后续轻松启动扩展。
+
+```json title=".vscode/launch.json"
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Launch Extension",
+      "type": "extensionHost",
+      "request": "launch",
+      "runtimeExecutable": "${execPath}",
+      "args": [
+        "--disable-updates",
+        "--disable-workspace-trust",
+        "--profile-temp",
+        "--skip-release-notes",
+        "--skip-welcome",
+        "--extensionDevelopmentPath=${workspaceFolder}/packages/client"
+      ],
+      "outFiles": ["${workspaceFolder}/packages/client/dist/*.js"]
+    }
+  ]
+}
+```
+
+当所有这些完成后, 你的项目结构应该如下所示: 
+
+<FileTree>
+
+- .vscode/
+  - launch.json
+- packages/
+  - client/
+    - package.json
+  - server/
+    - package.json
+- package.json
+- tsconfig.base.json
+
+</FileTree>
+
+## 创建客户端
+
+客户端将是一个 VS Code 扩展, 这需要 [一个 `package.json` 文件, 包含一些特定字段](https://code.visualstudio.com/api/references/extension-manifest)。在 `packages/client` 文件夹中, 编辑 `package.json` 文件, 使其如下所示: 
+
+```json title="packages/client/package.json"
+{
+  "name": "vscode-html1",
+  "displayName": "HTML1 Client",
+  "description": "A VS Code extension for HTML1.",
+  "version": "0.0.1",
+  "engines": {
+    "vscode": "^1.55.0"
+  },
+  "activationEvents": ["onLanguage:html1"],
+  "main": "./src/extension.js",
+  "contributes": {
+    "languages": [
+      {
+        "id": "html1",
+        "extensions": [".html1"]
+      }
+    ]
+  }
+}
+```
+
+此外, 还需要一些来自 Volar 和 VS Code 的依赖项。确保你在正确的文件夹中（`packages/client`）, 并通过运行以下命令安装依赖项: 
+
+<Tabs>
+<TabItem label="npm">
+
+```sh
+# 使用 npm 安装依赖项
+npm install @volar/language-server @volar/vscode vscode-languageclient @types/vscode ../server
+```
+
+</TabItem>
+<TabItem label="pnpm">
+
+```sh
+# 使用 pnpm 安装依赖项
+pnpm install @volar/language-server @volar/vscode vscode-languageclient @types/vscode ../server
+```
+
+</TabItem>
+<TabItem label="Yarn">
+
+```sh
+# 使用 Yarn 安装依赖项
+yarn add @volar/language-server @volar/vscode vscode-languageclient @types/vscode ../server
+```
+
+</TabItem>
+</Tabs>
+
+下一步, 在 `packages/client` 文件夹中创建一个 `tsconfig.json` 文件来配置 TypeScript, 这将在本指南中用作构建工具。此文件将告诉 TypeScript 将编译后的 JavaScript 文件输出到 `out` 目录。
+
+如前所述, 这个文件会继承之前在项目根目录创建的 `tsconfig.base.json` 基础配置。
+
+```jsonc title="packages/client/tsconfig.json"
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "out",
+    "rootDir": "src",
+  },
+  "include": ["src"],
+}
+```
+
+然后, 在 `packages/client` 文件夹中创建一个新的 `src` 目录, 并向其中添加一个新的 `extension.ts` 文件。此文件将包含客户端扩展的代码。
+
+这段代码的大部分都是用于启动语言服务器的样板代码, 虽然看起来内容很多且不太有趣, 但它对于扩展的正常运行至关重要。
+
+```ts title="packages/client/src/extension.ts"
+import * as serverProtocol from "@volar/language-server/protocol";
+import { activateAutoInsertion, createLabsInfo } from "@volar/vscode";
+import * as vscode from "vscode";
+import * as lsp from "vscode-languageclient/node";
+
+let client: lsp.BaseLanguageClient;
+
+// 如其名称所示, 此函数在扩展被激活时调用。
+export async function activate(context: vscode.ExtensionContext) {
+  const serverModule = vscode.Uri.joinPath(
+    context.extensionUri,
+    "node_modules",
+    "@html1/language-server",
+    "dist",
+    "server.js",
+  );
+  const serverOptions: lsp.ServerOptions = {
+    run: {
+      module: serverModule.fsPath,
+      transport: lsp.TransportKind.ipc,
+      options: { execArgv: <string[]>[] },
+    },
+    debug: {
+      module: serverModule.fsPath,
+      transport: lsp.TransportKind.ipc,
+      options: { execArgv: ["--nolazy", "--inspect=" + 6009] },
+    },
+  };
+
+  // 用于控制语言客户端的选项, 这里我们只关注 HTML1 文件。
+  // 语言服务器也可以接受初始化选项, 这些选项会在服务器启动时传递, 
+  // 但这里我们没有需要传递的内容。
+  const clientOptions: lsp.LanguageClientOptions = {
+    documentSelector: [{ language: "html1" }],
+    initializationOptions: {},
+  };
+
+  // 使用我们定义的所有选项, 创建语言客户端, 并启动它。
+  client = new lsp.LanguageClient(
+    "html1-language-server",
+    "HTML1 Language Server",
+    serverOptions,
+    clientOptions,
+  );
+  await client.start();
+
+  // 额外的: 为自动插入闭合标签提供支持（例如: <div> -> <div></div>）
+  activateAutoInsertion("html1", client);
+
+  // 添加该代码以添加对 Volar Labs 的支持
+  // https://volarjs.dev/core-concepts/volar-labs/
+  const labsInfo = createLabsInfo(serverProtocol);
+  labsInfo.addLanguageClient(client);
+  return labsInfo.extensionExports;
+}
+
+// ... 当扩展被停用时会调用此函数！
+export function deactivate(): Thenable<any> | undefined {
+  return client?.stop();
+}
+```
+
+<Aside type="note">
+你可能会注意到, 上面的代码导入了 `vscode`, 尽管并没有安装它。这是因为 `vscode` 模块是由 VS Code 本身提供的, 并且默认对扩展可用。
+
+有关此模块及其内容的更多信息, 请查看 [VS Code API 文档](https://code.visualstudio.com/api/references/vscode-api)。
+
+</Aside>
+
+现在客户端已经完成。由于绝大多数实际逻辑将在语言服务器中, 因此即使随着项目复杂性的增长, 您也不太可能需要再次访问客户端。
+
+你的项目结构现在应该是这样的: 
+
+<FileTree>
+
+- .vscode/
+  - launch.json
+- packages/
+  - client/
+    - src/
+      - extension.ts
+    - package.json
+    - tsconfig.json
+  - server/
+    - package.json
+- package.json
+- tsconfig.base.json
+
+</FileTree>
+
+如果你非常好奇, 你可以通过在 VS Code 中运行 `Launch Extension` 任务来立即启动客户端。
+
+由于服务器尚不存在, 因此客户端将无法启动并立即崩溃, 但这将是我们的一个开始！
+
+## 服务器
+
+现在进入项目的核心部分: 语言服务器。本节的大部分内容将花费在连接各个部分上, 而不是编写实际的逻辑。实际的逻辑将非常简单, 因为我们支持的语言也相当简单。
+
+首先, 我们将安装一些依赖项, 就像我们为客户端所做的那样。确保您在正确的文件夹（`packages/server`）中, 并运行以下命令: 
+
+<Tabs>
+<TabItem label="npm">
+
+```sh
+# 使用 npm 安装依赖项
+npm install @volar/language-server @volar/language-core @volar/language-service volar-service-html volar-service-css vscode-html-languageservice
+```
+
+</TabItem>
+
+<TabItem label="pnpm">
+
+```sh
+# 使用 pnpm 安装依赖项
+pnpm install @volar/language-server @volar/language-core @volar/language-service volar-service-html volar-service-css vscode-html-languageservice
+```
+
+</TabItem>
+
+<TabItem label="Yarn">
+
+```sh
+# 使用 yarn 安装依赖项
+yarn add @volar/language-server @volar/language-core @volar/language-service volar-service-html volar-service-css vscode-html-languageservice
+```
+
+</TabItem>
+</Tabs>
+
+与客户端一样, 在 `packages/server` 文件夹中创建一个 `tsconfig.json` 文件以配置 TypeScript。此文件将告诉 TypeScript 将编译后的 JavaScript 文件输出到 `dist` 目录。
+
+```jsonc title="packages/server/tsconfig.json"
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "out",
+    "rootDir": "src",
+  },
+  "include": ["src"],
+}
+```
+
+由于语言服务器是可执行程序, 我们需要为服务器创建一个入口点。在 `packages/server` 文件夹中创建一个新的 `bin` 目录, 并添加一个名为 `html1-language-server.js` 的文件。
+
+这个文件将包含一小段代码, 用于启动语言服务器。
+
+```ts title="packages/server/bin/html1-language-server.js"
+#!/usr/bin/env node
+if (process.argv.includes("--version")) {
+  const pkgJSON = require("../package.json");
+  console.log(`${pkgJSON["version"]}`);
+} else {
+  require("../out/index.js");
+}
+```
+
+我们还将更新 `packages/server` 文件夹中的 `package.json` 文件, 以将此文件添加为包提供的可执行文件。
+
+```jsonc title="packages/server/package.json" ins={4-6}
+{
+  "name": "@html1/language-server",
+  "version": "0.0.1",
+  "bin": {
+    "html1-language-server": "./bin/html1-language-server.js",
+  },
+  "dependencies": {
+    // All your dependencies here...
+  },
+}
+```
+
+zh: 现在, 安装您的软件包的人将能够使用 `html1-language-server` 命令运行服务器。另外, 我们还可以通过运行 `html1-language-server --version` 来打印服务器的版本号。
+
+然而, 我们仍然没有实际可以启动的服务器！在 `packages/server` 文件夹中创建一个新的 `src` 目录, 并创建以下三个文件: 
+
+- `index.ts`: 服务器的入口点, 该文件将创建、配置和启动服务器。
+- `html1-service.ts`: 处理 HTML1 语言的 [服务](/reference/services/)。
+- `languagePlugin.ts`: HTML1 语言的 [语言定义](/reference/languages/)。
+
+此时, 您的整个项目结构应如下所示: 
+
+<FileTree>
+
+- .vscode/
+  - launch.json
+- packages/
+  - client/
+    - src/
+      - extension.ts
+    - package.json
+    - tsconfig.json
+  - server/
+    - bin/
+      - html1-language-server.js
+    - src/
+      - index.ts
+      - html1-service.ts
+      - languagePlugin.ts
+    - package.json
+    - tsconfig.json
+- package.json
+- tsconfig.base.json
+
+</FileTree>
+
+### 配置服务器
+
+我们将首先跳转到 `index.ts` 文件。该文件将创建服务器, 配置所有支持的语言和将要使用的不同服务, 然后启动服务器。
+
+```ts title="packages/server/src/index.ts"
+import { html1LanguagePlugin, Html1Code } from "./languagePlugin";
+import { create as createHtmlService } from "volar-service-html";
+import { create as createCssService } from "volar-service-css";
+import {
+  createServer,
+  createConnection,
+  createSimpleProject,
+} from "@volar/language-server/node";
+
+const connection = createConnection();
+const server = createServer(connection);
+
+connection.listen();
+
+connection.onInitialize((params) => {
+  return server.initialize(
+    params,
+    createSimpleProject([
+      // 语言插件, 目前为空
+    ]),
+    [
+      createHtmlService(),
+      createCssService(),
+    ],
+  );
+});
+
+connection.onInitialized(server.initialized);
+connection.onShutdown(server.shutdown);
+```
+
+首先, 我们创建一个连接（`createConnection`）, 然后创建服务器本身。接着, 我们监听连接, 等待客户端连接。
+
+一旦连接完成, 我们初始化服务器, 包括其语言和服务插件。在我们的例子中, 我们还没有任何语言插件, 但我们确实有两个服务插件: 一个用于 HTML, 一个用于 CSS, 这两种语言都是我们的 HTML1 语言将支持的。
+
+### 定义语言
+
+顾名思义, 我们需要定义我们支持的语言。在我们的例子中, 这就是 HTML1。作为提醒, HTML1 是 HTML, 但限制为仅允许一个 `<style>` 标签（此外, 它没有 `script` 标签, 但我们暂时忽略这一点）。
+
+语言定义的核心只是一个 JavaScript 对象, 具有两个方法: 一个用于创建虚拟代码, 一个用于更新它。虚拟代码（`VirtualCode`）是一个表示语言服务器中文件的对象, 用于存储有关文件的信息, 例如其内容、当前版本以及可能有用的任何其他元数据。
+
+每个语言服务器处理的文件都将具有一个对应的 `VirtualCode` 对象。语言服务器将在文件打开时创建这些对象, 并在文件更改时更新它们。
+
+```ts title="packages/server/src/languagePlugin.ts"
+import type { LanguagePlugin } from "@volar/language-core";
+import type { URI } from "vscode-uri";
+
+export const language = {
+  getLanguageId(uri) {
+    if (uri.path.endsWith('.html1')) {
+      return 'html1';
+    }
+  },
+  createVirtualCode(uri, languageId, snapshot) {
+    // 在这里创建虚拟代码对象
+  },
+  updateVirtualCode(uri, languageCode, snapshot) {
+    // 更新虚拟代码对象时会被调用
+  },
+} satisfies LanguagePlugin<URI>;
+```
+
+虽然 `VirtualCode` 对象可以是普通的 JavaScript 对象, 但通常创建一个 JavaScript 类来表示它们是有用的。这个类可以包含处理文件及其相关数据时有用的方法和属性。
+
+```ts title="packages/server/src/languagePlugin.ts" ins={3, 12-14, 17-18, 22-99} ins=/(VirtualCode) }/
+import type { LanguagePlugin, VirtualCode } from "@volar/language-core";
+import type { URI } from "vscode-uri";
+import type * as ts from 'typescript';
+
+export const language = {
+  getLanguageId(uri) {
+    if (uri.path.endsWith('.html1')) {
+      return 'html1';
+    }
+  },
+  createVirtualCode(uri, languageId, snapshot) {
+    if (languageId === "html1") {
+      return new Html1Code(snapshot);
+    }
+  },
+  updateVirtualCode(uri, languageCode, snapshot) {
+    languageCode.update(snapshot);
+    return languageCode;
+  },
+} satisfies LanguagePlugin<URI>;
+
+export class Html1Code implements VirtualCode {
+  id = "root";
+  languageId = "html1";
+  embeddedCodes: VirtualCode[] = [];
+
+  constructor(public snapshot: ts.IScriptSnapshot) {
+    this.onSnapshotUpdated();
+  }
+
+  public update(newSnapshot: ts.IScriptSnapshot) {
+    this.snapshot = newSnapshot;
+    this.onSnapshotUpdated();
+  }
+
+  public onSnapshotUpdated() {
+    // 在这里处理快照更新逻辑
+  }
+}
+```
+
+这个方法将包含在文件更新时执行的所有逻辑。在我们的例子中, 我们将使用此方法来解析文件并理解其结构和内容。
+
+你可能已经注意到 `Html1Code` 类有一个 `embeddedCodes` 属性。这个属性用于存储文件可能包含的 [嵌入式语言](/core-concepts/embedded-languages) 的任何嵌入式 `VirtualCode`。
+
+在我们的例子中, HTML1 将包含两种嵌入式语言: HTML 和 CSS。要找到这些嵌入式语言的位置, 我们需要解析文件并查找 `<style>` 标签。当我们找到它时, 我们将为 HTML 和 CSS 代码创建一个新的 `VirtualCode` 对象, 并将其添加到 `embeddedCodes` 数组中。
+
+我们将使用 `vscode-html-languageservice` 包来解析 HTML 和 CSS 代码, 这个包也是我们之前添加到服务器的 HTML 服务所使用的。

From 528f5fccfbf60d6429a5cb32586f9d05ae8234c7 Mon Sep 17 00:00:00 2001
From: groupguanfang <1203970284@qq.com>
Date: Wed, 23 Jul 2025 02:52:37 +0800
Subject: [PATCH 6/7] feat: add zh-cn translations for reference

---
 .../docs/zh-cn/reference/languages.mdx        | 126 ++++++++
 src/content/docs/zh-cn/reference/services.mdx | 279 ++++++++++++++++++
 2 files changed, 405 insertions(+)
 create mode 100644 src/content/docs/zh-cn/reference/languages.mdx
 create mode 100644 src/content/docs/zh-cn/reference/services.mdx

diff --git a/src/content/docs/zh-cn/reference/languages.mdx b/src/content/docs/zh-cn/reference/languages.mdx
new file mode 100644
index 0000000..c42d1d3
--- /dev/null
+++ b/src/content/docs/zh-cn/reference/languages.mdx
@@ -0,0 +1,126 @@
+---
+title: 语言
+---
+
+> 这个页面正在编写中。想要为它贡献一些文档，或者想要改进它？[在 GitHub 上编辑这个页面](https://github.com/volarjs/docs/blob/main/src/content/docs/reference/languages.mdx)
+
+作为一个语言服务器框架, Volar 允许您定义要在项目中支持的语言。
+
+## 语言定义的形状
+
+语言定义是一个包含 `createVirtualCode` 和 `updateVirtualCode` 函数的 JavaScript 对象。
+
+```ts title="src/my-language.ts"
+export const language = {
+	createVirtualCode(fileId, languageId, snapshot) {
+		// 创建一个虚拟代码对象
+	},
+	updateVirtualCode(_fileId, languageCode, snapshot) {
+		// 更新虚拟代码对象
+	},
+};
+```
+
+正如名称所示，这些方法创建和更新虚拟代码 `VirtualCode`。为每个语言服务器处理的文件创建一个 `VirtualCode` 对象。然后可以在提供语言服务器功能的 [services](/reference/services) 的钩子中访问这些对象，因此它们也是存储有关文件的附加信息的地方，这些信息可能对服务的功能很有用。
+
+虽然不是必须的，但一个常见的模式是定义一个实现 `VirtualCode` 接口的 JavaScript 类，这样可以更方便地为虚拟代码对象添加更多属性和方法，并且可以使用 `instanceof` 来检查虚拟代码对象是否属于某个类型。
+
+```ts title="src/my-language.ts"
+import type { LanguagePlugin, VirtualCode } from '@volar/language-core';
+
+export const language = {
+	createVirtualCode(fileId, languageId, snapshot) {
+		if (languageId !== 'my-language')
+			return;
+
+		return new MyLanguageVirtualCode(snapshot);
+	},
+	updateVirtualCode(_fileId, languageCode, snapshot) {
+		languageCode.update(snapshot);
+		return languageCode;
+	},
+} satisfies LanguagePlugin<MyLanguageVirtualCode>;
+
+export class MyLanguageVirtualCode implements VirtualCode {
+	id = 'root';
+	languageId = 'my-language';
+	mappings = []
+
+	constructor(
+		public snapshot: ts.IScriptSnapshot
+	) {
+		this.onSnapshotUpdated();
+	}
+
+	public update(newSnapshot: ts.IScriptSnapshot) {
+		this.snapshot = newSnapshot;
+		this.onSnapshotUpdated();
+	}
+
+	onSnapshotUpdated() {
+		// Update the virtual code object
+	}
+}
+```
+
+这是一个语言定义的简单示例，其中 `MyVirtualLanguageCode` 仅执行严格的最小操作。在实际的语言定义中，您很可能会在 `MyLanguageVirtualCode` 类上拥有更多的属性和方法。
+
+### 嵌入式语言
+
+如果您的语言支持 [嵌入式语言](/zh-cn/core-concepts/embedded-languages/)，则您的实例 `VirtualCode` 应该包含一个 `embeddedCodes` 属性，该属性包含嵌入式语言的 `VirtualCode` 实例数组。
+
+```ts title="src/my-language.ts" ins={20, 34-52} collapse={1-14, 22-31}
+import type { LanguagePlugin, VirtualCode } from '@volar/language-core';
+
+export const language = {
+	createVirtualCode(fileId, languageId, snapshot) {
+		if (languageId !== 'my-language')
+			return;
+
+		return new MyLanguageVirtualCode(snapshot);
+	},
+	updateVirtualCode(_fileId, languageCode, snapshot) {
+		languageCode.update(snapshot);
+		return languageCode;
+	},
+} satisfies LanguagePlugin<MyLanguageVirtualCode>;
+
+export class MyLanguageVirtualCode implements VirtualCode {
+	id = 'root';
+	languageId = 'my-language';
+	mappings = []
+	embeddedCodes: VirtualCode[] = []
+
+	constructor(
+		public snapshot: ts.IScriptSnapshot
+	) {
+		this.onSnapshotUpdated();
+	}
+
+	public update(newSnapshot: ts.IScriptSnapshot) {
+		this.snapshot = newSnapshot;
+		this.onSnapshotUpdated();
+	}
+
+	onSnapshotUpdated() {
+		const snapshotContent = this.snapshot.getText(0, this.snapshot.getLength());
+
+		// Find embedded languages
+		const embeddedLanguages = findEmbeddedLanguages(snapshotContent);
+
+		// Create virtual code objects for embedded languages
+		this.embeddedCodes = embeddedLanguages.map(embeddedLanguage => {
+			return {
+				id: embeddedLanguage.id,
+				languageId: embeddedLanguage.languageId,
+				mappings: [],
+				snapshot: {
+						getText: (start, end) => embeddedLanguage.content.substring(start, end),
+						getLength: () => embeddedLanguage.content.length,
+						getChangeRange: () => undefined,
+					}
+			}
+		});
+	}
+}
+```
diff --git a/src/content/docs/zh-cn/reference/services.mdx b/src/content/docs/zh-cn/reference/services.mdx
new file mode 100644
index 0000000..8a2cbc3
--- /dev/null
+++ b/src/content/docs/zh-cn/reference/services.mdx
@@ -0,0 +1,279 @@
+---
+title: 服务
+description: 列出 VolarJS 中所有可用服务的列表, 以及它们的功能。
+---
+
+服务是 Volar 语言服务器的构建块。它们负责提供您在语言服务器中所期望的所有功能，包括补全、诊断、悬停信息等。
+
+虽然服务在技术上并不与单个语言绑定，但它们通常被设计为与特定语言或文件类型一起使用，包括 [嵌入式语言](/core-concepts/embedded-languages)。
+
+例如，如果您要为 HTML 实现一个 Volar 语言服务器，您可能最终会得到三个不同的服务，一个用于一般的 HTML 支持，一个用于 CSS 支持，一个用于 JavaScript 支持，后两个分别用于 `<style>` 和 `<script>` 标签。
+
+## 服务的结构
+
+服务是一个 JavaScript 对象，其唯一必需的属性是 `create` 方法。`create` 方法在服务初始化时被调用，它应该返回一个包含实现服务各种功能的方法的对象。
+
+这些方法在 Volar 语言服务器需要执行特定任务时被调用，例如提供补全或诊断。这些方法几乎完全映射到 [语言服务器协议](https://microsoft.github.io/language-server-protocol/) (LSP) 请求，例如 `textDocument/completion` 变为 `provideCompletionItems`，`textDocument/hover` 变为 `provideHover`，等等。
+
+```ts title="service.ts"
+export const service = {
+	name: 'my-service', // 服务的名称, 用于在日志和 Volar Labs 中标识服务。
+	create(context): ServicePluginInstance {
+		return {
+			provideHover(document, position, token) {
+				// 在这里实现悬停支持
+			},
+			// 更多方法...
+		};
+	},
+} satisfies ServicePlugin;
+```
+
+## 使用服务
+
+在初始化语言服务器时，使用的服务列表作为选项传递给 `initialize` 方法。
+
+```ts title="server.ts"
+import {
+  createConnection,
+  createServer,
+  createSimpleProjectProviderFactory,
+} from "@volar/language-server/node";
+import { service } from "./service";
+
+const connection = createConnection();
+const server = createServer(connection);
+
+connection.listen();
+
+connection.onInitialize((params) => {
+  return server.initialize(params, createSimpleProjectProviderFactory(), {
+    // ...
+    getServicePlugins() {
+      return [service];
+    },
+  });
+});
+
+connection.onInitialized(() => {
+  server.initialized();
+});
+```
+
+## 第一方服务支持
+
+Volar 团队维护了一些可以在您的 Volar 语言服务器中使用的第一方服务。这些服务应该涵盖绝大多数常见用例，例如为 HTML、CSS、JSON、JavaScript 等提供补全、诊断、悬停信息等，或与 Emmett、Prettier 等知名工具集成。
+
+要查看所有第一方服务的列表，请参阅 [volarjs/services](https://github.com/volarjs/services) 存储库。
+
+## 方法参考
+
+### `provideCompletionItems`
+
+**方法签名:** `(document: TextDocument, position: Position, token: CancellationToken) => CompletionItem[] | Promise<CompletionItem[]>`
+
+当用户在文档的特定位置请求补全时，将调用此方法。
+
+```ts title="service.ts"
+import { CompletionItemKind } from '@volar/language-server';
+
+export const service = {
+	name: 'my-service',
+	create(context): ServicePluginInstance {
+		return {
+			provideCompletionItems(document, position, token) {
+				return {
+					isIncomplete: true,
+					items: [
+						{
+							label: 'Hello',
+							kind: CompletionItemKind.Text,
+							isIncomplete: false
+						},
+						{
+							label: 'World',
+							kind: CompletionItemKind.Text,
+							isIncomplete: false
+						},
+					]
+				}
+			},
+		};
+	},
+} satisfies ServicePlugin;
+```
+
+### `resolveCompletionItem`
+
+**方法签名:** `(item: CompletionItem, token: CancellationToken) => CompletionItem | Promise<CompletionItem>`
+
+当用户从补全列表中选择一个补全项时，将调用此方法。它允许您为所选的补全项提供额外的信息。这通常在计算补全的完整信息很昂贵时使用，您希望推迟到用户实际选择特定补全时再进行计算。
+
+### `provideCodeActions`
+
+**方法签名:** `(document: TextDocument, range: Range, context: CodeActionContext, token: CancellationToken) => CodeAction[] | Promise<CodeAction[]>`
+
+当用户请求文档中特定范围的代码操作时，将调用此方法。代码操作通常用于修复问题或改善代码（例如“提取方法”、“添加缺失的导入”）。
+
+### `resolveCodeAction`
+
+**方法签名:** `(action: CodeAction, token: CancellationToken) => CodeAction | Promise<CodeAction>`
+
+当用户从代码操作列表中选择一个代码操作时，将调用此方法。它允许您为所选的代码操作提供额外的信息。
+
+### `provideHover`
+
+**方法签名:** `(document: TextDocument, position: Position, token: CancellationToken) => Hover | Promise<Hover>`
+
+当用户请求文档中特定位置的悬停信息时，将调用此方法。
+
+### `provideSignatureHelp`
+
+**方法签名:** `(document: TextDocument, position: Position, token: CancellationToken) => SignatureHelp | Promise<SignatureHelp>`
+
+当用户请求文档中特定位置的签名帮助时，将调用此方法。
+
+### `provideDefinition`
+
+**方法签名:** `(document: TextDocument, position: Position, token: CancellationToken) => Location | Location[] | Promise<Location | Location[]>`
+
+当用户请求文档中特定位置的符号定义时，将调用此方法。此方法为“转到定义”等功能提供支持。
+
+### `provideReferences`
+
+**方法签名:** `(document: TextDocument, position: Position, context: ReferenceContext, token: CancellationToken) => Location[] | Promise<Location[]>`
+
+当用户请求文档中特定位置的符号引用时，将调用此方法。此方法为“查找所有引用”等功能提供支持。
+
+### `provideDocumentHighlights`
+
+**方法签名:** `(document: TextDocument, position: Position, token: CancellationToken) => DocumentHighlight[] | Promise<DocumentHighlight[]>`
+
+当用户请求文档中特定位置的符号高亮时，将调用此方法。
+
+### `provideDocumentSymbols`
+
+**方法签名:** `(document: TextDocument, token: CancellationToken) => SymbolInformation[] | Promise<SymbolInformation[]>`
+
+当用户请求文档中的符号时，将调用此方法。
+
+
+### `provideCodeLens`
+
+**方法签名:** `(document: TextDocument, token: CancellationToken) => CodeLens[] | Promise<CodeLens[]>`
+
+当用户请求文档中的代码镜头时，将调用此方法。
+
+### `resolveCodeLens`
+
+**方法签名:** `(codeLens: CodeLens, token: CancellationToken) => CodeLens | Promise<CodeLens>`
+
+当用户从代码镜头列表中选择一个代码镜头时，将调用此方法。它允许您为所选的代码镜头提供额外的信息。
+
+### `provideDocumentFormattingEdits`
+
+**方法签名:** `(document: TextDocument, options: FormattingOptions, token: CancellationToken) => TextEdit[] | Promise<TextEdit[]>`
+
+当用户请求对整个文档进行格式化时，将调用此方法。
+
+### `provideDocumentRangeFormattingEdits`
+
+**方法签名:** `(document: TextDocument, range: Range, options: FormattingOptions, token: CancellationToken) => TextEdit[] | Promise<TextEdit[]>`
+
+当用户请求对文档中特定范围进行格式化时，将调用此方法。
+
+### `provideOnTypeFormattingEdits`
+
+**方法签名:** `(document: TextDocument, position: Position, ch: string, options: FormattingOptions, token: CancellationToken) => TextEdit[] | Promise<TextEdit[]>`
+
+当用户在文档中输入特定字符时，将调用此方法。
+
+### `provideRenameEdits`
+
+**方法签名:** `(document: TextDocument, position: Position, newName: string, token: CancellationToken) => WorkspaceEdit | Promise<WorkspaceEdit>`
+
+当用户请求对文档中特定位置的符号进行重命名时，将调用此方法。
+
+### `provideDocumentLinks`
+
+**方法签名:** `(document: TextDocument, token: CancellationToken) => DocumentLink[] | Promise<DocumentLink[]>`
+
+当用户请求文档中的链接时，将调用此方法。
+
+### `resolveDocumentLink`
+
+**方法签名:** `(link: DocumentLink, token: CancellationToken) => DocumentLink | Promise<DocumentLink>`
+
+当用户从链接列表中选择一个链接时，将调用此方法。它允许您为所选的链接提供额外的信息。
+
+### `provideDocumentColors`
+
+**方法签名:** `(document: TextDocument, token: CancellationToken) => ColorInformation[] | Promise<ColorInformation[]>`
+
+当用户请求文档中的颜色时，将调用此方法。
+
+### `provideColorPresentations`
+
+**方法签名:** `(color: Color, document: TextDocument, range: Range, token: CancellationToken) => ColorPresentation[] | Promise<ColorPresentation[]>`
+
+当用户从颜色列表中选择一个颜色时，将调用此方法。它允许您为所选的颜色提供额外的信息。
+
+### `provideFoldingRanges`
+
+**方法签名:** `(document: TextDocument, context: FoldingContext, token: CancellationToken) => FoldingRange[] | Promise<FoldingRange[]>`
+
+当用户请求文档中的折叠范围时，将调用此方法。
+
+### `provideSelectionRanges`
+
+**方法签名:** `(document: TextDocument, positions: Position[], token: CancellationToken) => SelectionRange[] | Promise<SelectionRange[]>`
+
+当用户请求文档中特定位置的选择范围时，将调用此方法。
+
+### `provideDocumentSemanticTokens`
+
+**方法签名:** `(document: TextDocument, token: CancellationToken) => SemanticTokens | Promise<SemanticTokens>`
+
+当用户请求文档中的语义标记时，将调用此方法。
+
+### `provideDocumentSemanticTokensEdits`
+
+**方法签名:** `(document: TextDocument, previousResultId: string, token: CancellationToken) => SemanticTokens | SemanticTokensEdits | Promise<SemanticTokens | SemanticTokensEdits>`
+
+当用户请求文档中的语义标记编辑时，将调用此方法。
+
+### `provideLinkedEditingRanges`
+
+**方法签名:** `(document: TextDocument, position: Position, token: CancellationToken) => LinkedEditingRanges | Promise<LinkedEditingRanges>`
+
+当用户请求文档中特定位置的联动编辑范围时，将调用此方法。
+
+### `provideCallHierarchyItems`
+
+**方法签名:** `(document: TextDocument, position: Position, token: CancellationToken) => CallHierarchyItem[] | Promise<CallHierarchyItem[]>`
+
+当用户请求文档中特定位置的符号的调用层次结构项时，将调用此方法。
+
+### `provideCallHierarchyIncomingCalls`
+
+**方法签名:** `(document: TextDocument, position: Position, token: CancellationToken) => CallHierarchyIncomingCall[] | Promise<CallHierarchyIncomingCall[]>`
+
+当用户请求文档中特定位置的符号的入站调用时，将调用此方法。
+
+### `provideCallHierarchyOutgoingCalls`
+
+**方法签名:** `(document: TextDocument, position: Position, token: CancellationToken) => CallHierarchyOutgoingCall[] | Promise<CallHierarchyOutgoingCall[]>`
+
+当用户请求文档中特定位置的符号的出站调用时，将调用此方法。
+
+### `provideInlayHints`
+
+**方法签名:** `(document: TextDocument, token: CancellationToken) => InlayHint[] | Promise<InlayHint[]>`
+
+当用户请求文档中的内联提示时，将调用此方法。
+
+### `resolveInlayHint`
+
+**方法签名:** `(hint: InlayHint, token: CancellationToken) => InlayHint | Promise<InlayHint>`
+
+当用户从内联提示列表中选择一个内联提示时，将调用此方法。它允许您为所选的内联提示提供额外的信息。

From a7a4b24aee3722d8522235bbe0bafc68a2aadefc Mon Sep 17 00:00:00 2001
From: groupguanfang <1203970284@qq.com>
Date: Wed, 23 Jul 2025 03:14:52 +0800
Subject: [PATCH 7/7] feat: add zh-cn translation for `SiteTitle.astro`

---
 src/components/starlight/SiteTitle.astro | 22 ++++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/src/components/starlight/SiteTitle.astro b/src/components/starlight/SiteTitle.astro
index e6612ce..e546d30 100644
--- a/src/components/starlight/SiteTitle.astro
+++ b/src/components/starlight/SiteTitle.astro
@@ -3,9 +3,19 @@ import type { Props } from "@astrojs/starlight/props";
 import AstrolightSiteTitle from "@astrojs/starlight/components/SiteTitle.astro";
 
 const menuItems = [
-  { name: "Docs", href: "/core-concepts/why-volar" },
-  { name: "Blog", href: "/blog" },
+  { 
+    name: { 'en-US': "Docs", 'zh-CN': '文档' },
+    id: 'docs',
+    href: { 'en-US': "/core-concepts/why-volar", 'zh-CN': "/zh-cn/core-concepts/why-volar" }
+  },
+  { 
+    name: { 'en-US': "Blog", 'zh-CN': '博客' },
+    id: 'blog',
+    href: { 'en-US': "/blog", 'zh-CN': "/blog" }
+  },
 ];
+type DefinedI18nName = keyof typeof menuItems[number]['name']
+type DefinedHref = keyof typeof menuItems[number]['href'];
 
 function pathsMatch(pathA: string, pathB: string): boolean {
   return pathB.includes(pathA);
@@ -21,14 +31,14 @@ function pathsMatch(pathA: string, pathB: string): boolean {
     {
       menuItems.map((menuItem) => (
         <a
-          href={menuItem.href}
+          href={menuItem.href[Astro.currentLocale as DefinedHref] || menuItem.href['en-US']}
           aria-current={
-            (pathsMatch(encodeURI(menuItem.href), Astro.url.pathname) ||
-              (menuItem.name === "Docs" && Astro.props.hasSidebar)) &&
+            (pathsMatch(encodeURI(menuItem.href[Astro.currentLocale as DefinedHref] || menuItem.href['en-US']), Astro.url.pathname) ||
+              (menuItem.id === "Docs" && Astro.props.hasSidebar)) &&
             "page"
           }
         >
-          <span>{menuItem.name}</span>
+          <span>{menuItem.name[Astro.currentLocale as DefinedI18nName] || menuItem.name['en-US']}</span>
         </a>
       ))
     }