@intlayer/docs 8.11.2 → 8.11.3

package/docs/vi/lsp.md

@@ -0,0 +1,351 @@
+---
+createdAt: 2025-06-07
+updatedAt: 2026-05-31
+title: Máy chủ Intlayer LSP
+description: Tìm hiểu cách Máy chủ Ngôn ngữ Intlayer cung cấp tính năng Đi tới Định nghĩa (Go-to-Definition) và các tính năng IDE khác cho useIntlayer, getIntlayer và các lệnh gọi liên quan trên tất cả các trình soạn thảo được hỗ trợ.
+keywords:
+  - LSP
+  - Máy chủ Ngôn ngữ
+  - Đi tới Định nghĩa
+  - IDE
+  - Intlayer
+  - VS Code
+  - Neovim
+  - TypeScript
+slugs:
+  - doc
+  - lsp
+history:
+  - version: 8.12.0
+    date: 2026-06-01
+    changes: "Release LSP"
+---
+
+# Máy chủ Intlayer LSP
+
+**Máy chủ Ngôn ngữ Intlayer (LSP)** là một triển khai của [Giao thức Máy chủ Ngôn ngữ (LSP)](https://microsoft.github.io/language-server-protocol/) nhằm nâng cao IDE của bạn bằng trí thông minh nhận biết cấu trúc Intlayer. Hiện tại, máy chủ cung cấp tính năng **Đi tới Định nghĩa (Go to Definition)** cho các lệnh gọi khóa từ điển, cho phép bạn nhảy trực tiếp từ `useIntlayer("my-key")` trong thành phần của mình sang tệp `.content.ts` khai báo khóa đó.
+
+---
+
+## Tại sao nên sử dụng LSP?
+
+Khi bạn sử dụng Intlayer, kết nối giữa một lệnh gọi như `useIntlayer("homepage")` và khai báo của nó trong `src/homepage.content.ts` là ẩn định. Nếu không có công cụ, bạn phải tìm kiếm tệp theo cách thủ công. LSP làm cho liên kết đó trở nên rõ ràng:
+
+**Nhận thức của tác nhân AI**
+
+Các tác nhân lập trình AI (Cursor, Windsurf, GitHub Copilot, Claude Code, Codex) dựa vào máy chủ ngôn ngữ để giải quyết các ký hiệu và hiểu mối quan hệ chéo giữa các tệp. Khi Intlayer LSP đang chạy, các tác nhân có thể đi theo lệnh gọi `useIntlayer("key")` trở lại khai báo của nó, mang lại cho chúng ngữ cảnh chính xác về các khóa nội dung có sẵn, cấu trúc của từng từ điển và tệp nào cần đọc hoặc chỉnh sửa.
+
+**Đi tới Định nghĩa**
+
+Đặt con trỏ của bạn lên bất kỳ chuỗi khóa từ điển nào bên trong lệnh gọi getter được hỗ trợ và nhấn `F12` (hoặc `Cmd/Ctrl+Click`). Trình soạn thảo sẽ mở tệp khai báo nội dung và đặt con trỏ vào dòng `key:`.
+
+**Hỗ trợ từ điển được gộp**
+
+Một khóa có thể được chia ra ở nhiều tệp nội dung khác nhau (Intlayer sẽ gộp chúng lại). Máy chủ trả về một vị trí (`Location`) trên mỗi tệp nguồn để bạn có thể điều hướng đến từng khai báo.
+
+**Hoạt động ở mọi nơi**
+
+Hỗ trợ tất cả các gói `*-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`).
+
+### Các lệnh gọi getter được hỗ trợ
+
+Máy chủ phát hiện các lệnh gọi hàm sau và trích xuất đối số chuỗi ký tự đầu tiên làm khóa từ điển:
+
+| Hàm           | Ví dụ                         |
+| ------------- | ----------------------------- |
+| `useIntlayer` | `useIntlayer("hero")`         |
+| `getIntlayer` | `getIntlayer("hero", locale)` |
+
+Các generic của TypeScript và các đối số bổ sung đều bị bỏ qua — chỉ chuỗi khóa mới quan trọng.
+
+> `useDictionary` và `getDictionary` nhận một đối tượng `Dictionary` đã được nhập làm đối số đầu tiên của chúng thay vì một khóa chuỗi, do đó chúng không được hưởng lợi từ tính năng Đi tới Định nghĩa và không được theo dõi bởi máy chủ.
+
+---
+
+## Cài đặt
+
+Máy chủ LSP được phân phối như một phần của `@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
+```
+
+Gói này cung cấp tệp nhị phân `intlayer-lsp`, được trình soạn thảo sử dụng làm tệp thực thi của máy chủ.
+
+---
+
+## Thiết lập như một Plugin Claude Code
+
+Intlayer LSP có sẵn dưới dạng **plugin Claude Code** được lưu trữ trực tiếp trong kho lưu trữ GitHub của Intlayer. Việc cài đặt nó giúp Claude Code có nhận thức gốc về tính năng Đi tới Định nghĩa cho tất cả các lệnh gọi `useIntlayer` / `getIntlayer` của bạn.
+
+### 1. Cài đặt tệp nhị phân máy chủ ngôn ngữ
+
+```bash packageManager="npm"
+npm install -g @intlayer/lsp
+```
+
+```bash packageManager="yarn"
+yarn global add @intlayer/lsp
+```
+
+```bash packageManager="pnpm"
+pnpm add -g @intlayer/lsp
+```
+
+Thao tác này sẽ đặt tệp nhị phân `intlayer-lsp` vào biến môi trường PATH của bạn, đây là tệp được gọi bởi mục `lspServers` trong plugin.
+
+### 2. Đăng ký thị trường Intlayer và cài đặt plugin
+
+```bash
+claude plugin marketplace add intlayer@github:aymericzip/intlayer
+claude plugin install intlayer-lsp@intlayer
+claude plugin enable intlayer-lsp@intlayer
+```
+
+Claude Code sẽ thêm `"intlayer-lsp@intlayer": true` vào danh sách `enabledPlugins` của bạn và tự động khởi động máy chủ ngôn ngữ trên các loại tệp được hỗ trợ (`.ts`, `.tsx`, `.js`, `.jsx`, `.vue`, `.svelte`).
+
+### 3. Bật công cụ LSP (nếu chưa hoạt động)
+
+Một số phiên bản Claude Code yêu cầu cờ tính năng LSP phải được đặt. Thêm nội dung sau vào tệp `~/.claude/settings.json` của bạn nếu tính năng Đi tới Định nghĩa không hoạt động sau khi cài đặt:
+
+```json fileName="~/.claude/settings.json"
+{
+  "env": {
+    "ENABLE_LSP_TOOL": "1"
+  }
+}
+```
+
+Khởi động lại Claude Code — từ giờ nó sẽ sử dụng `goToDefinition`, `findReferences` và các thao tác LSP khác khi điều hướng cơ sở mã Intlayer của bạn thay vì sử dụng `grep`.
+
+---
+
+## Thiết lập trong VS Code (thông qua tiện ích mở rộng — khuyến nghị)
+
+Nếu bạn đã cài đặt [tiện ích mở rộng Intlayer VS Code](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension), máy chủ ngôn ngữ sẽ tự động bắt đầu. Không cần cấu hình thêm.
+
+> Xem [tài liệu tiện ích mở rộng VS Code](https://intlayer.org/doc/vs-code-extension) để biết cách cài đặt và các tính năng khác.
+
+---
+
+## Thiết lập thủ công trong VS Code
+
+Nếu bạn không sử dụng tiện ích mở rộng Intlayer, bạn có thể kết nối máy chủ ngôn ngữ theo cách thủ công bằng cách sử dụng một tiện ích mở rộng ứng dụng khách LSP chung như [**vscode-glspc**](https://marketplace.visualstudio.com/items?itemName=sibiraj-s.vscode-scss-formatter) hoặc bằng cách viết một tiện ích mở rộng nhỏ của riêng bạn. Phương pháp khuyến nghị là sử dụng tiện ích mở rộng Intlayer.
+
+Để tham khảo, máy chủ được khởi chạy thông qua tệp nhị phân `intlayer-lsp` qua stdio:
+
+```json fileName=".vscode/settings.json"
+{
+  "intlayer.languageServer.command": "npx",
+  "intlayer.languageServer.args": ["@intlayer/lsp"]
+}
+```
+
+Tiện ích mở rộng Intlayer đọc các cài đặt này để khởi chạy máy chủ. Nếu bạn chỉ dựa vào tiện ích mở rộng, không cần cài đặt thủ công.
+
+---
+
+## Thiết lập trong Cursor
+
+[Cursor](https://www.cursor.com/) là một bản phân nhánh của VS Code với các tính năng AI tích hợp. Nó sử dụng cùng một hệ sinh thái tiện ích mở rộng, vì vậy **tiện ích mở rộng Intlayer VS Code** hoạt động mà không cần bất kỳ cấu hình bổ sung nào — hãy cài đặt nó một lần và Cursor sẽ tự động phát hiện.
+
+Nếu bạn thích cấu hình thủ công, Cursor cũng đọc tệp `.vscode/settings.json` từ thư mục gốc của không gian làm việc, do đó đoạn mã VS Code ở trên sẽ áp dụng trực tiếp.
+
+---
+
+## Thiết lập trong Windsurf
+
+[Windsurf](https://windsurf.com/) (phát triển bởi Codeium) là một trình soạn thảo dựa trên VS Code khác. Cài đặt tiện ích mở rộng Intlayer từ VS Code Marketplace và máy chủ ngôn ngữ sẽ tự động được kích hoạt, giống hệt như trong VS Code và Cursor.
+
+Để cấu hình thủ công, hãy tạo tệp `.vscode/settings.json` tại thư mục gốc của dự án:
+
+```json fileName=".vscode/settings.json"
+{
+  "intlayer.languageServer.command": "npx",
+  "intlayer.languageServer.args": ["@intlayer/lsp"]
+}
+```
+
+---
+
+## Thiết lập trong Zed
+
+[Zed](https://zed.dev/) hỗ trợ LSP gốc thông qua cài đặt ngôn ngữ của nó. Thêm một mục trong cài đặt người dùng Zed của bạn (`~/.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", "..."]
+    }
+  }
+}
+```
+
+Dấu giữ chỗ `"..."` yêu cầu Zed giữ các máy chủ ngôn ngữ mặc định của nó cùng với máy chủ Intlayer.
+
+---
+
+## Thiết lập cho CLI Tác nhân AI (Claude Code, Codex, v.v.)
+
+**Claude Code** có hỗ trợ plugin LSP hạng nhất — hãy làm theo các bước [thiết lập Plugin Claude Code](#thiết-lập-như-một-plugin-claude-code) ở trên để có được trải nghiệm Đi tới Định nghĩa đầy đủ trực tiếp trong các phiên terminal của bạn.
+
+**OpenAI Codex** và các công cụ dựa trên terminal khác chưa hoạt động như máy chủ khách LSP — chúng đọc và ghi tệp trực tiếp thay vì duy trì một phiên máy chủ ngôn ngữ liên tục. Đối với những công cụ đó, giá trị của việc chạy LSP đến một cách gián tiếp: khi máy chủ hoạt động trong một trình soạn thảo đồng hành (VS Code, Cursor, Windsurf, ...), chỉ mục trực tiếp của trình soạn thảo sẽ có sẵn cho bất kỳ tác nhân AI nào có thể truy vấn nó thông qua ngữ cảnh do trình soạn thảo cung cấp (ví dụ: Cursor Composer, Windsurf Cascade, GitHub Copilot Chat).
+
+Nếu bạn chỉ làm việc trong terminal mà không mở trình soạn thảo, bạn có thể khởi động máy chủ ngôn ngữ trong nền để nó sẵn sàng cho bất kỳ trình soạn thảo nào sau đó kết nối với cùng một không gian làm việc:
+
+```bash
+# Giữ cho máy chủ tiếp tục chạy trong nền
+npx @intlayer/lsp &
+```
+
+---
+
+## Thiết lập thủ công trong Neovim
+
+Sử dụng [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig), đăng ký cấu hình máy chủ tùy chỉnh:
+
+```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 = {
+      -- Khởi chạy máy chủ bằng npx để bạn không cần cài đặt toàn cục
+      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({})
+```
+
+Sau khi khởi động lại Neovim, việc nhấn `gd` trên một khóa Intlayer sẽ kích hoạt Đi tới Định nghĩa.
+
+---
+
+## Thiết lập thủ công trong các Trình soạn thảo khác
+
+Bất kỳ trình soạn thảo nào hỗ trợ Giao thức Máy chủ Ngôn ngữ đều có thể sử dụng `@intlayer/lsp`. Máy chủ:
+
+- **Truyền tải** – Node.js IPC / stdio (tiêu chuẩn)
+- **Tệp thực thi** – `npx @intlayer/lsp` (hoặc tệp nhị phân `intlayer-lsp` được cài đặt cục bộ)
+- **Khả năng** – `definitionProvider: true`, `textDocumentSync: Incremental`
+
+Tham khảo tài liệu LSP của trình soạn thảo của bạn để biết định dạng cấu hình chính xác (ví dụ: `languageserver.json` cho [coc.nvim](https://github.com/neoclide/coc.nvim), hoặc cài đặt ứng dụng khách LSP trong [Helix](https://helix-editor.com)).
+
+### Ví dụ: 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"
+      ]
+    }
+  }
+}
+```
+
+### Ví dụ: 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"]
+```
+
+---
+
+## Cách hoạt động
+
+Khi máy chủ khởi động, nó sẽ giải quyết cấu hình Intlayer từ thư mục gốc của không gian làm việc bằng cách sử dụng `getConfiguration()`. Điều này cung cấp cho nó các đường dẫn `build` và `system` cần thiết để tìm các từ điển được biên dịch.
+
+Trên mỗi yêu cầu **Đi tới Định nghĩa**:
+
+1. Máy chủ đọc toàn bộ văn bản của tài liệu đang mở.
+2. Nó quét các lệnh gọi getter (`useIntlayer`, `getIntlayer`, v.v.) bằng cách sử dụng một biểu thức chính quy.
+3. Nó kiểm tra xem vị trí con trỏ có nằm trong một trong những lệnh gọi đó hay không.
+4. Nếu có, nó sẽ trích xuất khóa từ điển (nhóm chụp 3 của biểu thức chính quy) và gọi `getUnmergedDictionaries()` để xác định vị trí của từng tệp nội dung khai báo khóa đó.
+5. Nó đọc từng tệp phù hợp và tìm dòng chính xác chứa `key: "<key>"` để định vị con trỏ một cách chính xác.
+6. Nó trả về một mảng gồm các đối tượng `Location` — một đối tượng trên mỗi tệp nguồn.
+
+Cấu hình được giải quyết một cách lazy và được lưu vào bộ nhớ cache cho mỗi phiên; nó sẽ được đặt lại trên mỗi yêu cầu `initialize` (ví dụ: khi bạn mở một thư mục không gian làm việc mới).
+
+---
+
+## Khắc phục sự cố
+
+| Triệu chứng                            | Nguyên nhân có thể                | Giải pháp                                                                                                 |
+| -------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Đi tới Định nghĩa không hoạt động      | Máy chủ không chạy                | Kiểm tra xem `@intlayer/lsp` đã được cài đặt chưa và trình soạn thảo có đang khởi chạy nó không           |
+| Phát hiện sai thư mục gốc              | Nhiều thư mục không gian làm việc | Đảm bảo thư mục chứa `intlayer.config.ts` là thư mục không gian làm việc đầu tiên                         |
+| Không tìm thấy định nghĩa cho một khóa | Cấu hình chưa được giải quyết     | Xác minh xem `intlayer.config.ts` (hoặc `.js`) có tồn tại trong thư mục gốc của không gian làm việc không |
+| Máy chủ gặp sự cố khi khởi động        | Phiên bản Node.js quá cũ          | Yêu cầu Node.js ≥ 14.18                                                                                   |

package/docs/vi/releases/v7.md

@@ -32,7 +32,7 @@ Chào mừng đến với Intlayer v7! Phiên bản lớn này giới thiệu c
 - Các chế độ định tuyến mới: `prefix-no-default`, `prefix-all`, `no-prefix`, `search-params`
 - Lưu trữ ngôn ngữ tuân thủ GDPR với localStorage làm mặc định
 - Cấu hình lưu trữ linh hoạt: cookies, localStorage, sessionStorage, hoặc kết hợp nhiều loại
-- Kích thước gói Visual Editor giảm 30%
+- Kích thước bundle Visual Editor giảm 30%
 - Tùy chọn cấu hình middleware được cải thiện
 - Cập nhật hành vi lệnh fill để quản lý nội dung tốt hơn
 - Tăng cường độ ổn định với việc cập nhật đầy đủ các tệp khai báo nội dung

package/docs/zh/benchmark/nextjs.md

@@ -90,7 +90,7 @@ Intlayer 尝试在这些维度上进行优化。
 
 即使你使用 Webpack 或 Turbopack 声明了类似 `[locale]/page.tsx` 的路由，并且定义了 `generateStaticParams`，打包工具也不会将 `locale` 视为静态常量。这意味着它可能会将所有语言的内容都拉入每个页面。限制这种情况的主要方法是通过动态导入（例如 `import('./locales/${locale}.json')`）加载内容。
 
-在构建时，Next.js 会为每个语言环境生成一个 JS 包（例如 `./locales_fr_12345.js`）。当站点发送到客户端并运行时，浏览器会为所需的 JS 文件发出额外的 HTTP 请求。
+在构建时 (build time)，Next.js 会为每个语言环境生成一个 JS 包（例如 `./locales_fr_12345.js`）。当站点发送到客户端并运行时，浏览器会为所需的 JS 文件发出额外的 HTTP 请求。
 
 > 解决同一问题的另一种方法是使用 `fetch()` 动态加载 JSON。这就是当 JSON 存储在 `/public` 下时 `Tolgee` 的工作方式，或者是依赖 `getStaticProps` 加载内容的 `next-translate` 的工作方式。流程是一样的：浏览器会发起额外的 HTTP 请求来下载资源。
 

package/docs/zh/benchmark/solid.md

@@ -2,7 +2,7 @@
 createdAt: 2026-04-20
 updatedAt: 2026-05-18
 title: 2026 年 Solid 最佳 i18n 解决方案 - 基准报告
-description: 比较 Solid 国际化（i18n）库，如 solid-primitives、solid-i18next 和 Intlayer。关于包大小、泄漏和反应性的详细性能报告。
+description: 比较 Solid 国际化（i18n）库，如 solid-primitives、solid-i18next 和 Intlayer。关于Bundle 大小、泄漏和反应性的详细性能报告。
 keywords:
   - benchmark
   - i18n

package/docs/zh/benchmark/svelte.md

@@ -2,7 +2,7 @@
 createdAt: 2026-04-20
 updatedAt: 2026-05-18
 title: 2026 年 Svelte 最佳 i18n 解决方案 - 基准报告
-description: 比较 Svelte 国际化（i18n）库，如 svelte-i18n、Paraglide 和 Intlayer。关于包大小、泄漏和反应性的详细性能报告。
+description: 比较 Svelte 国际化（i18n）库，如 svelte-i18n、Paraglide 和 Intlayer。关于Bundle 大小、泄漏和反应性的详细性能报告。
 keywords:
   - benchmark
   - i18n

package/docs/zh/benchmark/vue.md

@@ -2,7 +2,7 @@
 createdAt: 2026-04-20
 updatedAt: 2026-05-18
 title: 2026 年 Vue 最佳 i18n 解决方案 - 基准报告
-description: 比较 Vue 国际化（i18n）库，如 vue-i18n、fluent-vue 和 Intlayer。关于包大小、泄漏和反应性的详细性能报告。
+description: 比较 Vue 国际化（i18n）库，如 vue-i18n、fluent-vue 和 Intlayer。关于Bundle 大小、泄漏和反应性的详细性能报告。
 keywords:
   - benchmark
   - i18n
@@ -128,7 +128,7 @@ style="border:none;"
 
 - **其他路由的泄漏**: 应用中**其他屏幕**的同样想法：当你只打开一个页面时，它们的文案是否也随之而来。（例如：`/en/about` 页面内容出现在 `/en/contact` 页面包中）。高分暗示拆分较弱或包范围过宽。
 
-- **平均组件包大小**: 常见的 UI 部件被**逐一**测量，而不是隐藏在一个巨大的应用数字中。它显示国际化是否在静默地膨胀日常组件。例如，如果您的组件重新渲染，它将从内存加载所有这些数据。将巨大的 JSON 附加到任何组件就像连接一个庞大的未使用数据存储，这会减慢组件的性能。
+- **平均组件Bundle 大小**: 常见的 UI 部件被**逐一**测量，而不是隐藏在一个巨大的应用数字中。它显示国际化是否在静默地膨胀日常组件。例如，如果您的组件重新渲染，它将从内存加载所有这些数据。将巨大的 JSON 附加到任何组件就像连接一个庞大的未使用数据存储，这会减慢组件的性能。
 
 - **语言切换响应能力**: 我使用应用自带的控制切换语言，并计时直到页面清晰切换的时间，这是访问者会注意到的，而不是实验室的微小步骤。
 

package/docs/zh/bundle_optimization.md

@@ -1,7 +1,7 @@
 ---
 createdAt: 2025-11-25
 updatedAt: 2026-04-08
-title: 优化 i18n 构建包大小与性能
+title: 优化 i18n 构建Bundle 大小与性能
 description: 通过优化国际化 (i18n) 内容来减小应用程序构建包的大小。学习如何利用 Intlayer 对字典进行 Tree Shaking 和延迟加载。
 keywords:
   - 构建包优化
@@ -21,7 +21,7 @@ history:
     changes: "在构建配置中增加了 `minify` 和 `purge` 选项"
 ---
 
-# 优化 i18n 构建包大小与性能
+# 优化 i18n 构建Bundle 大小与性能
 
 依赖 JSON 文件的传统 i18n 解决方案面临的最常见挑战之一是管理内容大小。如果开发人员不手动将内容分离到命名空间中，用户往往为了查看单个页面而下载每个页面甚至每种语言的翻译。
 
@@ -269,7 +269,7 @@ const config: IntlayerConfig = {
   },
   build: {
     /**
-     * 压缩字典以减小构建包大小。
+     * 压缩字典以减小构建Bundle 大小。
      */
      minify: true;
 
@@ -299,7 +299,7 @@ export default config;
 | 属性           | 类型      | 默认值      | 描述                                                                                                                                    |
 | :------------- | :-------- | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
 | **`optimize`** | `boolean` | `undefined` | 控制是否启用构建优化。如果为 `true`，Intlayer 使用优化后的注入替换字典调用。如果为 `false`，则禁用优化。建议在生产环境中设置为 `true`。 |
-| **`minify`**   | `boolean` | `false`     | 是否压缩字典以减小构建包大小。                                                                                                          |
+| **`minify`**   | `boolean` | `false`     | 是否压缩字典以减小构建Bundle 大小。                                                                                                     |
 | **`purge`**    | `boolean` | `false`     | 是否清除字典中未使用的键。                                                                                                              |
 
 ### 压缩 (Minification)
@@ -340,7 +340,7 @@ export default config;
 
 ### 导入模式 (Import Mode)
 
-对于包含多个页面和语言的大型应用程序，您的 JSON 文件可能占用构建包大小的很大一部分。Intlayer 允许您控制字典的加载方式。
+对于包含多个页面和语言的大型应用程序，您的 JSON 文件可能占用构建Bundle 大小的很大一部分。Intlayer 允许您控制字典的加载方式。
 
 导入模式可以在 `intlayer.config.ts` 文件中全局定义默认值。
 
@@ -412,7 +412,7 @@ const content = useDictionary({
 
 - **优点：** **语言级别的 Tree Shaking。** 查看英文版本的用户将*仅*下载英文字典，永远不会加载法文字典。
 - **缺点：** 在水合过程中每个组件都会触发一次网络请求（资源获取）。
-- **最适合：** 大型文本块、文章或支持多种语言且构建包大小至关重要的应用程序。
+- **最适合：** 大型文本块、文章或支持多种语言且构建Bundle 大小至关重要的应用程序。
 
 **转换后的代码示例：**
 
@@ -445,10 +445,10 @@ const content = useDictionaryAsync({
 
 ## 总结：静态 vs 动态
 
-| 特性              | 静态模式                   | 动态模式                 |
-| :---------------- | :------------------------- | :----------------------- |
-| **JS 构建包大小** | 较大（包含组件的所有语言） | 最小（仅代码，无内容）   |
-| **初始加载**      | 即时（内容在构建包中）     | 轻微延迟（获取 JSON）    |
-| **网络请求**      | 0 次额外请求               | 每个字典 1 次请求        |
-| **Tree Shaking**  | 组件级                     | 组件级 + 语言级          |
-| **最佳用例**      | UI 组件、小型应用          | 文本较多的页面、多种语言 |
+| 特性                   | 静态模式                   | 动态模式                 |
+| :--------------------- | :------------------------- | :----------------------- |
+| **JS 构建Bundle 大小** | 较大（包含组件的所有语言） | 最小（仅代码，无内容）   |
+| **初始加载**           | 即时（内容在构建包中）     | 轻微延迟（获取 JSON）    |
+| **网络请求**           | 0 次额外请求               | 每个字典 1 次请求        |
+| **Tree Shaking**       | 组件级                     | 组件级 + 语言级          |
+| **最佳用例**           | UI 组件、小型应用          | 文本较多的页面、多种语言 |

package/docs/zh/component_i18n.md

@@ -168,7 +168,7 @@ export function ClientComponent() {
 ## 为什么 Intlayer 的组件方法是最佳选择
 
 - **内容共置**：内容声明与组件紧密相邻，减少偏差并提升设计系统中的复用性。
-- **类型安全**：键和值结构均为强类型；缺失的翻译会在构建时而非运行时暴露。
+- **类型安全**：键和值结构均为强类型；缺失的翻译会在构建时 (build time)而非运行时暴露。
 - **服务器优先**：原生支持服务器组件，提升安全性和性能；客户端钩子依然保持良好的使用体验。
 - **摇树优化**：仅打包组件实际使用的内容，保持大型应用的负载体积小。
 - **开发体验与工具**：内置中间件、SEO助手，以及可选的可视化编辑器/AI翻译，简化日常工作流程。

package/docs/zh/dictionary/content_file.md

@@ -520,7 +520,7 @@ export default aboutPageMetaContent;
 
 导入模式决定字典在应用程序中的导入方式。
 
-- `'static'`: 字典在构建时静态导入。这是默认模式。
+- `'static'`: 字典在构建时 (build time)静态导入。这是默认模式。
 - `'dynamic'`: 字典在运行时使用 suspense API 动态导入。
 - `'fetch'`: 字典使用实时同步 API 动态导入。
 
@@ -1079,4 +1079,4 @@ export default {
 3. **性能**：
    - 调整内容配置以限制监视文件的范围
    - 仅在需要实时更新时使用实时字典（例如 A/B 测试等）
-   - 确保启用构建转换插件（`@intlayer/swc` 或 `@intlayer/babel`）以在构建时优化字典
+   - 确保启用构建转换插件（`@intlayer/swc` 或 `@intlayer/babel`）以在构建时 (build time)优化字典

package/docs/zh/dictionary/html.md

@@ -277,7 +277,7 @@ const myContent = html(
     );
     ```
 
-    > 动态导入 HTML 渲染器是减小应用程序包大小的好方法。
+    > 动态导入 HTML 渲染器是减小应用程序Bundle 大小的好方法。
 
   </Tab>
   <Tab label="Vue" value="vue">
@@ -322,7 +322,7 @@ const myContent = html(
     app.mount("#app");
     ```
 
-    > 动态导入 HTML 渲染器是减小应用程序包大小的好方法。
+    > 动态导入 HTML 渲染器是减小应用程序Bundle 大小的好方法。
 
   </Tab>
   <Tab label="Svelte" value="svelte">
@@ -359,7 +359,7 @@ const myContent = html(
     </HTMLProvider>
     ```
 
-    > 动态导入 HTML 渲染器是减小应用程序包大小的好方法。
+    > 动态导入 HTML 渲染器是减小应用程序Bundle 大小的好方法。
 
   </Tab>
   <Tab label="Preact" value="preact">
@@ -395,7 +395,7 @@ const myContent = html(
     );
     ```
 
-    > 动态导入 HTML 渲染器是减小应用程序包大小的好方法。
+    > 动态导入 HTML 渲染器是减小应用程序Bundle 大小的好方法。
 
   </Tab>
   <Tab label="Solid" value="solid">
@@ -431,7 +431,7 @@ const myContent = html(
     );
     ```
 
-    > 动态导入 HTML 渲染器是减小应用程序包大小的好方法。
+    > 动态导入 HTML 渲染器是减小应用程序Bundle 大小的好方法。
 
   </Tab>
   <Tab label="Angular" value="angular">
@@ -468,7 +468,7 @@ const myContent = html(
     };
     ```
 
-    > 动态导入 HTML 渲染器是减小应用程序包大小的好方法。
+    > 动态导入 HTML 渲染器是减小应用程序Bundle 大小的好方法。
 
   </Tab>
 </Tabs>

package/docs/zh/dictionary/markdown.md

@@ -740,7 +740,7 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
     );
     ```
 
-    > 动态导入您的 Markdown 渲染器是减少应用程序包大小的好方法。
+    > 动态导入您的 Markdown 渲染器是减少应用程序Bundle 大小的好方法。
 
   </Tab>
   <Tab label="Next.js" value="nextjs">
@@ -782,7 +782,7 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
     );
     ```
 
-    > 动态导入您的 Markdown 渲染器是减少应用程序包大小的好方法。
+    > 动态导入您的 Markdown 渲染器是减少应用程序Bundle 大小的好方法。
 
   </Tab>
   <Tab label="Vue" value="vue">
@@ -833,7 +833,7 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
     app.mount("#app");
     ```
 
-    > 动态导入您的 Markdown 渲染器是减少应用程序包大小的好方法。
+    > 动态导入您的 Markdown 渲染器是减少应用程序Bundle 大小的好方法。
 
   </Tab>
   <Tab label="Svelte" value="svelte">
@@ -873,7 +873,7 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
     </MarkdownProvider>
     ```
 
-    > 动态导入您的 Markdown 渲染器是减少应用程序包大小的好方法。
+    > 动态导入您的 Markdown 渲染器是减少应用程序Bundle 大小的好方法。
 
   </Tab>
   <Tab label="Preact" value="preact">
@@ -912,7 +912,7 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
     );
     ```
 
-    > 动态导入您的 Markdown 渲染器是减少应用程序包大小的好方法。
+    > 动态导入您的 Markdown 渲染器是减少应用程序Bundle 大小的好方法。
 
   </Tab>
   <Tab label="Solid" value="solid">
@@ -951,7 +951,7 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
     );
     ```
 
-    > 动态导入您的 Markdown 渲染器是减少应用程序包大小的好方法。
+    > 动态导入您的 Markdown 渲染器是减少应用程序Bundle 大小的好方法。
 
   </Tab>
   <Tab label="Angular" value="angular">
@@ -973,7 +973,7 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
     export class AppModule {}
     ```
 
-    > 动态导入您的 Markdown 渲染器是减少应用程序包大小的好方法。
+    > 动态导入您的 Markdown 渲染器是减少应用程序Bundle 大小的好方法。
 
   </Tab>
 </Tabs>

package/docs/zh/how_works_intlayer.md

@@ -101,7 +101,7 @@ Intlayer 还提供了一个可视化编辑器，允许您以可视化的方式
 
 ## 应用构建优化
 
-为了优化应用的包大小，Intlayer 提供了两个插件来优化应用的构建：`@intlayer/babel` 和 `@intlayer/swc` 插件。
+为了优化应用的Bundle 大小，Intlayer 提供了两个插件来优化应用的构建：`@intlayer/babel` 和 `@intlayer/swc` 插件。
 Babel 和 SWC 插件通过分析应用程序的抽象语法树（AST）来替换 Intlayer 函数的调用为优化后的代码。此过程确保只导入实际使用的字典，优化分块，从而减小生产环境中的最终包体积。
 
 在开发模式下，Intlayer 使用集中式静态导入字典以简化开发体验。