@intlayer/docs 7.0.6 → 7.0.8-canary.0

package/docs/vi/autoFill.md

@@ -0,0 +1,284 @@
+---
+createdAt: 2025-03-13
+updatedAt: 2025-09-20
+title: Tự Động Điền
+description: Tìm hiểu cách sử dụng chức năng tự động điền trong Intlayer để tự động điền nội dung dựa trên các mẫu định sẵn. Theo dõi tài liệu này để triển khai các tính năng tự động điền một cách hiệu quả trong dự án của bạn.
+keywords:
+  - Tự Động Điền
+  - Tự Động Hóa Nội Dung
+  - Nội Dung Động
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - auto-fill
+history:
+  - version: 7.0.0
+    date: 2025-10-23
+    changes: Đổi tên `autoFill` thành `fill` và cập nhật hành vi
+  - version: 6.0.0
+    date: 2025-09-20
+    changes: Thêm cấu hình toàn cục
+  - version: 6.0.0
+    date: 2025-09-17
+    changes: Thêm biến `{{fileName}}`
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Khởi tạo lịch sử
+---
+
+# Dịch Tệp Khai Báo Nội Dung Tự Động Điền
+
+**Các tệp khai báo nội dung tự động điền** trong CI của bạn là một cách để tăng tốc quy trình phát triển.
+
+## Hành Vi Mặc Định
+
+Theo mặc định, `fill` được đặt là `true` toàn cục, có nghĩa là Intlayer sẽ tự động điền tất cả các tệp nội dung và chỉnh sửa chính tệp đó. Hành vi này có thể được tùy chỉnh theo nhiều cách:
+
+### Tùy Chọn Cấu Hình Toàn Cục
+
+1. **`fill: true` (mặc định)** - Tự động điền tất cả các locale và chỉnh sửa tệp hiện tại
+2. **`fill: false`** - Vô hiệu hóa tự động điền cho tệp nội dung này
+3. **`fill: "path/to/file"`** - Tạo/cập nhật tệp được chỉ định mà không chỉnh sửa tệp hiện tại
+4. **`fill: { [key in Locales]?: string }`** - Tạo/cập nhật tệp được chỉ định cho từng locale
+
+### Thay Đổi Hành Vi trong v7
+
+Trong v7, hành vi của lệnh `fill` đã được cập nhật:
+
+- **`fill: true`** - Viết lại tệp hiện tại với nội dung đã điền cho tất cả các locale
+- **`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
+
+Khi sử dụng tùy chọn đường dẫn để ghi vào một tệp khác, cơ chế điền hoạt động thông qua mối quan hệ _master-slave_ giữa các tệp khai báo nội dung. Tệp chính (master) đóng vai trò là nguồn dữ liệu chính xác, và khi nó được cập nhật, Intlayer sẽ tự động áp dụng những thay đổi đó cho các tệp khai báo dẫn xuất (đã điền) được chỉ định bởi đường dẫn.
+
+### Tùy Chỉnh Theo Locale
+
+Bạn cũng có thể tùy chỉnh hành vi cho từng locale bằng cách sử dụng một đối tượng:
+
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  content: {
+    internationalization: {
+      locales: [Locales.ENGLISH, Locales.FRENCH, Locales.POLISH],
+      defaultLocale: Locales.ENGLISH,
+      requiredLocales: [Locales.ENGLISH], // Khuyến nghị để tránh lỗi Property 'pl' is missing in type '{ en: string; xxx }' trong hàm t của bạn nếu
+    },
+  },
+  dictionary: {
+    fill: {
+      en: true, // Điền và chỉnh sửa tệp hiện tại cho tiếng Anh
+      fr: "./translations/fr.json", // Tạo tệp riêng cho tiếng Pháp
+      es: false, // Vô hiệu hóa điền cho tiếng Tây Ban Nha
+    },
+  },
+};
+```
+
+Điều này cho phép bạn có các hành vi điền khác nhau cho các locale khác nhau trong cùng một dự án.
+
+```ts fileName="src/components/example/example.content.ts"
+import { Locales, type Dictionary } from "intlayer";
+
+const exampleContent = {
+  key: "example",
+  locale: Locales.ENGLISH,
+  fill: "./example.content.json",
+  content: {
+    contentExample: "Đây là một ví dụ về nội dung",
+  },
+} satisfies Dictionary;
+
+export default exampleContent;
+```
+
+Dưới đây là một [tệp khai báo nội dung theo từng locale](https://github.com/aymericzip/intlayer/blob/main/docs/docs/vi/per_locale_file.md) sử dụng chỉ dẫn `fill`.
+
+Sau đó, khi bạn chạy lệnh sau:
+
+```bash
+npx intlayer fill --file 'src/components/example/example.content.ts'
+```
+
+Intlayer sẽ tự động tạo tệp khai báo dẫn xuất tại `src/components/example/example.content.json`, điền vào tất cả các locale chưa được khai báo trong tệp chính.
+
+```json5 fileName="src/components/example/example.content.json"
+{
+  "key": "example",
+  "content": {
+    "contentExample": {
+      "nodeType": "translation",
+      "translation": {
+        "fr": "Ceci est un exemple de contenu",
+        "es": "Este es un ejemplo de contenido",
+      },
+    },
+  },
+}
+```
+
+Sau đó, cả hai tệp khai báo sẽ được hợp nhất thành một từ điển duy nhất, có thể truy cập bằng cách sử dụng hook tiêu chuẩn `useIntlayer("example")` (react) / composable (vue).
+
+## Cấu hình toàn cục
+
+Bạn có thể cấu hình tự động điền toàn cục trong tệp `intlayer.config.ts`.
+
+```ts fileName="intlayer.config.ts"
+import { type IntlayerConfig, Locales } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+  },
+  dictionary: {
+    // Tự động tạo các bản dịch còn thiếu cho tất cả các từ điển
+    fill: "./{{fileName}}Filled.content.ts",
+    //
+    // fill: "/messages/{{locale}}/{{key}}/{{fileName}}.content.json",
+    //
+    // fill: true, // tự động tạo các bản dịch còn thiếu cho tất cả các từ điển giống như sử dụng "./{{fileName}}.content.json"
+    //
+    // fill: {
+    //   en: "./{{fileName}}.en.content.json",
+    //   fr: "./{{fileName}}.fr.content.json",
+    //   es: "./{{fileName}}.es.content.json",
+    // },
+  },
+};
+
+export default config;
+```
+
+Bạn vẫn có thể tinh chỉnh từng từ điển bằng cách sử dụng trường `fill` trong các tệp nội dung. Intlayer sẽ ưu tiên cấu hình theo từng từ điển trước, sau đó mới dùng cấu hình toàn cục.
+
+## Định dạng tệp tự động điền
+
+Định dạng được khuyến nghị cho các tệp khai báo tự động điền là **JSON**, giúp tránh các ràng buộc về định dạng. Tuy nhiên, Intlayer cũng hỗ trợ các định dạng `.ts`, `.js`, `.mjs`, `.cjs` và các định dạng khác.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: "./example.filled.content.ts",
+  content: {
+    // Nội dung của bạn
+  },
+};
+```
+
+Điều này sẽ tạo tệp tại:
+
+```
+src/components/example/example.filled.content.ts
+```
+
+> Việc tạo các tệp `.js`, `.ts` và các tệp tương tự hoạt động như sau:
+>
+> - Nếu tệp đã tồn tại, Intlayer sẽ phân tích nó bằng cách sử dụng AST (Cây cú pháp trừu tượng) để xác định từng trường và chèn các bản dịch còn thiếu.
+> - Nếu tệp không tồn tại, Intlayer sẽ tạo tệp đó bằng cách sử dụng mẫu tệp khai báo nội dung mặc định.
+
+## Đường dẫn tuyệt đối
+
+Trường `fill` cũng hỗ trợ các đường dẫn tuyệt đối.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: "/messages/example.content.json",
+  content: {
+    // Nội dung của bạn
+  },
+};
+```
+
+Điều này sẽ tạo tệp tại:
+
+```
+/messages/example.content.json
+```
+
+## Tự động tạo tệp khai báo nội dung theo từng locale
+
+Trường `fill` cũng hỗ trợ tạo các tệp khai báo nội dung **theo từng locale**.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: {
+    fr: "./example.fr.content.json",
+    es: "./example.es.content.json",
+  },
+  content: {
+    // Nội dung của bạn
+  },
+};
+```
+
+Điều này sẽ tạo hai tệp riêng biệt:
+
+- `src/components/example/example.fr.content.json`
+- `src/components/example/example.es.content.json`
+
+> Trong trường hợp này, nếu đối tượng không chứa tất cả các locale, Intlayer sẽ bỏ qua việc tạo các locale còn lại.
+
+## Lọc tự động điền cho locale cụ thể
+
+Sử dụng một đối tượng cho trường `fill` cho phép bạn áp dụng bộ lọc và chỉ tạo các tệp locale cụ thể.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: {
+    fr: "./example.fr.content.json",
+  },
+  content: {
+    // Nội dung của bạn
+  },
+};
+```
+
+Điều này chỉ tạo tệp dịch tiếng Pháp.
+
+## Biến đường dẫn
+
+Bạn có thể sử dụng các biến bên trong đường dẫn `fill` để giải quyết động các đường dẫn đích cho các tệp được tạo ra.
+
+**Các biến có sẵn:**
+
+- `{{locale}}` – Mã locale (ví dụ: `fr`, `es`)
+- `{{fileName}}` – Tên tệp (ví dụ: `index`)
+- `{{key}}` – Khóa từ điển (ví dụ: `example`)
+
+```ts fileName="src/components/example/index.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: "/messages/{{locale}}/{{key}}.content.json",
+  content: {
+    // Nội dung của bạn
+  },
+};
+```
+
+Điều này sẽ tạo ra:
+
+- `/messages/fr/example.content.json`
+- `/messages/es/example.content.json`
+
+```ts fileName="src/components/example/index.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: "./{{fileName}}.content.json",
+  content: {
+    // Nội dung của bạn
+  },
+};
+```
+
+Điều này sẽ tạo ra:
+
+- `./index.content.json`
+- `./index.content.json`

