@intlayer/docs 8.7.7 → 8.7.8-canary.0

package/docs/vi/intlayer_with_astro.md

@@ -1,14 +1,14 @@
 ---
 createdAt: 2024-03-07
 updatedAt: 2025-12-30
-title: Astro i18n - Cách dịch ứng dụng Astro năm 2026
-description: Tìm hiểu cách thêm quốc tế hóa (i18n) vào trang web Astro của bạn bằng Intlayer. Làm theo hướng dẫn này để làm cho trang web của bạn đa ngôn ngữ.
+title: Dịch Astro i18n - Cách dịch ứng dụng Astro vào năm 2026
+description: Tìm hiểu cách thêm đa ngôn ngữ (i18n) vào trang web Astro của bạn bằng Intlayer. Làm theo hướng dẫn này để trang web của bạn có thể sử dụng nhiều ngôn ngữ.
 keywords:
-  - Quốc tế hóa
-  - Tài liệu
+  - đa ngôn ngữ
+  - tài liệu
   - Intlayer
   - Vite
-  - Astro
+  - React
   - i18n
   - JavaScript
 slugs:
@@ -16,73 +16,95 @@ slugs:
   - environment
   - astro
 applicationTemplate: https://github.com/aymericzip/intlayer-astro-template
+applicationShowcase: https://intlayer-astro-template.vercel.app
 history:
   - version: 7.5.9
     date: 2025-12-30
     changes: "Thêm lệnh init"
   - version: 6.2.0
     date: 2025-10-03
-    changes: "Làm mới hướng dẫn tích hợp Astro, cấu hình, cách sử dụng"
+    changes: "Cập nhật tích hợp Astro, cấu hình và cách sử dụng"
 ---
 
-# Dịch trang web Astro của bạn bằng Intlayer | Quốc tế hóa (i18n)
+# Dịch trang web Astro của bạn với Intlayer | Đa ngôn ngữ (i18n)
 
-## Intlayer là gì?
-
-**Intlayer** là một thư viện quốc tế hóa (i18n) mã nguồn mở sáng tạo, được thiết kế để đơn giản hóa việc hỗ trợ đa ngôn ngữ trong các ứng dụng web hiện đại.
-
-Với Intlayer, bạn có thể:
-
-- **Dễ dàng quản lý bản dịch** bằng cách sử dụng các từ điển khai báo ở cấp độ component.
-- **Định vị động metadata**, các route và nội dung.
-- **Đảm bảo hỗ trợ TypeScript** với các kiểu tự động tạo, cải thiện tính năng tự hoàn thành và phát hiện lỗi.
-- **Tận hưởng các tính năng nâng cao**, như phát hiện và chuyển đổi locale động.
+<Tabs defaultTab="code">
+  <Tab label="Mã nguồn" value="code">
 
----
+<iframe
+  src="https://ide.intlayer.org/aymericzip/intlayer-astro-template?file=intlayer.config.ts"
+  className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
+  title="Demo CodeSandbox - Cách đa ngôn ngữ hóa ứng dụng của bạn với Intlayer"
+  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
+  loading="lazy"
+/>
 
-## Hướng dẫn từng bước để thiết lập Intlayer trong Astro
+  </Tab>
+  <Tab label="Bản demo" value="demo">
 
 <iframe
-  src="https://stackblitz.com/github/aymericzip/intlayer-astro-template?embed=1&ctl=1&file=intlayer.config.ts"
+  src="https://intlayer-astro-template.vercel.app"
   className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
-  title="Demo CodeSandbox - Cách quốc tế hóa ứng dụng của bạn bằng Intlayer"
+  title="Bản demo — intlayer-astro-template"
   sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
   loading="lazy"
 />
 
