@intlayer/docs 9.2.0 → 9.3.1

package/docs/zh-TW/bundle_optimization.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-06-07
+updatedAt: 2026-08-09
 title: 最佳化 i18n 打包體積與效能
 description: 透過最佳化國際化（i18n）內容來縮減應用程式包的大小。了解如何利用 Intlayer 實現字典的 tree shaking 和延遲載入（lazy loading）。
 keywords:
@@ -16,6 +16,12 @@ slugs:
   - concept
   - bundle-optimization
 history:
+  - version: 9.2.1
+    date: 2026-08-09
+    changes: "`purge` 與 `minify` 現在可透過 `@intlayer/swc` 在 Next.js 上運作 — 不需要 `babel.config.js`"
+  - version: 8.12.0
+    date: 2026-06-24
+    changes: "在參考表中依所需的流水線順序列出 Babel 外掛（extract → purge → minify → optimize）"
   - version: 8.12.0
     date: 2026-06-07
     changes: "為 Babel/Webpack 引入了 `intlayerPurgeBabelPlugin` 和 `intlayerMinifyBabelPlugin`，明確了外掛程式管線"
@@ -191,12 +197,14 @@ Intlayer 的建置最佳化被劃分為若干個職責單一的外掛程式。
 
 這些被直接運用在基於 Webpack 設定的 `babel.config.js` 當中（比如使用了 Babel 的 Next.js、CRA，或是自訂的 Webpack 等）。
 
+下表依所需的流水線順序列出它們（與它們必須在 `babel.config.js` 中出現的順序相同）：
+
 | 外掛程式                      | 功能說明                                                                                               |
 | :---------------------------- | :----------------------------------------------------------------------------------------------------- |
 | `intlayerExtractBabelPlugin`  | 掃描 `.content.ts` 檔案並把編譯好的字典寫入 `.intlayer/`                                               |
-| `intlayerOptimizeBabelPlugin` | 將 `useIntlayer('key')` 重寫為 `useDictionary(hash)` 並注入匹配對應字典的 `import` 語句                |
 | `intlayerPurgeBabelPlugin`    | 掃描所有原始碼檔案，從已編譯的 `.intlayer/**/*.json` 字典檔案中刪除**未被使用的內容欄位**              |
 | `intlayerMinifyBabelPlugin`   | **重新命名內容欄位的鍵（keys）** 為簡短的字母別名（例如 `title` 變成 `a`），作用範圍包括 JSON 與原始碼 |
+| `intlayerOptimizeBabelPlugin` | 將 `useIntlayer('key')` 重寫為 `useDictionary(hash)` 並注入匹配對應字典的 `import` 語句                |
 
 > **外掛程式的執行順序很重要。** 在您的 `babel.config.js` 裡，purge 和 minify 的外掛程式必須放置在 optimize 外掛程式**之前**。最佳化步驟（optimize）會把 `useIntlayer('key')` 替換為模糊的 `useDictionary(hash)`，此舉抹除了能夠讓 purge 和 minify 識別哪些欄位被使用過的字典 key 資訊。
 
@@ -205,9 +213,9 @@ Intlayer 的建置最佳化被劃分為若干個職責單一的外掛程式。
 | 選項助手                     | 配套外掛程式                  |
 | :--------------------------- | :---------------------------- |
 | `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`  |
-| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 | `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`    |
 | `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`   |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin` |
 
 ### Vite 外掛程式 (`vite-intlayer`)
 
@@ -220,6 +228,20 @@ Vite 使用者**不需要直接對它們進行設定**。當您在 `vite.config.
 | Dictionary minify  | 等同於 `intlayerMinifyBabelPlugin` 的 JSON 寫入步驟                                     |
 | Babel transform    | 等同於 `intlayerMinifyBabelPlugin` 的程式碼重新命名步驟 + `intlayerOptimizeBabelPlugin` |
 
+### SWC 外掛（`@intlayer/swc`）
+
+Next.js 使用者同樣**從不直接設定這些**。自 **v9.2.1** 起，`next.config.ts` 中的 `withIntlayer()` 僅憑 `build.purge` 與 `build.minify` 兩個旗標就會執行完整流水線 —— 清除、壓縮與匯入重寫。
+
+工作被分成兩部分，因為 SWC Wasm 外掛一次只轉換一個檔案，且無法存取檔案系統：
+
+| 階段                                 | 執行位置                       | 作用                                                           |
+| :----------------------------------- | :----------------------------- | :------------------------------------------------------------- |
+| 使用分析 + JSON 清除/壓縮            | Node，位於 `withIntlayer()` 內 | 讀取每個元件原始檔，重寫 `.intlayer/**/*.json`，產生重新命名表 |
+| 原始碼重寫（`content.title` → `.a`） | `@intlayer/swc`（Wasm）        | 將重新命名表套用到你程式碼中對應的屬性存取                     |
+| 匯入重寫（`useIntlayer` → dict）     | `@intlayer/swc`（Wasm）        | 與 `intlayerOptimizeBabelPlugin` 相同                          |
+
+判斷_哪些_欄位未被使用以及每個欄位取得_什麼_別名，需要跨檔案狀態與檔案 I/O，因此這一半在 Node 中執行；SWC 外掛只接收產生的表。
+
 ## 各平台設定指南
 
 <Tabs>
