@intlayer/docs 7.0.0-canary.2 → 7.0.0-canary.3

package/docs/vi/releases/v7.md

@@ -0,0 +1,486 @@
+---
+createdAt: 2025-09-22
+updatedAt: 2025-09-23
+title: Intlayer v7 Mới - Có gì mới?
+description: Khám phá những điểm mới trong Intlayer v7. Cải tiến lớn về hiệu suất, trải nghiệm nhà phát triển và các tính năng mới để nâng cao quy trình quốc tế hóa của bạn.
+keywords:
+  - Intlayer
+  - Địa phương hóa
+  - Phát triển
+  - Hiệu suất
+  - Trải nghiệm nhà phát triển
+  - Tính năng
+  - React
+  - Next.js
+  - JavaScript
+  - TypeScript
+slugs:
+  - doc
+  - releases
+  - v7
+---
+
+# Intlayer v7 Mới - Có gì mới?
+
+Chào mừng đến với Intlayer v7! Phiên bản lớn này giới thiệu các cải tiến đáng kể về hiệu suất, an toàn kiểu và trải nghiệm nhà phát triển. Dưới đây là những điểm nổi bật, kèm theo ghi chú di chuyển và ví dụ thực tiễn.
+
+## Những điểm nổi bật
+
+- Chiến lược lưu bộ nhớ đệm để xây dựng nhanh hơn
+- Cải tiến việc tạo kiểu TypeScript với các kiểu riêng cho từng ngôn ngữ
+- Tối ưu gói: Các ngôn ngữ được lưu dưới dạng chuỗi thay vì enum
+- 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%
+- 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
+- Quản lý thử lại thông minh để đảm bảo độ chính xác dịch thuật
+- Xử lý song song để tăng tốc quá trình dịch thuật
+- Chia nhỏ thông minh để xử lý các tệp lớn trong giới hạn ngữ cảnh AI
+
+---
+
+## Hiệu suất: Bộ nhớ đệm để tăng tốc quá trình build
+
+Thay vì xây dựng lại các khai báo nội dung với esbuild trong mỗi lần build, phiên bản v7 triển khai một chiến lược lưu bộ nhớ đệm giúp tăng tốc quá trình build.
+
+```bash
+npx intlayer build
+```
+
+Hệ thống lưu bộ nhớ đệm mới:
+
+- Lưu trữ các khai báo nội dung đã biên dịch để tránh xử lý trùng lặp
+- Phát hiện thay đổi và chỉ xây dựng lại các tệp đã sửa đổi
+- Giảm đáng kể thời gian build cho các dự án lớn
+
+---
+
+## TypeScript: Tạo kiểu riêng cho từng ngôn ngữ
+
+Kiểu TypeScript giờ đây được tạo riêng cho từng ngôn ngữ, cung cấp kiểu mạnh hơn và loại bỏ các kiểu hợp nhất (union types) giữa các ngôn ngữ.
+
+**Hành vi v6:**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" } | { title: "Mon titre" } | { title: "Mi título" }
+```
+
+**Hành vi v7:**
+
+```tsx
+const content = getIntlayer("my-title-content", "en");
+// typeof content = { title: "My title" }
+```
+
+Lợi ích:
+
+- Tự động hoàn thành chính xác hơn trong IDE của bạn
+- An toàn kiểu tốt hơn, không bị lẫn lộn kiểu giữa các ngôn ngữ
+- Cải thiện hiệu suất bằng cách giảm độ phức tạp kiểu
+
+---
+
+## Tối ưu gói: Các ngôn ngữ dưới dạng chuỗi
+
+Kiểu `Locales` không còn là enum nữa, điều này có nghĩa là nó hoàn toàn có thể tree-shake và sẽ không làm phình to gói của bạn với hàng nghìn bản ghi ngôn ngữ không sử dụng.
+
+**v6:**
+
+```typescript
+import { Locales } from "intlayer";
+// Enum bao gồm tất cả các ngôn ngữ -> không thể tree-shake
+
+const locale: Locales = Locales.ENGLISH;
+```
+
+**v7:**
+
+```typescript
+import { Locales, Locale } from "intlayer";
+// Kiểu chuỗi -> hoàn toàn có thể tree-shake
+
+const locale: Locale = Locales.ENGLISH;
+```
+
+> Vì `Locales` không còn là enum nữa, bạn sẽ phải thay đổi kiểu từ `Locales` thành `Locale` để lấy locale dưới dạng kiểu.
+
+Xem [chi tiết triển khai](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts) để biết thêm thông tin.
+
+---
+
+## Chế độ định tuyến mới cho sự linh hoạt hơn
+
+Phiên bản v7 giới thiệu cấu hình `routing.mode` thống nhất thay thế cho các tùy chọn `prefixDefault` và `noPrefix` trước đây, cung cấp kiểm soát chi tiết hơn đối với cấu trúc URL.
+
+### Các chế độ định tuyến có sẵn
+
+- **`prefix-no-default`** (mặc định): Ngôn ngữ mặc định không có tiền tố, các ngôn ngữ khác có
+  - `/dashboard` (en) hoặc `/fr/dashboard` (fr)
+- **`prefix-all`**: Tất cả các ngôn ngữ đều có tiền tố
+  - `/en/dashboard` (en) hoặc `/fr/dashboard` (fr)
+- **`no-prefix`**: Không có tiền tố locale trong URL (locale được xử lý qua lưu trữ/headers)
+  - `/dashboard` cho tất cả các locale
+- **`search-params`**: Locale được truyền dưới dạng tham số truy vấn
+  - `/dashboard?locale=en` hoặc `/dashboard?locale=fr`
+
+### Cấu hình cơ bản
+
+```typescript
+// intlayer.config.ts
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default", // mặc định
+  },
+};
+```
+
+---
+
+## Tuân thủ GDPR: lưu trữ localStorage / cookies
+
+Phiên bản v7 ưu tiên quyền riêng tư của người dùng bằng cách sử dụng `localStorage` làm cơ chế lưu trữ mặc định thay vì cookies. Thay đổi này giúp tuân thủ GDPR bằng cách tránh yêu cầu đồng ý cookie cho tùy chọn locale.
+
+### Các tùy chọn cấu hình lưu trữ
+
+Trường `routing.storage` mới cũng có sẵn bên cạnh các tùy chọn trước đó như `middleware.cookieName` và `middleware.serverSetCookie`, cung cấp các cấu hình lưu trữ linh hoạt:
+
+```typescript
+// Vô hiệu hóa lưu trữ
+storage: false
+
+// Các loại lưu trữ đơn giản
+storage: 'cookie'
+storage: 'localStorage'
+storage: 'sessionStorage'
+
+// Cookie với các thuộc tính tùy chỉnh
+storage: {
+  type: 'cookie',
+  name: 'custom-locale',
+  domain: '.example.com',
+  secure: true,
+  sameSite: 'strict'
+}
+
+// localStorage với khóa tùy chỉnh
+storage: {
+  type: 'localStorage',
+  name: 'custom-locale'
+}
+
+// Nhiều loại lưu trữ để dự phòng
+storage: ['cookie', 'localStorage']
+```
+
+### Ví dụ cấu hình tuân thủ GDPR
+
+Dành cho các ứng dụng sản xuất cần cân bằng giữa chức năng và tuân thủ GDPR:
+
+```typescript
+// intlayer.config.ts
+export default {
+  internationalization: {
+    locales: ["en", "fr", "es"],
+    defaultLocale: "en",
+  },
+  routing: {
+    mode: "prefix-no-default",
+    storage: [
+      {
+        type: "localStorage", // Lưu trữ chính (không cần sự đồng ý)
+        name: "user-locale",
+      },
+      {
+        type: "cookie", // Lưu trữ cookie tùy chọn (cần sự đồng ý)
+        name: "user-locale",
+        secure: true,
+        sameSite: "strict",
+        httpOnly: false,
+      },
+    ],
+  },
+};
+```
+
+### Bật / tắt lưu trữ cookie
+
+Ví dụ sử dụng React / Next.js:
+
+Có thể được định nghĩa toàn cục:
+
+```typescript
+<IntlayerProvider isCookieEnabled={false}>
+  <App />
+</IntlayerProvider>
+```
+
+Có thể ghi đè cục bộ cho từng hook:
+
+```ts
+const { setLocale } = useLocale({ isCookieEnabled: false });
+
+setLocale("en");
+```
+
+**Lưu ý:** Cookie được bật theo mặc định.
+**Lưu ý:** Kiểm tra [yêu cầu cookie GDPR](https://gdpr.eu/cookies/) cho trường hợp sử dụng cụ thể của bạn.
+
+---
+
+## Trình chỉnh sửa trực quan: Gói nhỏ hơn 30%
+
+Gói Trình chỉnh sửa trực quan đã được tối ưu hóa để nhỏ hơn 30% so với phiên bản trước, nhờ vào:
+
+- Cải thiện hiệu suất trình chỉnh sửa mã
+- Loại bỏ các phụ thuộc không cần thiết trên các gói lõi của Intlayer
+- Cải tiến tree-shaking và đóng gói module
+
+Điều này giúp giảm thời gian tải xuống và cải thiện hiệu suất chạy ứng dụng của bạn.
+
+---
+
+## Lệnh fill: Hành vi cập nhật để quản lý nội dung tốt hơn
+
+Phiên bản v7 giới thiệu hành vi cải tiến cho lệnh `fill`, cung cấp quản lý nội dung linh hoạt và dễ dự đoán hơn:
+
+### Hành vi fill mới
+
+- **`fill: true`** - Ghi đè tệp hiện tại với nội dung đã điền cho tất cả các ngôn ngữ
+- **`fill: "path/to/file"`** - Điền vào tệp được chỉ định mà không sửa đổi tệp hiện tại
+- **`fill: false`** - Vô hiệu hóa hoàn toàn tính năng tự động điền
+
+### Hỗ trợ nâng cao cho các cấu trúc nội dung phức tạp
+
+Lệnh fill hiện hỗ trợ các cấu trúc khai báo nội dung phức tạp, bao gồm:
+
+- **Đối tượng ghép**: Các khai báo nội dung tham chiếu đến các đối tượng khác
+- **Nội dung giải cấu trúc**: Nội dung sử dụng các mẫu giải cấu trúc
+- **Tham chiếu lồng nhau**: Các đối tượng gọi lẫn nhau trong các hệ thống phân cấp phức tạp
+- **Cấu trúc nội dung động**: Nội dung có các thuộc tính điều kiện hoặc tính toán
+
+### Lợi ích
+
+- **Ý định rõ ràng hơn**: Hành vi giờ đây rõ ràng hơn về những gì được sửa đổi
+- **Tách biệt tốt hơn**: Các tệp nội dung có thể được giữ riêng biệt với các bản dịch đã điền
+- **Quy trình làm việc cải tiến**: Các nhà phát triển có nhiều quyền kiểm soát hơn về nơi lưu trữ các bản dịch
+- **Hỗ trợ cấu trúc phức tạp**: Xử lý các kiến trúc nội dung tinh vi với nhiều đối tượng liên kết phức tạp
+
+### Ví dụ sử dụng
+
+```typescript
+// Ghi đè tệp hiện tại với tất cả các ngôn ngữ
+const content = {
+  key: "example",
+  fill: true, // Ghi đè tệp này
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Điền vào tệp riêng biệt mà không sửa đổi tệp hiện tại
+const content = {
+  key: "example",
+  fill: "./translations.json", // Tạo/cập nhật translations.json
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Vô hiệu hóa tự động điền
+const content = {
+  key: "example",
+  fill: false, // Không tự động điền
+  content: {
+    title: "Hello World",
+  },
+};
+
+// Cấu trúc nội dung phức tạp với các đối tượng ghép
+const sharedContent = {
+  buttons: {
+    save: "Lưu",
+    cancel: "Hủy",
+  },
+};
+
+const content = {
+  key: "complex-example",
+  fill: true,
+  content: {
+    // Tham chiếu đến các đối tượng khác
+    sharedContent,
+
+    // Nội dung được giải cấu trúc
+    ...sharedContent,
+
+    // Tham chiếu lồng nhau
+    sections: [
+      {
+        ...sharedContent.buttons,
+        header: "Phần 1",
+      },
+    ],
+  },
+};
+```
+
+---
+
+## Tăng cường độ ổn định và quản lý bản dịch
+
+Phiên bản v7 giới thiệu một số cải tiến để làm cho việc dịch nội dung trở nên đáng tin cậy và hiệu quả hơn:
+
+### Cập nhật đầy đủ tệp khai báo nội dung
+
+Hệ thống hiện cập nhật các tệp `.content.{ts,js,cjs,mjs}` thay vì cập nhật từng phần, đảm bảo:
+
+- **Toàn vẹn dữ liệu**: Việc viết lại toàn bộ file ngăn ngừa các cập nhật một phần có thể làm hỏng nội dung
+- **Tính nhất quán**: Tất cả các ngôn ngữ được cập nhật đồng thời, duy trì sự đồng bộ
+- **Độ tin cậy**: Giảm nguy cơ các file nội dung bị thiếu hoặc bị lỗi định dạng
+
+### Quản lý thử lại thông minh
+
+Cơ chế thử lại mới ngăn việc đẩy nội dung với định dạng sai, và tránh làm gián đoạn toàn bộ quá trình điền nếu một yêu cầu thất bại.
+
+### Song song hóa để xử lý nhanh hơn
+
+Các thao tác dịch thuật hiện chạy theo hàng đợi để thực thi song song. Điều này tăng tốc đáng kể quá trình.
+
+### Chia nhỏ thông minh cho các file lớn
+
+Chiến lược chia nhỏ nâng cao xử lý các file nội dung lớn mà không vượt quá giới hạn ngữ cảnh của AI:
+
+### Ví dụ quy trình làm việc
+
+```typescript
+// File nội dung lớn được tự động chia nhỏ
+const content = {
+  key: "large-documentation",
+  fill: true,
+  content: {
+    // Nội dung lớn được tự động chia nhỏ để xử lý AI
+    introduction: "..." // hơn 5000 ký tự
+    sections: [
+      // Nhiều phần lớn
+    ]
+  }
+};
+```
+
+Hệ thống tự động:
+
+1. Phân tích kích thước và cấu trúc nội dung
+2. Chia nhỏ nội dung phù hợp
+3. Xử lý các phần song song
+4. Xác thực và thử lại nếu cần
+5. Tái tạo lại file hoàn chỉnh
+
+---
+
+## Ghi chú di chuyển từ v6
+
+### Các cấu hình đã loại bỏ
+
+- **`middleware.cookieName`**: Thay thế bằng `routing.storage`
+- **`middleware.serverSetCookie`**: Thay thế bằng `routing.storage`
+- **`middleware.prefixDefault`**: Thay thế bằng `routing.mode`
+- **`middleware.noPrefix`**: Thay thế bằng `routing.mode`
+
+### Bản đồ di chuyển
+
+#### Bản đồ cấu hình
+
+| Cấu hình v6                | Cấu hình v7                                             |
+| -------------------------- | ------------------------------------------------------- |
+| `autoFill: xxx`            | `fill: xxx`                                             |
+| `prefixDefault: false`     | `mode: 'prefix-no-default'`                             |
+| `prefixDefault: true`      | `mode: 'prefix-all'`                                    |
+| `noPrefix: true`           | `mode: 'no-prefix'`                                     |
+| `cookieName: 'my-locale'`  | `storage: { type: 'cookie', name: 'my-locale' }`        |
+| `serverSetCookie: 'never'` | `storage: false` hoặc loại bỏ cookie khỏi mảng storage` |
+
+#### Ví dụ di chuyển
+
+**Trước (v6):**
+
+```typescript
+export default {
+  middleware: {
+    headerName: "x-intlayer-locale",
+    cookieName: "intlayer-locale",
+    prefixDefault: false,
+    basePath: "",
+    serverSetCookie: "always",
+    noPrefix: false,
+  },
+};
+```
+
+**Sau (v7):**
+
+```typescript
+export default {
+  routing: {
+    mode: "prefix-no-default",
+    storage: "localStorage", // hoặc 'cookie' nếu bạn cần lưu trữ bằng cookie
+    headerName: "x-intlayer-locale",
+    basePath: "",
+    detectLocaleOnPrefetchNoPrefix: false,
+  },
+};
+```
+
+#### Bản đồ nội dung từ điển
+
+| Nội dung từ điển v6 | Nội dung từ điển v7 |
+| ------------------- | ------------------- |
+| `autoFill: xxx`     | `fill: xxx`         |
+
+#### Ví dụ di chuyển
+
+**Trước (v6):**
+
+```typescript
+const content = {
+  key: "example",
+  autoFill: true, // Viết lại file này
+  content: {
+    title: "Hello World",
+  },
+};
+```
+
+**Sau (v7):**
+
+```typescript
+const content = {
+  key: "example",
+  fill: true, // Ghi đè file này
+  content: {
+    title: "Hello World",
+  },
+};
+```
+
+---
+
+## Ghi chú di chuyển từ v5 lên v6
+
+Xem [ghi chú di chuyển từ v5 lên v6](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/releases/v6.md) để biết thêm thông tin.
+
+---
+
+## Liên kết hữu ích
+
+- [Tham khảo Cấu hình](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/configuration.md)
+- [Tài liệu Middleware](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/packages/next-intlayer/index.md)
+- [Kiểu TypeScript](https://github.com/aymericzip/intlayer/blob/main/packages/%40intlayer/types/src/index.ts)
+- [Hướng dẫn Cookie GDPR](https://gdpr.eu/cookies/)

package/docs/zh/intlayer_CMS.md

@@ -502,37 +502,14 @@ const config = {
 module.exports = config;
 ```
 
-此配置会将你的开发服务器包装在实时同步服务器中，启动时获取远程字典，并通过 SSE 从 CMS 流式传输更新。刷新页面即可看到更改。
-
-注意事项和限制：
-
-- 将实时同步的源添加到你的网站安全策略（CSP）中。确保在 `connect-src`（如果相关，还包括 `frame-ancestors`）中允许实时同步 URL。
-- 实时同步不适用于静态输出。对于 Next.js，页面必须是动态的，才能在运行时接收更新（例如，适当使用 `generateStaticParams`、`generateMetadata`、`getServerSideProps` 或 `getStaticProps`，以避免完全静态的限制）。
-
-```
-
 此设置将您的开发服务器与实时同步服务器包装在一起，在启动时获取远程字典，并通过 SSE 从 CMS 流式传输更新。刷新页面以查看更改。
 
 注意事项和限制：
 
 - 将实时同步源添加到您的站点安全策略（CSP）中。确保实时同步 URL 被允许在 `connect-src` 中（如果相关，也包括 `frame-ancestors`）。
 - 实时同步不适用于静态输出。对于 Next.js，页面必须是动态的才能在运行时接收更新（例如，适当使用 `generateStaticParams`、`generateMetadata`、`getServerSideProps` 或 `getStaticProps`，以避免完全静态的限制）。
-/// 在 CMS 中，每个字典都有一个 `live` 标志。只有 `live=true` 的字典才会通过实时同步 API 获取；其他字典则动态导入，并在运行时保持不变。
-/// `live` 标志在构建时对每个字典进行评估。如果远程内容在构建时未标记为 `live=true`，则必须重新构建以启用该字典的实时同步。
-/// 实时同步服务器必须能够写入 `.intlayer`。在容器中，确保对 `/.intlayer` 具有写入权限。
-///
-/// ## 调试
-///
-/// 如果遇到 CMS 相关问题，请检查以下内容：
-///
-/// - 应用程序是否正在运行。
-///
-/// - [`editor`](https://intlayer.org/doc/concept/configuration#editor-configuration) 配置是否在您的 Intlayer 配置文件中正确设置。
-///   - 必填字段：
-///
 - 应用程序 URL 应与您在编辑器配置中设置的 URL (`applicationURL`) 匹配。
 - CMS URL
-
 - 确保项目配置已推送到 Intlayer CMS。
 
 - 可视化编辑器使用 iframe 来显示您的网站。确保您网站的内容安全策略（CSP）允许 CMS URL 作为 `frame-ancestors`（默认是 'https://intlayer.org'）。检查编辑器控制台是否有任何错误。