package/docs/vi/component_i18n.md

@@ -0,0 +1,186 @@
+---
+createdAt: 2024-03-07
+updatedAt: 2025-09-30
+title: Tạo một component đa ngôn ngữ (thư viện i18n) trong React và Next.js
+description: Tìm hiểu cách khai báo và lấy nội dung bản địa hóa để xây dựng một component React hoặc Next.js đa ngôn ngữ với Intlayer.
+keywords:
+  - i18n
+  - component
+  - react
+  - đa ngôn ngữ
+  - next.js
+  - intlayer
+slugs:
+  - doc
+  - component
+  - i18n
+applicationTemplate: https://github.com/aymericzip/intlayer-vite-react-template
+youtubeVideo: https://www.youtube.com/watch?v=dS9L7uJeak4
+---
+
+# Cách tạo một component đa ngôn ngữ (i18n) với Intlayer
+
+Hướng dẫn này trình bày các bước tối thiểu để làm cho một component giao diện người dùng đa ngôn ngữ trong hai thiết lập phổ biến:
+
+- React (Vite/SPA)
+- Next.js (App Router)
+
+Bạn sẽ bắt đầu bằng cách khai báo nội dung, sau đó lấy nội dung đó trong component của bạn.
+
+## 1) Khai báo nội dung của bạn (dùng chung cho React và Next.js)
+
+Tạo một file khai báo nội dung gần component của bạn. Điều này giữ cho các bản dịch gần với nơi chúng được sử dụng và cho phép an toàn kiểu dữ liệu.
+
+```ts fileName="component.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const componentContent = {
+  key: "component-example",
+  content: {
+    title: t({
+      en: "Hello",
+      fr: "Bonjour",
+      es: "Hola",
+    }),
+    description: t({
+      en: "A multilingual React component",
+      fr: "Un composant React multilingue",
+      es: "Un componente React multilingüe",
+    }),
+  },
+} satisfies Dictionary;
+
+export default componentContent;
+```
+
+JSON cũng được hỗ trợ nếu bạn thích dùng các file cấu hình.
+
+```json fileName="component.content.json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "component-example",
+  "content": {
+    "title": {
+      "nodeType": "translation",
+      "translation": { "en": "Hello", "fr": "Bonjour", "es": "Hola" }
+    },
+    "description": {
+      "nodeType": "translation",
+      "translation": {
+        "en": "A multilingual React component",
+        "fr": "Un composant React multilingue",
+        "es": "Un componente React multilingüe"
+      }
+    }
+  }
+}
+```
+
+## 2) Lấy nội dung của bạn
+
+### Trường hợp A — Ứng dụng React (Vite/SPA)
+
+Cách tiếp cận mặc định: sử dụng `useIntlayer` để lấy theo key. Điều này giữ cho các component gọn nhẹ và có kiểu dữ liệu.
+
+```tsx fileName="ComponentExample.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export function ComponentExample() {
+  const content = useIntlayer("component-example");
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+}
+```
+
+Kết xuất phía máy chủ hoặc bên ngoài provider: sử dụng `react-intlayer/server` và truyền một `locale` rõ ràng khi cần.
+
+```tsx fileName="ServerRenderedExample.tsx"
+import { useIntlayer } from "react-intlayer/server";
+
+export function ServerRenderedExample({ locale }: { locale: string }) {
+  const content = useIntlayer("component-example", locale);
+  return (
+    <>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </>
+  );
+}
+```
+
+Phương án thay thế: `useDictionary` có thể đọc toàn bộ đối tượng đã khai báo nếu bạn thích đặt cấu trúc tại nơi gọi.
+
+```tsx fileName="ComponentWithDictionary.tsx"
+import { useDictionary } from "react-intlayer";
+import componentContent from "./component.content";
+
+export function ComponentWithDictionary() {
+  const { title, description } = useDictionary(componentContent);
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{description}</p>
+    </div>
+  );
+}
+```
+
+### Trường hợp B — Next.js (App Router)
+
+Ưu tiên sử dụng server components để đảm bảo an toàn dữ liệu và hiệu năng. Sử dụng `useIntlayer` từ `next-intlayer/server` trong các file server, và `useIntlayer` từ `next-intlayer` trong các component phía client.
+
+```tsx fileName="app/[locale]/example/ServerComponent.tsx"
+import { useIntlayer } from "next-intlayer/server";
+
+export default function ServerComponent() {
+  const content = useIntlayer("component-example");
+  return (
+    <>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </>
+  );
+}
+```
+
+```tsx fileName="app/[locale]/example/ClientComponent.tsx"
+"use client";
+
+import { useIntlayer } from "next-intlayer";
+
+export function ClientComponent() {
+  const content = useIntlayer("component-example");
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+}
+```
+
+Mẹo: Để lấy metadata trang và SEO, bạn cũng có thể lấy nội dung bằng cách sử dụng `getIntlayer` và tạo URL đa ngôn ngữ thông qua `getMultilingualUrls`.
+
+## Tại sao cách tiếp cận component của Intlayer là tốt nhất
+
+- **Collocation**: Các khai báo nội dung nằm gần các component, giảm sự lệch pha và cải thiện việc tái sử dụng trong các hệ thống thiết kế.
+- **Type safety**: Các khóa và cấu trúc được kiểu hóa chặt chẽ; các bản dịch thiếu sẽ được phát hiện trong thời gian build thay vì khi chạy ứng dụng.
+- **Server-first**: Hoạt động nguyên bản trong các component phía server để tăng cường bảo mật và hiệu suất; các hook phía client vẫn giữ được tính tiện dụng.
+- **Tree-shaking**: Chỉ nội dung được component sử dụng mới được đóng gói, giữ cho payload nhỏ trong các ứng dụng lớn.
+- **DX & tooling**: Middleware tích hợp sẵn, trợ giúp SEO và tùy chọn Visual Editor/AI dịch thuật giúp đơn giản hóa công việc hàng ngày.
+
+Xem các so sánh và mẫu trong bài tổng hợp tập trung vào Next.js: https://intlayer.org/blog/next-i18next-vs-next-intl-vs-intlayer
+
+## Hướng dẫn và tài liệu liên quan
+
+- Cài đặt React (Vite): https://intlayer.org/doc/environment/vite-and-react
+- React Router v7: https://intlayer.org/doc/environment/vite-and-react/react-router-v7
+- Bắt đầu với TanStack: https://intlayer.org/doc/environment/vite-and-react/tanstack-start
+- Cài đặt Next.js: https://intlayer.org/doc/environment/nextjs
+- Tại sao chọn Intlayer thay vì next-intl hay next-i18next - https://intlayer.org/blog/next-i18next-vs-next-intl-vs-intlayer
+
+Các trang này bao gồm thiết lập end-to-end, providers, routing và trợ giúp SEO.