@@ -227,10 +249,12 @@ Vite 使用者**不需要直接對它們進行設定**。當您在 `vite.config.
 
 ### Next.js
 
-Next.js 需要依靠 `@intlayer/swc` 外掛程式來進行最佳化步驟（匯入重寫），因為 Next.js 採用 SWC 作為編譯器。
+Next.js 需要 `@intlayer/swc` 外掛，因為 Next.js 使用 SWC 進行建置。自 **v9.2.1** 起，這一個套件即可涵蓋整條流水線 —— 最佳化（匯入重寫）、清除與壓縮。
 
 > 該外掛程式並未預設安裝，因為 SWC 外掛程式在 Next.js 當中目前仍處於實驗階段。未來這部分有可能會發生改變。
 
+> **Next.js 16.1.0 是最低版本。** 它是首個基於 SWC 向前相容 Wasm 外掛 ABI 建置的版本；更早的版本會拒絕該外掛。`withIntlayer` 會讀取你專案的 Next.js 版本，低於 16.1.0 時乾脆不註冊該外掛 —— 這些建置仍會成功，只是在沒有打包最佳化的情況下執行。
+
 <Tabs>
  <Tab value="npm">
 
@@ -265,33 +289,40 @@ intlayer-swc-plugin = "*"
 
 安裝完畢後，Intlayer 將會自動偵測並使用該外掛程式。
 
-至於**清除（purge）和最小化（minify）**步驟（即欄位移除和欄位重新命名），請連同 `@intlayer/babel` 一併安裝並加入 Babel 外掛程式。由於 Next.js 依靠 SWC 處理程式碼轉化，但仍會評估 `babel.config.js` 以決定外掛程式設定，因此上述 Babel 外掛程式能夠在進入 SWC 前作為預處理步驟得以執行。
+**清除與壓縮**階段（欄位移除與欄位重新命名）不需要額外套件，也不需要 `babel.config.js`。用 `withIntlayer` 包住你的設定，並在 `intlayer.config.ts` 中開啟相應旗標：
 
-```bash packageManager="npm"
-npm install -D @intlayer/babel
+```typescript fileName="next.config.ts"
+import { withIntlayer } from "next-intlayer/server";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {/* 你的設定 */};
+
+export default withIntlayer(nextConfig);
 ```
 
-```javascript fileName="babel.config.js"
-const {
-  intlayerPurgeBabelPlugin,
-  intlayerMinifyBabelPlugin,
-  getPurgePluginOptions,
-  getMinifyPluginOptions,
-} = require("@intlayer/babel");
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
 
-module.exports = {
-  presets: ["next/babel"],
-  plugins: [
-    // Purge: 移除 .intlayer/**/*.json 裡未被使用的內容欄位
-    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
-    // Minify: 對 JSON 以及原始碼裡的內容欄位的鍵（keys）進行重新命名
-    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
-    // 注意: 在這裡不需要使用 intlayerOptimizeBabelPlugin，因為
-    // @intlayer/swc 已經處理了 useIntlayer → useDictionary 的重寫過程。
-  ],
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // 從打包的 JSON 中移除未使用的內容欄位
+    minify: true, // 將內容欄位鍵重新命名為簡短別名
+  },
 };
+
+export default config;
 ```
 
+在 `next build` 期間，`withIntlayer` 會分析你的原始碼、重寫已編譯的字典，並將產生的欄位重新命名表交給 `@intlayer/swc`，由它更新你程式碼中對應的屬性存取。
+
+> 請使用非同步的 `withIntlayer`，而不是 `withIntlayerSync`。同步版本不會執行分析流水線，因此清除與壓縮對它沒有效果。
+
+> 清除與壓縮僅在 `next build` 時執行 —— 最佳化流水線在 `next dev` 期間是關閉的。
+
+> 當設定了相容轉接器呼叫方時它們也會被停用（`swcExtraCallers`，由 `@intlayer/next-intl`、`@intlayer/react-i18next` 等相容套件設定）：這些呼叫點對使用分析器不可見，因此清除會移除程式碼仍在讀取的欄位。匯入重寫仍保持啟用。
+
+**更早的版本（9.2.1 之前）** 需要 `@intlayer/babel` 以及一個宣告 `intlayerPurgeBabelPlugin` 與 `intlayerMinifyBabelPlugin` 的 `babel.config.js`。該檔案不再需要，可以刪除。
+
  </Tab>
  <Tab value="vite">
 
@@ -447,6 +478,8 @@ export default config;
 
 > 如果在 `optimize` 被設為 `false`、又或是啟用了視覺化編輯器也就是當 `editor.enabled` 設定為了 `true` 時（由於編輯器需要保留欄位名稱以便做後續處理），重新命名這個操作都將會被跳過。
 
