@intlayer/docs 7.3.1 → 7.3.2-canary.1

package/docs/vi/compiler.md

@@ -0,0 +1,133 @@
+---
+createdAt: 2025-09-09
+updatedAt: 2025-09-09
+title: Trình Biên Dịch Intlayer | Trích Xuất Nội Dung Tự Động cho i18n
+description: Tự động hóa quy trình quốc tế hóa của bạn với Trình Biên Dịch Intlayer. Trích xuất nội dung trực tiếp từ các component để i18n nhanh hơn và hiệu quả hơn trong Vite, Next.js và nhiều hơn nữa.
+keywords:
+  - Intlayer
+  - Trình Biên Dịch
+  - Quốc tế hóa
+  - i18n
+  - Tự động hóa
+  - Trích xuất
+  - Tốc độ
+  - Vite
+  - Next.js
+  - React
+  - Vue
+  - Svelte
+slugs:
+  - doc
+  - compiler
+history:
+  - version: 7.3.1
+    date: 2025-11-27
+    changes: Phát hành Trình Biên Dịch
+---
+
+# Trình Biên Dịch Intlayer | Trích Xuất Nội Dung Tự Động cho i18n
+
+## Trình Biên Dịch Intlayer là gì?
+
+**Trình Biên Dịch Intlayer** là một công cụ mạnh mẽ được thiết kế để tự động hóa quy trình quốc tế hóa (i18n) trong các ứng dụng của bạn. Nó quét mã nguồn của bạn (JSX, TSX, Vue, Svelte) để tìm các khai báo nội dung, trích xuất chúng và tự động tạo ra các tệp từ điển cần thiết. Điều này cho phép bạn giữ nội dung cùng vị trí với các component của mình trong khi Intlayer xử lý việc quản lý và đồng bộ hóa các từ điển đó.
+
+## Tại sao nên sử dụng Trình Biên Dịch Intlayer?
+
+- **Tự động hóa**: Loại bỏ việc sao chép thủ công nội dung vào từ điển.
+- **Tốc độ**: Tối ưu hóa việc trích xuất nội dung đảm bảo quá trình build của bạn vẫn nhanh.
+- **Trải nghiệm nhà phát triển**: Giữ các khai báo nội dung ngay tại nơi chúng được sử dụng, cải thiện khả năng bảo trì.
+- **Cập nhật trực tiếp**: Hỗ trợ Hot Module Replacement (HMR) để phản hồi ngay lập tức trong quá trình phát triển.
+
+Xem bài viết blog [Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/vi/compiler_vs_declarative_i18n.md) để có sự so sánh sâu hơn.
+
+## Tại sao không sử dụng Trình Biên Dịch Intlayer?
+
+Mặc dù trình biên dịch mang lại trải nghiệm "hoạt động ngay" tuyệt vời, nó cũng giới thiệu một số đánh đổi mà bạn nên biết:
+
+- **Sự mơ hồ của heuristic**: Trình biên dịch phải đoán xem đâu là nội dung hướng đến người dùng so với logic ứng dụng (ví dụ: `className="active"`, mã trạng thái, ID sản phẩm). Trong các codebase phức tạp, điều này có thể dẫn đến dương tính giả hoặc các chuỗi bị bỏ sót cần chú thích thủ công và ngoại lệ.
+- **Chỉ trích xuất tĩnh**: Trích xuất dựa trên trình biên dịch dựa vào phân tích tĩnh. Các chuỗi chỉ tồn tại ở thời gian chạy (mã lỗi API, trường CMS, v.v.) không thể được phát hiện hoặc dịch bởi trình biên dịch một mình, vì vậy bạn vẫn cần một chiến lược i18n thời gian chạy bổ sung.
+
+Để có so sánh kiến trúc sâu hơn, xem bài viết blog [Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/vi/compiler_vs_declarative_i18n.md).
+
+Như một giải pháp thay thế, để tự động hóa quy trình i18n của bạn trong khi vẫn giữ quyền kiểm soát hoàn toàn đối với nội dung của bạn, Intlayer cũng cung cấp lệnh tự động trích xuất `intlayer transform` (xem [tài liệu CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/cli/transform.md)), hoặc lệnh `Intlayer: extract content to Dictionary` từ tiện ích mở rộng Intlayer VS Code (xem [tài liệu tiện ích mở rộng VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/vs_code_extension.md)).
+
+## Cách sử dụng
+
+### Vite
+
+Đối với các ứng dụng dựa trên Vite (React, Vue, Svelte, v.v.), cách dễ nhất để sử dụng trình biên dịch là thông qua plugin `vite-intlayer`.
+
+#### Cài đặt
+
+```bash
+npm install vite-intlayer
+```
+
+#### Cấu hình
+
+Cập nhật file `vite.config.ts` của bạn để bao gồm plugin `intlayerCompiler`:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer, intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer(),
+    intlayerCompiler(), // Thêm plugin trình biên dịch
+  ],
+});
+```
+
+#### Hỗ trợ Framework
+
+Plugin Vite tự động phát hiện và xử lý các loại file khác nhau:
+
+- **React / JSX / TSX**: Xử lý một cách tự nhiên.
+- **Vue**: Yêu cầu `@intlayer/vue-compiler`.
+- **Svelte**: Yêu cầu `@intlayer/svelte-compiler`.
+
+Hãy chắc chắn cài đặt gói trình biên dịch phù hợp với framework của bạn:
+
+```bash
+# Dành cho Vue
+npm install @intlayer/vue-compiler
+
+# Dành cho Svelte
+npm install @intlayer/svelte-compiler
+```
+
+### Next.js (Babel)
+
+Đối với Next.js hoặc các ứng dụng dựa trên Webpack sử dụng Babel, bạn có thể cấu hình trình biên dịch bằng cách sử dụng plugin `@intlayer/babel`.
+
+#### Cài đặt
+
+```bash
+npm install @intlayer/babel
+```
+
+#### Cấu hình
+
+Cập nhật `babel.config.js` (hoặc `babel.config.json`) của bạn để bao gồm plugin trích xuất. Chúng tôi cung cấp một helper `getExtractPluginOptions` để tự động tải cấu hình Intlayer của bạn.
+
+```js fileName="babel.config.js"
+const {
+  intlayerExtractBabelPlugin,
+  intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getOptimizePluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    // Extract content from components into dictionaries
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+    // Optimize imports by replacing useIntlayer with direct dictionary imports
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
+};
+```
+
+Cấu hình này đảm bảo rằng nội dung được khai báo trong các component của bạn sẽ được tự động trích xuất và sử dụng để tạo từ điển trong quá trình build.

package/docs/vi/intlayer_with_nextjs_14.md

@@ -17,7 +17,6 @@ slugs:
   - 14
 applicationTemplate: https://github.com/aymericzip/intlayer-next-14-template
 history:
-  - version: 7.0.6
   - version: 6.2.0
     date: 2025-10-09
     changes: Thêm tài liệu cho hook `useLocale` với tùy chọn `onLocaleChange`
@@ -26,7 +25,7 @@ history:
     changes: Thêm tài liệu cho hàm `getLocale` trên các hành động server
   - version: 5.6.2
     date: 2025-09-22
-  changes: Thêm tài liệu cho helper `multipleMiddlewares`
+    changes: Thêm tài liệu cho helper `multipleMiddlewares`
   - version: 5.6.0
     date: 2025-07-06
     changes: Chuyển hàm `withIntlayer()` thành hàm dựa trên promise

package/docs/vi/intlayer_with_nextjs_15.md

@@ -26,7 +26,7 @@ history:
     changes: Thêm đề cập đến hàm `withIntlayerSync()`
   - version: 6.2.0
     date: 2025-10-09
-  changes: Thêm tài liệu cho hook `useLocale` với tùy chọn `onLocaleChange`
+    changes: Thêm tài liệu cho hook `useLocale` với tùy chọn `onLocaleChange`
   - version: 5.6.6
     date: 2025-10-02
     changes: Thêm tài liệu cho hàm `getLocale` trong các hành động server

package/docs/zh/bundle_optimization.md

@@ -153,9 +153,13 @@ const content = useIntlayer("my-key");
 // 优化后的代码（动态）
 const content = useDictionaryAsync({
   en: () =>
-    import(".intlayer/dynamic_dictionary/en.json").then((mod) => mod.default),
+    import(".intlayer/dynamic_dictionary/my-key/en.json").then(
+      (mod) => mod.default
+    ),
   fr: () =>
-    import(".intlayer/dynamic_dictionary/fr.json").then((mod) => mod.default),
+    import(".intlayer/dynamic_dictionary/my-key/fr.json").then(
+      (mod) => mod.default
+    ),
 });
 ```
 