-Xem [Mẫu Ứng Dụng](https://github.com/aymericzip/intlayer-astro-template) trên GitHub.
+  </Tab>
+</Tabs>
+
+## Mục lục
+
+<TOC/>
+
+## Intlayer là gì?
+
+**Intlayer** là một thư viện đa ngôn ngữ (i18n) mã nguồn mở sáng tạo được thiết kế để đơn giản hóa việc hỗ trợ nhiều ngôn ngữ trong các ứng dụng web hiện đại.
+
+Với Intlayer, bạn có thể:
+
+- **Quản lý bản dịch dễ dàng**: Sử dụng các từ điển khai báo ở cấp độ thành phần.
+- **Bản địa hóa động các metadata, route và nội dung**.
+- **Đảm bảo hỗ trợ TypeScript**: Với các kiểu dữ liệu được tạo tự động để tự động hoàn thành và phát hiện lỗi tốt hơn.
+- **Tận dụng các tính năng nâng cao**: Như phát hiện ngôn ngữ động và chuyển đổi ngôn ngữ.
+
+---
+
+## Hướng dẫn từng bước để cấu hình Intlayer trong Astro
+
+Xem [mẫu ứng dụng](https://github.com/aymericzip/intlayer-astro-template) trên GitHub.
 
 ### Bước 1: Cài đặt các phụ thuộc
 
-Cài đặt các gói cần thiết bằng trình quản lý gói của bạn:
+Cài đặt các gói cần thiết bằng trình quản lý gói ưa thích của bạn:
 
 ```bash packageManager="npm"
 npm install intlayer astro-intlayer
-# Tùy chọn: thêm hỗ trợ React island
+# tùy chọn: nếu bạn muốn thêm hỗ trợ React islands
 npm install react react-dom react-intlayer @astrojs/react
 ```
 
 ```bash packageManager="pnpm"
 pnpm add intlayer astro-intlayer
-# Tùy chọn: thêm hỗ trợ React island
+# tùy chọn: nếu bạn muốn thêm hỗ trợ React islands
 pnpm add react react-dom react-intlayer @astrojs/react
 ```
 
 ```bash packageManager="yarn"
 yarn add intlayer astro-intlayer
- # Tùy chọn: thêm hỗ trợ React island
+# tùy chọn: nếu bạn muốn thêm hỗ trợ React islands
 yarn add react react-dom react-intlayer @astrojs/react
 ```
 
 - **intlayer**
-  Gói cốt lõi cung cấp các công cụ quốc tế hóa cho quản lý cấu hình, dịch thuật, [khai báo nội dung](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dictionary/content_file.md), biên dịch lại, và [các lệnh CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/cli/index.md).
+  Gói cốt lõi cung cấp các công cụ i18n để quản lý cấu hình, bản dịch, [khai báo nội dung](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dictionary/content_file.md), chuyển mã và [các lệnh CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/cli/index.md).
 
 - **astro-intlayer**
-  Bao gồm plugin tích hợp Astro để tích hợp Intlayer với [trình đóng gói Vite](https://vite.dev/guide/why.html#why-bundle-for-production), cũng như middleware để phát hiện ngôn ngữ ưu tiên của người dùng, quản lý cookie, và xử lý chuyển hướng URL.
+  Plugin tích hợp Astro để kết nối Intlayer với [trình đóng gói Vite](https://vite.dev/guide/why.html#why-bundle-for-production); nó cũng bao gồm middleware để phát hiện ngôn ngữ ưa thích của người dùng, quản lý cookie và xử lý chuyển hướng URL.
 
 ### Bước 2: Cấu hình dự án của bạn
 
-Tạo một tệp cấu hình để cấu hình các ngôn ngữ của ứng dụng của bạn:
+Tạo một file cấu hình để xác định các ngôn ngữ của ứng dụng:
 
 ```typescript fileName="intlayer.config.ts"
 import { Locales, type IntlayerConfig } from "intlayer";
@@ -93,6 +115,7 @@ const config: IntlayerConfig = {
       Locales.ENGLISH,
       Locales.FRENCH,
       Locales.SPANISH,
+      Locales.VIETNAMESE,
       // Các ngôn ngữ khác của bạn
     ],
     defaultLocale: Locales.ENGLISH,
@@ -102,11 +125,11 @@ const config: IntlayerConfig = {
 export default config;
 ```
 
-> Thông qua tệp cấu hình này, bạn có thể thiết lập các URL địa phương hóa, chuyển hướng middleware, tên cookie, vị trí và phần mở rộng của các khai báo nội dung của bạn, tắt các log của Intlayer trên console, và nhiều hơn nữa. Để xem danh sách đầy đủ các tham số có sẵn, hãy tham khảo [tài liệu cấu hình](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/configuration.md).
+> Thông qua file cấu hình này, bạn có thể thiết lập các URL bản địa hóa, chuyển hướng middleware, tên cookie, vị trí và phần mở rộng của các khai báo nội dung, tắt log Intlayer trong console, v.v. Để biết danh sách đầy đủ các tham số có sẵn, hãy xem [tài liệu cấu hình](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/configuration.md).
 
-### Bước 3: Tích hợp Intlayer vào Cấu hình Astro của bạn
+### Bước 3: Tích hợp Intlayer vào cấu hình Astro của bạn
 
-Thêm plugin intlayer vào cấu hình của bạn.
+Thêm plugin `intlayer` vào cấu hình Astro của bạn.
 
 ```typescript fileName="astro.config.ts"
 // @ts-check
@@ -120,11 +143,11 @@ export default defineConfig({
 });
 ```
 
-> Plugin tích hợp `intlayer()` cho Astro được sử dụng để tích hợp Intlayer với Astro. Nó đảm bảo việc xây dựng các tệp khai báo nội dung và giám sát chúng trong chế độ phát triển. Nó định nghĩa các biến môi trường Intlayer trong ứng dụng Astro. Ngoài ra, nó cung cấp các bí danh để tối ưu hiệu suất.
+> Plugin tích hợp `intlayer()` được sử dụng để tích hợp Intlayer với Astro. Nó đảm bảo việc tạo các file khai báo nội dung và theo dõi chúng trong chế độ phát triển. Nó xác định các biến môi trường Intlayer bên trong ứng dụng Astro và cung cấp các alias để tối ưu hóa hiệu suất.
 
-### Bước 4: Khai báo Nội dung của bạn
+### Bước 4: Khai báo nội dung của bạn
 
-Tạo và quản lý các khai báo nội dung để lưu trữ các bản dịch:
+Tạo và quản lý các khai báo nội dung của bạn để lưu trữ các bản dịch:
 
 ```tsx fileName="src/app.content.tsx"
 import { t, type Dictionary } from "intlayer";
@@ -137,6 +160,7 @@ const appContent = {
       en: "Hello World",
       fr: "Bonjour le monde",
       es: "Hola mundo",
+      vi: "Xin chào thế giới",
     }),
   },
 } satisfies Dictionary;
@@ -144,16 +168,15 @@ const appContent = {
 export default appContent;
 ```
 
-> Các khai báo nội dung của bạn có thể được định nghĩa ở bất kỳ đâu trong ứng dụng của bạn miễn là chúng được đưa vào thư mục `contentDir` (mặc định là `./src`). Và phù hợp với phần mở rộng tệp khai báo nội dung (mặc định là `.content.{json,ts,tsx,js,jsx,mjs,cjs}`).
+> Các khai báo nội dung có thể được định nghĩa ở bất kỳ đâu trong ứng dụng của bạn, miễn là chúng nằm trong `contentDir` (mặc định là `./src`) và khớp với phần mở rộng của file khai báo nội dung (mặc định là `.content.{json,ts,tsx,js,jsx,mjs,cjs}`).
 
-> Để biết thêm chi tiết, tham khảo [tài liệu khai báo nội dung](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dictionary/content_file.md).
+> Để biết thêm thông tin, hãy xem [tài liệu khai báo nội dung](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/dictionary/content_file.md).
 
-### Bước 5: Sử dụng nội dung của bạn trong Astro
+### Bước 5: Sử dụng nội dung trong Astro
 
-Bạn có thể sử dụng trực tiếp các từ điển trong các tệp `.astro` bằng cách sử dụng các helper cốt lõi được xuất bởi `intlayer`.
+Bạn có thể sử dụng các từ điển trực tiếp trong các file `.astro` bằng cách sử dụng các hàm hỗ trợ cốt lõi được xuất từ `intlayer`.
 
 ```astro fileName="src/pages/index.astro"
-<!-- astro -->
 ---
 import { getIntlayer } from "intlayer";
 import appContent from "../app.content";
@@ -161,7 +184,7 @@ import appContent from "../app.content";
 const { title } = getIntlayer('app');
 ---
 
-<html lang="en">
+<html lang="vi">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width" />
@@ -173,12 +196,11 @@ const { title } = getIntlayer('app');
 </html>
 ```
 
-### Bước 6: Định tuyến theo ngôn ngữ
+### Bước 6: Định tuyến bản địa hóa
 
-Tạo một đoạn route động để phục vụ các trang được địa phương hóa, ví dụ `src/pages/[locale]/index.astro`:
+Tạo các đoạn route động (ví dụ: `src/pages/[locale]/index.astro`) để phục vụ các trang bản địa hóa:
 
 ```astro fileName="src/pages/[locale]/index.astro"
-<!-- astro -->
 ---
 import { getIntlayer } from "intlayer";
 
@@ -188,11 +210,11 @@ const { title } = getIntlayer('app');
 <h1>{title}</h1>
 ```
 
-Việc tích hợp Astro thêm một middleware Vite trong quá trình phát triển giúp định tuyến theo ngôn ngữ và định nghĩa môi trường. Bạn vẫn có thể liên kết giữa các ngôn ngữ bằng logic riêng của mình hoặc các hàm tiện ích như `getLocalizedUrl` từ `intlayer`.
+Tích hợp Astro thêm middleware Vite giúp định tuyến nhận biết ngôn ngữ và định nghĩa môi trường trong quá trình phát triển. Bạn cũng có thể sử dụng logic của riêng mình hoặc các công cụ `intlayer` như `getLocalizedUrl` để liên kết giữa các ngôn ngữ.
 
-### Bước 7: Tiếp tục sử dụng framework yêu thích của bạn
+### Bước 7: Tiếp tục sử dụng Framework yêu thích của bạn
 
-Tiếp tục sử dụng framework yêu thích của bạn để xây dựng ứng dụng.
+Tiếp tục xây dựng ứng dụng của bạn bằng cách sử dụng framework mà bạn chọn.
 
 - Intlayer + React: [Intlayer với React](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/intlayer_with_vite+react.md)
 - Intlayer + Vue: [Intlayer với Vue](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/intlayer_with_vite+vue.md)
@@ -202,54 +224,150 @@ Tiếp tục sử dụng framework yêu thích của bạn để xây dựng ứ
 
 ### Cấu hình TypeScript
 
-Intlayer sử dụng module augmentation để tận dụng các lợi ích của TypeScript và làm cho codebase của bạn mạnh mẽ hơn.
+Intlayer sử dụng cơ chế mở rộng module (module augmentation) để tận dụng TypeScript, làm cho cơ sở mã của bạn mạnh mẽ hơn.
 
-![Tự động hoàn thành](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
+![Autocompletion](https://github.com/aymericzip/intlayer/blob/main/docs/assets/autocompletion.png?raw=true)
 
-![Lỗi dịch thuật](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
+![Translation Error](https://github.com/aymericzip/intlayer/blob/main/docs/assets/translation_error.png?raw=true)
 
-Đảm bảo cấu hình TypeScript của bạn bao gồm các kiểu được tự động tạo.
+Đảm bảo cấu hình TypeScript của bạn bao gồm các kiểu dữ liệu được tạo tự động.
 
 ```json5 fileName="tsconfig.json"
 {
-  // ... Các cấu hình TypeScript hiện có của bạn
+  // ... cấu hình TypeScript hiện tại của bạn
   "include": [
-    // ... Các cấu hình TypeScript hiện có của bạn
-    ".intlayer/**/*.ts", // Bao gồm các kiểu được tự động tạo
+    // ... cấu hình TypeScript hiện tại của bạn
+    ".intlayer/**/*.ts", // Bao gồm các kiểu dữ liệu được tạo tự động
   ],
 }
 ```
 
 ### Cấu hình Git
 
-Khuyến nghị bạn nên bỏ qua các file được tạo bởi Intlayer. Điều này giúp bạn tránh việc commit các file này vào kho Git của mình.
+Khuyên bạn nên bỏ qua các file được tạo bởi Intlayer. Điều này ngăn chúng được commit vào kho lưu trữ Git của bạn.
 
-Để làm điều này, bạn có thể thêm các chỉ dẫn sau vào file `.gitignore` của bạn:
+Để làm điều đó, hãy thêm các hướng dẫn sau vào file `.gitignore` của bạn:
 
 ```bash
-#  Bỏ qua các file được tạo bởi Intlayer
+# Bỏ qua các file được tạo bởi Intlayer
 .intlayer
 ```
 
-### Extension VS Code
+### Tiện ích mở rộng VS Code
 
-Để cải thiện trải nghiệm phát triển với Intlayer, bạn có thể cài đặt **Extension Intlayer chính thức cho VS Code**.
+Để cải thiện trải nghiệm phát triển của bạn với Intlayer, bạn có thể cài đặt **tiện ích mở rộng Intlayer chính thức cho VS Code**.
 
 [Cài đặt từ VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)
 
-Extension này cung cấp:
+Tiện ích này sẽ cung cấp:
 
 - **Tự động hoàn thành** cho các khóa dịch.
-- **Phát hiện lỗi thời gian thực** cho các bản dịch bị thiếu.
-- **Xem trước nội dung dịch ngay trong dòng**.
-- **Hành động nhanh** để dễ dàng tạo và cập nhật bản dịch.
+- **Phát hiện lỗi thời gian thực** cho các bản dịch còn thiếu.
+- **Xem trước trực tiếp** nội dung đã dịch.
+- **Các hành động nhanh** để tạo và cập nhật bản dịch dễ dàng.
 
-Để biết thêm chi tiết về cách sử dụng extension, tham khảo [Tài liệu Extension Intlayer VS Code](https://intlayer.org/doc/vs-code-extension).
+Để biết thêm thông tin về cách sử dụng tiện ích này, hãy xem [tài liệu tiện ích VS Code](https://intlayer.org/doc/vs-code-extension).
 
 ---
 
-### Tiến xa hơn
+### (Tùy chọn) Bước 1 : Trích xuất nội dung các thành phần của bạn
+
+Nếu bạn có một cơ sở mã hiện có, việc chuyển đổi hàng nghìn tệp có thể tốn nhiều thời gian.
+
+Để đơn giản hóa quy trình này, Intlayer đề xuất một [trình biên dịch](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/compiler.md) / [trình trích xuất](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/cli/extract.md) để chuyển đổi các thành phần của bạn và trích xuất nội dung.
+
+Để thiết lập, bạn có thể thêm phần `compiler` vào tệp `intlayer.config.ts` của mình:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import { type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  // ... Phần còn lại của cấu hình
+  compiler: {
+    /**
+     * Cho biết trình biên dịch có nên được bật hay không.
+     */
+    enabled: true,
+
+    /**
+     * Xác định đường dẫn các tệp đầu ra
+     */
+    output: ({ fileName, extension }) => `./${fileName}${extension}`,
+
+    /**
+     * Cho biết các thành phần có nên được lưu sau khi chuyển đổi hay không. Bằng cách đó, trình biên dịch có thể được chạy chỉ một lần để chuyển đổi ứng dụng, sau đó có thể được gỡ bỏ.
+     */
+    saveComponents: false,
+
+    /**
+     * Tiền tố khóa từ điển
+     */
+    dictionaryKeyPrefix: "",
+  },
+};
+
+export default config;
+```
+
+<Tabs>
+ <Tab value='Lệnh trích xuất'>
+
+Chạy trình trích xuất để chuyển đổi các thành phần và trích xuất nội dung
+
+```bash packageManager="npm"
+npx intlayer extract
+```
+
+```bash packageManager="pnpm"
+pnpm intlayer extract
+```
+
+```bash packageManager="yarn"
+yarn intlayer extract
+```
+
+```bash packageManager="bun"
+bun x intlayer extract
+```
+
+ </Tab>
+ <Tab value='Trình biên dịch Babel'>
+
+Cập nhật `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
+  ],
+});
+```
 
-Để tiến xa hơn, bạn có thể triển khai [trình soạn thảo trực quan](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/intlayer_visual_editor.md) hoặc tách nội dung của bạn ra ngoài bằng cách sử dụng [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/intlayer_CMS.md).
+```bash packageManager="npm"
+npm run build # Hoặc npm run dev
+```
+
+```bash packageManager="pnpm"
+pnpm run build # Or pnpm run dev
+```
+
+```bash packageManager="yarn"
+yarn build # Or yarn dev
+```
+
+```bash packageManager="bun"
+bun run build # Or bun run dev
+```
+
+ </Tab>
+</Tabs>
 
 ---
+
+### Tìm hiểu sâu hơn
+
+Nếu bạn muốn tìm hiểu thêm, bạn cũng có thể triển khai [Visual Editor](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/intlayer_visual_editor.md) hoặc sử dụng [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/intlayer_CMS.md) để quản lý nội dung bên ngoài.