+> 在 Next.js 上，當 `@intlayer/swc` 未安裝或無法載入時（Next.js 低於 16.1.0），壓縮同樣會被略過。重寫原始碼存取的正是這個外掛，因此在沒有它的情況下重新命名字典，會讓你的程式碼讀取已不存在的欄位名稱。
+
 > 同理，如果是利用了 `importMode: 'fetch'` 來載入欄位時此過程同樣不適用。因為它們的內容會以原始命名由後端 API 所提供，對客戶端內容隨意重新命名會破壞客戶端與伺服器端的匹配契約。
 
 ### 欄位清除 / Purging (去掉未被引用的欄位內容)
@@ -475,7 +508,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> 與前邊提到的類似，當 `optimize` 是 `false` 或是開啟了視覺化編輯器(`editor.enabled` 取值 `true`) 時，它會選擇跳過對資料的清除操作。
+> 與前邊提到的類似，當 `optimize` 是 `false` 或是開啟了視覺化編輯器(`editor.enabled` 取值 `true`) 時，它會選擇跳過對資料的清除操作。 在 Next.js 上，當 `@intlayer/swc` 不可用以及設定了相容轉接器呼叫方時，還會被額外略過。
 
 > 當檢測到某份程式碼因為異常無法順利解析、又或者當把由 `useIntlayer` 輸出的值以靜態解析器難以預測分析的模式在不同元件中來回丟（比如被打包成物件傳入等而未被進行解構）的時候，它同樣會跳過，以此保守地保留整部字典的全部資訊，避免意外發生。
 

package/docs/zh-TW/interest_of_intlayer.md