package/docs/zh/compiler.md

@@ -0,0 +1,133 @@
+---
+createdAt: 2025-09-09
+updatedAt: 2025-09-09
+title: Intlayer 编译器 | 用于 i18n 的自动内容提取
+description: 使用 Intlayer 编译器自动化您的国际化流程。直接从组件中提取内容，实现 Vite、Next.js 等框架中更快速、更高效的 i18n。
+keywords:
+  - Intlayer
+  - 编译器
+  - 国际化
+  - i18n
+  - 自动化
+  - 提取
+  - 速度
+  - Vite
+  - Next.js
+  - React
+  - Vue
+  - Svelte
+slugs:
+  - doc
+  - compiler
+history:
+  - version: 7.3.1
+    date: 2025-11-27
+    changes: 发布编译器
+---
+
+# Intlayer 编译器 | 用于 i18n 的自动内容提取
+
+## 什么是 Intlayer 编译器？
+
+**Intlayer 编译器** 是一个强大的工具，旨在自动化您应用程序中的国际化（i18n）流程。它会扫描您的源代码（JSX、TSX、Vue、Svelte）中的内容声明，提取它们，并自动生成所需的字典文件。这使您能够将内容与组件放置在一起，而 Intlayer 则负责管理和同步您的字典。
+
+## 为什么使用 Intlayer 编译器？
+
+- **自动化**：消除手动将内容复制粘贴到字典中的步骤。
+- **速度**：优化的内容提取，确保构建过程保持快速。
+- **开发者体验**：将内容声明保留在使用它们的位置，提高可维护性。
+- **实时更新**：支持热模块替换（HMR），在开发过程中即时反馈。
+
+请参阅[Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/compiler_vs_declarative_i18n.md)博客文章，了解更深入的比较。
+
+## 为什么不使用 Intlayer 编译器？
+
+虽然编译器提供了出色的"开箱即用"体验，但它也引入了一些您应该了解的权衡：
+
+- **启发式歧义**：编译器必须猜测什么是面向用户的内容，什么是应用程序逻辑（例如，`className="active"`、状态代码、产品 ID）。在复杂的代码库中，这可能导致误报或遗漏的字符串，需要手动注释和异常处理。
+- **仅静态提取**：基于编译器的提取依赖于静态分析。仅在运行时存在的字符串（API 错误代码、CMS 字段等）无法被编译器单独发现或翻译，因此您仍然需要补充的运行时 i18n 策略。
+
+有关更深入的架构比较，请参阅博客文章[Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/zh/compiler_vs_declarative_i18n.md)。
+
+作为替代方案，为了在保持对内容的完全控制的同时自动化您的 i18n 流程，Intlayer 还提供了自动提取命令 `intlayer transform`（请参阅[CLI 文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/cli/transform.md)），或 Intlayer VS Code 扩展的 `Intlayer: extract content to Dictionary` 命令（请参阅[VS Code 扩展文档](https://github.com/aymericzip/intlayer/blob/main/docs/docs/zh/vs_code_extension.md)）。
+
+## 使用方法
+
+### Vite
+
+对于基于 Vite 的应用（React、Vue、Svelte 等），使用编译器最简单的方法是通过 `vite-intlayer` 插件。
+
+#### 安装
+
+```bash
+npm install vite-intlayer
+```
+
+#### 配置
+
+更新你的 `vite.config.ts`，以包含 `intlayerCompiler` 插件：
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer, intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer(),
+    intlayerCompiler(), // 添加编译器插件
+  ],
+});
+```
+
+#### 框架支持
+
+Vite 插件会自动检测并处理不同的文件类型：
+
+- **React / JSX / TSX**：原生支持。
+- **Vue**：需要安装 `@intlayer/vue-compiler`。
+- **Svelte**：需要安装 `@intlayer/svelte-compiler`。
+
+请确保为你的框架安装了相应的编译器包：
+
+```bash
+# Vue 使用
+npm install @intlayer/vue-compiler
+
+# Svelte 使用
+npm install @intlayer/svelte-compiler
+```
+
+### Next.js（Babel）
+
+对于使用 Babel 的 Next.js 或其他基于 Webpack 的应用，可以通过 `@intlayer/babel` 插件配置编译器。
+
+#### 安装
+
+```bash
+npm install @intlayer/babel
+```
+
+#### 配置
+
+更新您的 `babel.config.js`（或 `babel.config.json`）以包含提取插件。我们提供了一个辅助函数 `getExtractPluginOptions`，用于自动加载您的 Intlayer 配置。
+
+```js fileName="babel.config.js"
+const {
+  intlayerExtractBabelPlugin,
+  intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getOptimizePluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    // Extract content from components into dictionaries
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+    // Optimize imports by replacing useIntlayer with direct dictionary imports
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
+};
+```
+
+此配置确保在构建过程中，组件中声明的内容会被自动提取并用于生成字典。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/docs",
-  "version": "7.3.1",
+  "version": "7.3.2-canary.1",
   "private": false,
   "description": "Intlayer documentation",
   "keywords": [
@@ -48,6 +48,7 @@
     "legal"
   ],
   "scripts": {
+    "_prepublish": "cp -f ../README.md ./README.md",
     "prebuild": "tsx tools/generateEntry.ts",
     "build": "tsdown --config tsdown.config.ts",
     "build:ci": "tsdown --config tsdown.config.ts",
@@ -57,7 +58,7 @@
     "format:fix": "biome format --write .",
     "lint": "biome lint .",
     "lint:fix": "biome lint --write .",
-    "prepublish": "cp -f ../README.md ./README.md",
+    "prepublish": "echo prepublish temporally disabled to avoid rewrite readme",
     "publish": "bun publish || true",
     "publish:canary": "bun publish --access public --tag canary || true",
     "publish:latest": "bun publish --access public --tag latest || true",
@@ -72,23 +73,23 @@
     "watch": "webpack --config ./webpack.config.ts --watch"
   },
   "dependencies": {
-    "@intlayer/config": "7.3.1",
-    "@intlayer/core": "7.3.1",
-    "@intlayer/types": "7.3.1"
+    "@intlayer/config": "7.3.2-canary.1",
+    "@intlayer/core": "7.3.2-canary.1",
+    "@intlayer/types": "7.3.2-canary.1"
   },
   "devDependencies": {
-    "@intlayer/api": "7.3.1",
-    "@intlayer/cli": "7.3.1",
+    "@intlayer/api": "7.3.2-canary.1",
+    "@intlayer/cli": "7.3.2-canary.1",
     "@types/node": "24.10.1",
     "@utils/ts-config": "1.0.4",
     "@utils/ts-config-types": "1.0.4",
     "@utils/tsdown-config": "1.0.4",
     "fast-glob": "3.3.3",
     "rimraf": "6.1.2",
-    "tsdown": "0.16.6",
+    "tsdown": "0.16.8",
     "tsx": "^4.20.6",
     "typescript": "5.9.3",
-    "vitest": "4.0.13"
+    "vitest": "4.0.14"
   },
   "engines": {
     "node": ">=14.18"

package/src/generated/docs.entry.ts

@@ -433,6 +433,25 @@ export const docsEntry = {
     id: readLocale('cli/watch.md', 'id'),
     vi: readLocale('cli/watch.md', 'vi'),
   } as unknown as Record<LocalesValues, Promise<string>>,
+  './docs/en/compiler.md': {
+    en: readLocale('compiler.md', 'en'),
+    ru: readLocale('compiler.md', 'ru'),
+    ja: readLocale('compiler.md', 'ja'),
+    fr: readLocale('compiler.md', 'fr'),
+    ko: readLocale('compiler.md', 'ko'),
+    zh: readLocale('compiler.md', 'zh'),
+    es: readLocale('compiler.md', 'es'),
+    de: readLocale('compiler.md', 'de'),
+    ar: readLocale('compiler.md', 'ar'),
+    it: readLocale('compiler.md', 'it'),
+    'en-GB': readLocale('compiler.md', 'en-GB'),
+    pt: readLocale('compiler.md', 'pt'),
+    hi: readLocale('compiler.md', 'hi'),
+    tr: readLocale('compiler.md', 'tr'),
+    pl: readLocale('compiler.md', 'pl'),
+    id: readLocale('compiler.md', 'id'),
+    vi: readLocale('compiler.md', 'vi'),
+  } as unknown as Record<LocalesValues, Promise<string>>,
   './docs/en/component_i18n.md': {
     en: readLocale('component_i18n.md', 'en'),
     ru: readLocale('component_i18n.md', 'ru'),