@@ -188,7 +188,7 @@ export const ComponentExample = () => {
 這種方法允許你：
 
 1. **提高開發速度**
-   - 可以使用 VSCode 插件創建 `.content.{{ts|mjs|cjs|json}}` 文件
+   - 可以使用 VSCode 插件創建 `.content.{ts|js|mjs|cjs|json|tsx|jsx|md|mdx|yaml|yml}` 文件
    - IDE 中的 AI 自動補全工具（例如 GitHub Copilot）可以幫助你宣告內容，減少複製/粘貼
 
 2. **保持代码庫的整潔**
@@ -212,27 +212,27 @@ export const ComponentExample = () => {
 
 ## Intlayer 附加功能
 
-| 功能                                                                                                                      | 描述                                                                                                                                                                                                                                                                                                                                                      |
-| ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/frameworks.png?raw=true)                          | **跨框架支持**<br><br>Intlayer 兼容所有主流框架和庫，包括 Next.js, React, Vite, Vue.js, Nuxt, Preact, Express 等。                                                                                                                                                                                                                                        |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/javascript_content_management.jpg?raw=true)       | **JavaScript 驅動的內容管理**<br><br>利用 JavaScript 的靈活性來高效地定義和管理你的內容。<br><br> - [內容宣告](https://intlayer.org/doc/concept/content)                                                                                                                                                                                                  |
-| <img src="https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.jpg?raw=true" alt="Feature" width="700">  | **編譯器**<br><br>Intlayer 編譯器可自動从組件中提取內容并生成字典文件。<br><br> - [編譯器](https://intlayer.org/doc/compiler)                                                                                                                                                                                                                             |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/per_locale_content_declaration_file.png?raw=true) | **單語言內容宣告文件**<br><br>在自動生成前，通過僅宣告一次你的內容來加速開發。<br><br> - [單語言內容宣告文件](https://intlayer.org/doc/concept/per-locale-file)                                                                                                                                                                                           |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)                      | **類型安全環境**<br><br>利用 TypeScript 確保你的內容定義和代码沒有錯誤，同時還能享受 IDE 的自動補全功能。<br><br> - [TypeScript 配置](https://intlayer.org/doc/environment/vite-and-react#configure-typescript)                                                                                                                                           |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/config_file.png?raw=true)                         | **簡易配置**<br><br>僅需極簡的配置即可快速啟動并運行。輕鬆調整國際化、路由、AI、構築以及內容處理的設置。<br><br> - [探索 Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                       |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/content_retrieval.png?raw=true)                   | **簡化內容檢索**<br><br>無需為每一小段內容調用 `t` 函數。使用單一的 hook 即可直接檢索你的所有內容。<br><br> - [React 集成](https://intlayer.org/doc/environment/create-react-app)                                                                                                                                                                         |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/server_component.png?raw=true)                    | **一致的服務器組件實現**<br><br>完美適合 Next.js 服務器組件，客戶端和服務器組件使用相同的實現，無需跨每个服務器組件傳遞你的 `t` 函數。<br><br> - [服務器組件](https://intlayer.org/doc/environment/nextjs#step-7-utilize-content-in-your-code)                                                                                                            |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/file_tree.png?raw=true)                           | **有條理的代码庫**<br><br>保持代码庫更有條理：1 組件 = 在同一文件夾下的 1 個字典。靠近其各自組件的翻譯有助於提高可維護性和清晰度。<br><br> - [Intlayer 運行機制](https://intlayer.org/doc/concept/how-works-intlayer)                                                                                                                                     |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/url_routing.png?raw=true)                         | **增強的路由功能**<br><br>完全支持應用路由，無縫適應複雜的應用結構，適用於 Next.js, React, Vite, Vue.js 等。<br><br> - [探索 Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                   |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/markdown.png?raw=true)                            | **Markdown 支持**<br><br>導入并解譯本地文件以及遠程 Markdown，以獲得隱私政策、文檔等多語言內容。解譯并在你的代码中使 Markdown 元數據可被訪問。<br><br> - [內容文件](https://intlayer.org/doc/concept/content/file)                                                                                                                                        |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/visual_editor.png?raw=true)                       | **免費的可視化編輯器與 CMS**<br><br>視覺編輯器和 CMS 免費向內容創作者開放，消除对第三方本地化平台的依賴。使用 Git 保持內容同步，或使用 CMS 徹底或部分外置管理它。<br><br> - [Intlayer 編輯器](https://intlayer.org/doc/concept/editor) <br> - [Intlayer CMS](https://intlayer.org/doc/concept/cms)                                                        |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle.png?raw=true)                              | **構築時搖樹優化 (Tree-shakable) 內容**<br><br>構築時搖樹優化內容，減小最終包的體積。按組件載入內容，并从打包體積中排除 any 未使用的內容。支持懶載入以提高應用載入效率。<br><br> - [應用構築優化](https://intlayer.org/doc/concept/how-works-intlayer#app-build-optimization)                                                                             |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/static_rendering.png?raw=true)                    | **靜態渲染**<br><br>不阻碍靜態渲染（Static Rendering）。<br><br> - [Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                                                                            |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/AI_translation.png?raw=true)                      | **AI 驅動翻譯**<br><br>使用您自己的 AI 提供商/API 金鑰，點擊一下即可將您的網站翻譯成 231 種語言，得益於 Intlayer 先進的 AI 翻譯工具。<br><br> - [CI/CD 集成](https://intlayer.org/doc/concept/ci-cd) <br> - [Intlayer CLI](https://intlayer.org/doc/concept/cli) <br> - [自動填充](https://intlayer.org/doc/concept/auto-fill)                            |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/mcp.png?raw=true)                                 | **MCP 服務器集成**<br><br>提供用於 IDE 自動化的 MCP（Model Context Protocol）服務器，能夠直接在你的開發環境中實現無縫的內容管理和 i18n 工作流。<br><br> - [MCP 服務器](https://github.com/aymericzip/intlayer/blob/main/docs/zh-TW/mcp_server.md)                                                                                                         |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vscode_extension.png?raw=true)                    | **VSCode 插件**<br><br>Intlayer 提供 VSCode 插件協助管理你的內容和翻譯，構築你的字典，翻譯你的內容等。<br><br> - [VSCode 插件](https://intlayer.org/doc/vs-code-extension)                                                                                                                                                                                |
-| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/interoperability.png?raw=true)                    | **互操作性**<br><br>允許與 react-i18next、next-i18next, next-intl 和 react-intl 互操作。<br><br> - [Intlayer 與 react-intl](https://intlayer.org/blog/intlayer-with-react-intl) <br> - [Intlayer 與 next-intl](https://intlayer.org/blog/intlayer-with-next-intl) <br> - [Intlayer 與 next-i18next](https://intlayer.org/blog/intlayer-with-next-i18next) |
-| 測試缺失翻譯 (CLI/CI)                                                                                                     | ✅ CLI: npx intlayer content test (对 CI 友好的審計)                                                                                                                                                                                                                                                                                                      |
+| 功能                                                                                                                      | 描述                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/frameworks.png?raw=true)                          | **跨框架支持**<br><br>Intlayer 兼容所有主流框架和庫，包括 Next.js, React, Vite, Vue.js, Nuxt, Preact, Express 等。                                                                                                                                                                                                                                                                                                             |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/javascript_content_management.jpg?raw=true)       | **JavaScript 驅動的內容管理**<br><br>利用 JavaScript 的靈活性來高效地定義和管理你的內容。<br><br> - [內容宣告](https://intlayer.org/doc/concept/content)                                                                                                                                                                                                                                                                       |
+| <img src="https://github.com/aymericzip/intlayer/blob/main/docs/assets/compiler.jpg?raw=true" alt="Feature" width="700">  | **編譯器**<br><br>Intlayer 編譯器可自動从組件中提取內容并生成字典文件。<br><br> - [編譯器](https://intlayer.org/doc/compiler)                                                                                                                                                                                                                                                                                                  |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/per_locale_content_declaration_file.png?raw=true) | **單語言內容宣告文件**<br><br>在自動生成前，通過僅宣告一次你的內容來加速開發。<br><br> - [單語言內容宣告文件](https://intlayer.org/doc/concept/per-locale-file)                                                                                                                                                                                                                                                                |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)                      | **類型安全環境**<br><br>利用 TypeScript 確保你的內容定義和代码沒有錯誤，同時還能享受 IDE 的自動補全功能。<br><br> - [TypeScript 配置](https://intlayer.org/doc/environment/vite-and-react#configure-typescript)                                                                                                                                                                                                                |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/config_file.png?raw=true)                         | **簡易配置**<br><br>僅需極簡的配置即可快速啟動并運行。輕鬆調整國際化、路由、AI、構築以及內容處理的設置。<br><br> - [探索 Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                                                                                            |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/content_retrieval.png?raw=true)                   | **簡化內容檢索**<br><br>無需為每一小段內容調用 `t` 函數。使用單一的 hook 即可直接檢索你的所有內容。<br><br> - [React 集成](https://intlayer.org/doc/environment/create-react-app)                                                                                                                                                                                                                                              |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/server_component.png?raw=true)                    | **一致的服務器組件實現**<br><br>完美適合 Next.js 服務器組件，客戶端和服務器組件使用相同的實現，無需跨每个服務器組件傳遞你的 `t` 函數。<br><br> - [服務器組件](https://intlayer.org/doc/environment/nextjs#step-7-utilize-content-in-your-code)                                                                                                                                                                                 |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/file_tree.png?raw=true)                           | **有條理的代码庫**<br><br>保持代码庫更有條理：1 組件 = 在同一文件夾下的 1 個字典。靠近其各自組件的翻譯有助於提高可維護性和清晰度。<br><br> - [Intlayer 運行機制](https://intlayer.org/doc/concept/how-works-intlayer)                                                                                                                                                                                                          |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/url_routing.png?raw=true)                         | **增強的路由功能**<br><br>完全支持應用路由，無縫適應複雜的應用結構，適用於 Next.js, React, Vite, Vue.js 等。<br><br> - [探索 Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                                                                                        |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/markdown.png?raw=true)                            | **Markdown 支持**<br><br>導入并解譯本地文件以及遠程 Markdown，以獲得隱私政策、文檔等多語言內容。解譯并在你的代码中使 Markdown 元數據可被訪問。<br><br> - [內容文件](https://intlayer.org/doc/concept/content/file)                                                                                                                                                                                                             |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/visual_editor.png?raw=true)                       | **免費的可視化編輯器與 CMS**<br><br>視覺編輯器和 CMS 免費向內容創作者開放，消除对第三方本地化平台的依賴。使用 Git 保持內容同步，或使用 CMS 徹底或部分外置管理它。<br><br> - [Intlayer 編輯器](https://intlayer.org/doc/concept/editor) <br> - [Intlayer CMS](https://intlayer.org/doc/concept/cms)                                                                                                                             |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/bundle.png?raw=true)                              | **構築時搖樹優化 (Tree-shakable) 內容**<br><br>構築時搖樹優化內容，減小最終包的體積。按組件載入內容，并从打包體積中排除 any 未使用的內容。支持懶載入以提高應用載入效率。<br><br> - [應用構築優化](https://intlayer.org/doc/concept/how-works-intlayer#app-build-optimization)                                                                                                                                                  |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/static_rendering.png?raw=true)                    | **靜態渲染**<br><br>不阻碍靜態渲染（Static Rendering）。<br><br> - [Next.js 集成](https://intlayer.org/doc/environment/nextjs)                                                                                                                                                                                                                                                                                                 |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/AI_translation.png?raw=true)                      | **AI 驅動翻譯**<br><br>使用您自己的 AI 提供商/API 金鑰，點擊一下即可將您的網站翻譯成 231 種語言，得益於 Intlayer 先進的 AI 翻譯工具。<br><br> - [CI/CD 集成](https://intlayer.org/doc/concept/ci-cd) <br> - [Intlayer CLI](https://intlayer.org/doc/concept/cli) <br> - [自動填充](https://intlayer.org/doc/concept/auto-fill)                                                                                                 |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/mcp.png?raw=true)                                 | **MCP 服務器集成**<br><br>提供用於 IDE 自動化的 MCP（Model Context Protocol）服務器，能夠直接在你的開發環境中實現無縫的內容管理和 i18n 工作流。<br><br> - [MCP 服務器](https://github.com/aymericzip/intlayer/blob/main/docs/zh-TW/mcp_server.md)                                                                                                                                                                              |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vscode_extension.png?raw=true)                    | **VSCode 插件**<br><br>Intlayer 提供 VSCode 插件協助管理你的內容和翻譯，構築你的字典，翻譯你的內容等。<br><br> - [VSCode 插件](https://intlayer.org/doc/vs-code-extension)                                                                                                                                                                                                                                                     |
+| ![Feature](https://github.com/aymericzip/intlayer/blob/main/docs/assets/interoperability.png?raw=true)                    | **互操作性**<br><br>允許與 react-i18next、next-i18next, next-intl 和 react-intl 互操作。<br><br> - [Intlayer 與 react-intl](https://intlayer.org/blog/intlayer-with-react-intl) <br> - [Intlayer 與 next-intl](https://intlayer.org/blog/intlayer-with-next-intl) <br> - [Intlayer 與 next-i18next](https://intlayer.org/blog/intlayer-with-next-i18next) <br> - [Intlayer 相容轉接器](https://intlayer.org/doc/compatibility) |
+| 測試缺失翻譯 (CLI/CI)                                                                                                     | ✅ CLI: npx intlayer content test (对 CI 友好的審計)                                                                                                                                                                                                                                                                                                                                                                           |
 
 ## Intlayer 與其他解決方案 of 比較
 
@@ -271,3 +271,5 @@ GitHub 星星數是衡量項目受歡迎程度、社區信任度以及長期相
 `intlayer` 還可以幫助管理你的 `react-intl`、`react-i18next`、`next-intl`、`next-i18next` 以及 `vue-i18n` 命名空間。
 
 使用 `intlayer`，你可以宣告你喜歡的 i18n 庫格式的內容，並且 intlayer 將在你想指定的路徑下生成命名空間（例如：`/messages/{{locale}}/{{namespace}}.json`）。
+
+如果你想繼續使用目前 i18n 函式庫的 API，`intlayer` 也提供 **相容轉接器（compat adapters）**：這些套件公開與 `react-i18next`、`next-intl`、`react-intl`、`vue-i18n` 等完全相同的 API，但內容由 Intlayer 字典提供。如此一來，你就能逐步遷移，而不需要重寫程式碼。請參閱[相容轉接器文件](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/compat/index.md)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/docs",
-  "version": "9.2.0",
+  "version": "9.3.1",
   "private": false,
   "description": "Intlayer documentation",
   "keywords": [
@@ -73,14 +73,14 @@
     "watch": "webpack --config ./webpack.config.ts --watch"
   },
   "dependencies": {
-    "@intlayer/config": "9.2.0",
-    "@intlayer/core": "9.2.0",
-    "@intlayer/types": "9.2.0"
+    "@intlayer/config": "9.3.1",
+    "@intlayer/core": "9.3.1",
+    "@intlayer/types": "9.3.1"
   },
   "devDependencies": {
-    "@intlayer/api": "9.2.0",
-    "@intlayer/cli": "9.2.0",
-    "@types/node": "26.1.2",
+    "@intlayer/api": "9.3.1",
+    "@intlayer/cli": "9.3.1",
+    "@types/node": "26.2.0",
     "@utils/ts-config": "1.0.4",
     "@utils/ts-config-types": "1.0.4",
     "@utils/tsdown-config": "1.0.4",

package/src/common.ts

@@ -131,11 +131,25 @@ export const getFileMetadata = async <
   return formatMetadata(docKey as string, file, locale) as R;
 };
 
-export const getFileMetadataRecord = async <
+/**
+ * Per-locale metadata records, keyed by the entry map they were built from.
+ *
+ * Building a record parses the frontmatter of every document of a category, and
+ * callers such as {@link getFileMetadataBySlug} need the whole record just to
+ * resolve a single slug — which a static site generator repeats for every page
+ * it renders. Documents are read once per process anyway (each entry caches its
+ * own read), so the derived metadata is equally safe to keep.
+ */
+const fileMetadataRecordCache = new WeakMap<
+  Record<string, unknown>,
+  Map<LocalesValues, Promise<Record<string, FileMetadata>>>
+>();
+
+const buildFileMetadataRecord = async <
   F extends Record<string, Record<LocalesValues, Promise<string>>>,
 >(
   files: F,
-  locale: LocalesValues = defaultLocale as LocalesValues
+  locale: LocalesValues
 ): Promise<Record<keyof F, FileMetadata>> => {
   const results = await Promise.allSettled(
     Object.entries(files).map(async ([key]) => {
@@ -153,6 +167,29 @@ export const getFileMetadataRecord = async <
   return filesResult as Record<keyof F, FileMetadata>;
 };
 
+export const getFileMetadataRecord = async <
+  F extends Record<string, Record<LocalesValues, Promise<string>>>,
+>(
+  files: F,
+  locale: LocalesValues = defaultLocale as LocalesValues
+): Promise<Record<keyof F, FileMetadata>> => {
+  let localeCache = fileMetadataRecordCache.get(files);
+
+  if (!localeCache) {
+    localeCache = new Map();
+    fileMetadataRecordCache.set(files, localeCache);
+  }
+
+  let record = localeCache.get(locale);
+
+  if (!record) {
+    record = buildFileMetadataRecord(files, locale);
+    localeCache.set(locale, record);
+  }
+
+  return (await record) as Record<keyof F, FileMetadata>;
+};
+
 export const getFileMetadataBySlug = async <
   F extends Record<string, Record<LocalesValues, Promise<string>>>,
 >(

package/src/generated/blog.entry.ts

@@ -32,26 +32,58 @@ try {
   }
 }
 
-const readLocale = (
+/**
+ * Reads a document, preferring the requested locale and falling back to English.
+ */
+const readLocaleFile = async (
   relativeAfterLocale: string,
   locale: LocalesValues
 ): Promise<string> => {
   const target1 = join(baseDir, `./blog/${locale}/${relativeAfterLocale}`);
   if (existsSync(target1)) {
-    return readFile(target1, 'utf8');
+    return await readFile(target1, 'utf8');
   }
   const target2 = join(baseDir, `./blog/en/${relativeAfterLocale}`);
   if (existsSync(target2)) {
-    return readFile(target2, 'utf8');
+    return await readFile(target2, 'utf8');
   }
 
-  return Promise.reject(
-    new Error(
-      `[docs] File not found: ${relativeAfterLocale} - locale: ${locale} - path: ${target1} - path: ${target2}`
-    )
+  throw new Error(
+    `[docs] File not found: ${relativeAfterLocale} - locale: ${locale} - path: ${target1} - path: ${target2}`
   );
 };
 
+/**
+ * Builds a lazy, awaitable handle over a document.
+ *
+ * The entry map below holds one handle per document *per locale*, so reading
+ * eagerly would pull every markdown file of every locale into memory as soon as
+ * this module is imported — hundreds of megabytes, duplicated in every
+ * prerender worker, for the handful of documents a page actually renders.
+ *
+ * The returned value is a thenable rather than a promise: consumers only ever
+ * `await` it, and `await` triggers `then`, so the file is read on first use and
+ * the resulting promise is cached for subsequent reads.
+ */
+const readLocale = (
+  relativeAfterLocale: string,
+  locale: LocalesValues
+): Promise<string> => {
+  let pendingRead: Promise<string> | undefined;
+
+  const read = (): Promise<string> => {
+    pendingRead ??= readLocaleFile(relativeAfterLocale, locale);
+    return pendingRead;
+  };
+
+  return {
+    // biome-ignore lint/suspicious/noThenProperty: the thenable is intentional — `await` is what triggers the lazy read.
+    then: (onFulfilled, onRejected) => read().then(onFulfilled, onRejected),
+    catch: (onRejected) => read().catch(onRejected),
+    finally: (onFinally) => read().finally(onFinally),
+  } as Promise<string>;
+};
+
 export const blogEntry = {
   './blog/en/compiler_vs_declarative_i18n.md': {
     en: readLocale('compiler_vs_declarative_i18n.md', 'en'),

package/src/generated/docs.entry.ts

@@ -32,26 +32,58 @@ try {
   }
 }
 
-const readLocale = (
+/**
+ * Reads a document, preferring the requested locale and falling back to English.
+ */
+const readLocaleFile = async (
   relativeAfterLocale: string,
   locale: LocalesValues
 ): Promise<string> => {
   const target1 = join(baseDir, `./docs/${locale}/${relativeAfterLocale}`);
   if (existsSync(target1)) {
-    return readFile(target1, 'utf8');
+    return await readFile(target1, 'utf8');
   }
   const target2 = join(baseDir, `./docs/en/${relativeAfterLocale}`);
   if (existsSync(target2)) {
-    return readFile(target2, 'utf8');
+    return await readFile(target2, 'utf8');
   }
 
-  return Promise.reject(
-    new Error(
-      `[docs] File not found: ${relativeAfterLocale} - locale: ${locale} - path: ${target1} - path: ${target2}`
-    )
+  throw new Error(
+    `[docs] File not found: ${relativeAfterLocale} - locale: ${locale} - path: ${target1} - path: ${target2}`
   );
 };
 
+/**
+ * Builds a lazy, awaitable handle over a document.
+ *
+ * The entry map below holds one handle per document *per locale*, so reading
+ * eagerly would pull every markdown file of every locale into memory as soon as
+ * this module is imported — hundreds of megabytes, duplicated in every
+ * prerender worker, for the handful of documents a page actually renders.
+ *
+ * The returned value is a thenable rather than a promise: consumers only ever
+ * `await` it, and `await` triggers `then`, so the file is read on first use and
+ * the resulting promise is cached for subsequent reads.
+ */
+const readLocale = (
+  relativeAfterLocale: string,
+  locale: LocalesValues
+): Promise<string> => {
+  let pendingRead: Promise<string> | undefined;
+
+  const read = (): Promise<string> => {
+    pendingRead ??= readLocaleFile(relativeAfterLocale, locale);
+    return pendingRead;
+  };
+
+  return {
+    // biome-ignore lint/suspicious/noThenProperty: the thenable is intentional — `await` is what triggers the lazy read.
+    then: (onFulfilled, onRejected) => read().then(onFulfilled, onRejected),
+    catch: (onRejected) => read().catch(onRejected),
+    finally: (onFinally) => read().finally(onFinally),
+  } as Promise<string>;
+};
+
 export const docsEntry = {
   './docs/en/CI_CD.md': {
     en: readLocale('CI_CD.md', 'en'),

package/src/generated/frequentQuestions.entry.ts

@@ -32,7 +32,10 @@ try {
   }
 }
 
-const readLocale = (
+/**
+ * Reads a document, preferring the requested locale and falling back to English.
+ */
+const readLocaleFile = async (
   relativeAfterLocale: string,
   locale: LocalesValues
 ): Promise<string> => {
@@ -41,23 +44,52 @@ const readLocale = (
     `./frequent_questions/${locale}/${relativeAfterLocale}`
   );
   if (existsSync(target1)) {
-    return readFile(target1, 'utf8');
+    return await readFile(target1, 'utf8');
   }
   const target2 = join(
     baseDir,
     `./frequent_questions/en/${relativeAfterLocale}`
   );
   if (existsSync(target2)) {
-    return readFile(target2, 'utf8');
+    return await readFile(target2, 'utf8');
   }
 
-  return Promise.reject(
-    new Error(
-      `[docs] File not found: ${relativeAfterLocale} - locale: ${locale} - path: ${target1} - path: ${target2}`
-    )
+  throw new Error(
+    `[docs] File not found: ${relativeAfterLocale} - locale: ${locale} - path: ${target1} - path: ${target2}`
   );
 };
 
+/**
+ * Builds a lazy, awaitable handle over a document.
+ *
+ * The entry map below holds one handle per document *per locale*, so reading
+ * eagerly would pull every markdown file of every locale into memory as soon as
+ * this module is imported — hundreds of megabytes, duplicated in every
+ * prerender worker, for the handful of documents a page actually renders.
+ *
+ * The returned value is a thenable rather than a promise: consumers only ever
+ * `await` it, and `await` triggers `then`, so the file is read on first use and
+ * the resulting promise is cached for subsequent reads.
+ */
+const readLocale = (
+  relativeAfterLocale: string,
+  locale: LocalesValues
+): Promise<string> => {
+  let pendingRead: Promise<string> | undefined;
+
+  const read = (): Promise<string> => {
+    pendingRead ??= readLocaleFile(relativeAfterLocale, locale);
+    return pendingRead;
+  };
+
+  return {
+    // biome-ignore lint/suspicious/noThenProperty: the thenable is intentional — `await` is what triggers the lazy read.
+    then: (onFulfilled, onRejected) => read().then(onFulfilled, onRejected),
+    catch: (onRejected) => read().catch(onRejected),
+    finally: (onFinally) => read().finally(onFinally),
+  } as Promise<string>;
+};
+
 export const frequentQuestionsEntry = {
   './frequent_questions/en/SSR_Next_no_[locale].md': {
     en: readLocale('SSR_Next_no_[locale].md', 'en'),

package/src/generated/legal.entry.ts

@@ -32,26 +32,58 @@ try {
   }
 }
 
-const readLocale = (
+/**
+ * Reads a document, preferring the requested locale and falling back to English.
+ */
+const readLocaleFile = async (
   relativeAfterLocale: string,
   locale: LocalesValues
 ): Promise<string> => {
   const target1 = join(baseDir, `./legal/${locale}/${relativeAfterLocale}`);
   if (existsSync(target1)) {
-    return readFile(target1, 'utf8');
+    return await readFile(target1, 'utf8');
   }
   const target2 = join(baseDir, `./legal/en/${relativeAfterLocale}`);
   if (existsSync(target2)) {
-    return readFile(target2, 'utf8');
+    return await readFile(target2, 'utf8');
   }
 
-  return Promise.reject(
-    new Error(
-      `[docs] File not found: ${relativeAfterLocale} - locale: ${locale} - path: ${target1} - path: ${target2}`
-    )
+  throw new Error(
+    `[docs] File not found: ${relativeAfterLocale} - locale: ${locale} - path: ${target1} - path: ${target2}`
   );
 };
 
+/**
+ * Builds a lazy, awaitable handle over a document.
+ *
+ * The entry map below holds one handle per document *per locale*, so reading
+ * eagerly would pull every markdown file of every locale into memory as soon as
+ * this module is imported — hundreds of megabytes, duplicated in every
+ * prerender worker, for the handful of documents a page actually renders.
+ *
+ * The returned value is a thenable rather than a promise: consumers only ever
+ * `await` it, and `await` triggers `then`, so the file is read on first use and
+ * the resulting promise is cached for subsequent reads.
+ */
+const readLocale = (
+  relativeAfterLocale: string,
+  locale: LocalesValues
+): Promise<string> => {
+  let pendingRead: Promise<string> | undefined;
+
+  const read = (): Promise<string> => {
+    pendingRead ??= readLocaleFile(relativeAfterLocale, locale);
+    return pendingRead;
+  };
+
+  return {
+    // biome-ignore lint/suspicious/noThenProperty: the thenable is intentional — `await` is what triggers the lazy read.
+    then: (onFulfilled, onRejected) => read().then(onFulfilled, onRejected),
+    catch: (onRejected) => read().catch(onRejected),
+    finally: (onFinally) => read().finally(onFinally),
+  } as Promise<string>;
+};
+
 export const legalEntry = {
   './legal/en/privacy_notice.md': {
     en: readLocale('privacy_notice.md', 'en'),