@intlayer/docs 8.10.0-canary.1 → 8.10.1

package/docs/vi/dictionary/markdown.md

@@ -95,34 +95,34 @@ Bạn có thể khai báo nội dung Markdown bằng cách sử dụng hàm `md`
     ```
 
   </Tab>
-  <Tab label="Phát hiện Tự động" value="automatic-detection">
-    Nếu chuỗi chứa các chỉ báo Markdown phổ biến (như tiêu đề, danh sách, liên kết, v.v.), Intlayer sẽ tự động chuyển đổi nó.
+  <Tab label="Tệp Bên ngoài" value="external-files">
+    Nhập trực tiếp các tệp `.md` bằng cách sử dụng hàm `file`.
 
     ```typescript fileName="markdownDictionary.content.ts"
+    import { md, file, t } from "intlayer";
+
     export default {
       key: "app",
-      contentAutoTransformation: true, // Bật phát hiện tự động nội dung Markdown - Có thể được đặt toàn cục trong intlayer.config.ts
       content: {
-        myMarkdownContent: "## Tiêu đề của tôi \n\nLorem Ipsum",
+        content: t({
+          en: md(file("./myMarkdown.en.md")),
+          vi: md(file("./myMarkdown.vi.md")),
+        }),
       },
     };
     ```
 
   </Tab>
 
-  <Tab label="Tệp Bên ngoài" value="external-files">
-    Nhập trực tiếp các tệp `.md` bằng cách sử dụng hàm `file`.
+  <Tab label="Phát hiện Tự động" value="automatic-detection">
+    Nếu chuỗi chứa các chỉ báo Markdown phổ biến (như tiêu đề, danh sách, liên kết, v.v.), Intlayer sẽ tự động chuyển đổi nó.
 
     ```typescript fileName="markdownDictionary.content.ts"
-    import { md, file, t } from "intlayer";
-
     export default {
       key: "app",
+      contentAutoTransformation: true, // Bật phát hiện tự động nội dung Markdown - Có thể được đặt toàn cục trong intlayer.config.ts
       content: {
-        content: t({
-          en: md(file("./myMarkdown.en.md")),
-          vi: md(file("./myMarkdown.vi.md")),
-        }),
+        myMarkdownContent: "## Tiêu đề của tôi \n\nLorem Ipsum",
       },
     };
     ```
@@ -130,8 +130,6 @@ Bạn có thể khai báo nội dung Markdown bằng cách sử dụng hàm `md`
   </Tab>
 </Tabs>
 
----
-
 ## Render Markdown
 
 Intlayer cung cấp hai cách độc lập để render Markdown:
@@ -147,7 +145,7 @@ Render Markdown hỗ trợ **MDX** — sử dụng bất kỳ component JSX/fram
 ### 1. Render Tự động (thông qua `useIntlayer`)
 
 <Tabs group="framework">
-  <Tab label="React / Next.js" value="react">
+  <Tab label="React" value="react">
     Các node Markdown có thể được render trực tiếp dưới dạng JSX.
 
     ```tsx fileName="App.tsx"
@@ -197,6 +195,57 @@ Render Markdown hỗ trợ **MDX** — sử dụng bất kỳ component JSX/fram
     {myMarkdownContent.metadata.title}
     ```
 
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    Các node Markdown có thể được render trực tiếp dưới dạng JSX.
+
+    ```tsx fileName="App.tsx"
+    import { useIntlayer } from "next-intlayer";
+    import { MarkdownProvider } from "next-intlayer/markdown";
+
+    const AppContent = () => {
+      const { myMarkdownContent } = useIntlayer("app");
+
+      return <div>{myMarkdownContent}</div>;
+    };
+
+    const App = () => (
+      <MarkdownProvider
+        components={{
+          h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,
+          MyButton: (props) => <button {...props} />, // Component MDX
+        }}
+      >
+        <AppContent />
+      </MarkdownProvider>
+    );
+    ```
+
+    > Nếu không có `MarkdownProvider`, Intlayer sẽ render markdown bằng cách sử dụng trình phân tích cú pháp Markdown sang JSX mặc định.
+
+    Bạn cũng có thể cung cấp các ghi đè cục bộ cho các node cụ thể bằng phương thức `.use()`:
+
+    ```tsx
+    {myMarkdownContent.use({
+      h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,
+    })}
+    ```
+
+    Bạn có thể lấy Markdown dưới dạng chuỗi:
+
+    ```tsx
+    {myMarkdownContent.value}
+    {String(myMarkdownContent)}
+    {myMarkdownContent.toString()}
+    ```
+
+    Và bạn có thể truy cập siêu dữ liệu markdown của mình như sau:
+
+    ```tsx
+    {myMarkdownContent.metadata}
+    {myMarkdownContent.metadata.title}
+    ```
+
   </Tab>
   <Tab label="Vue" value="vue">
     Trong Vue, nội dung Markdown có thể được render bằng thẻ `component` tích hợp sẵn hoặc trực tiếp như một node.
@@ -441,7 +490,7 @@ Render Markdown hỗ trợ **MDX** — sử dụng bất kỳ component JSX/fram
 Các tiện ích này **chỉ render các chuỗi Markdown thô** và độc lập với `useIntlayer`. Hãy sử dụng chúng khi bạn cần render Markdown từ các nguồn khác ngoài từ điển của bạn.
 
 <Tabs group="framework">
-  <Tab label="React / Next.js" value="react">
+  <Tab label="React" value="react">
   
     #### Component `<MarkdownRenderer />`
 
@@ -479,6 +528,45 @@ Các tiện ích này **chỉ render các chuỗi Markdown thô** và độc l
     const jsx = renderMarkdown("# Tiêu đề của tôi", { forceBlock: true });
     ```
 
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+  
+    #### Component `<MarkdownRenderer />`
+
+    Render một chuỗi Markdown với các tùy chọn cụ thể.
+
+    ```tsx
+    import { MarkdownRenderer } from "next-intlayer/markdown";
+
+    <MarkdownRenderer forceBlock={true} tagfilter={true}>
+      {"# Tiêu đề của tôi"}
+    </MarkdownRenderer>
+    ```
+
+    #### Hook `useMarkdownRenderer()`
+
+    Nhận một hàm render đã được cấu hình trước.
+
+    ```tsx
+    import { useMarkdownRenderer } from "next-intlayer/markdown";
+
+    const renderMarkdown = useMarkdownRenderer({
+      forceBlock: true,
+      components: { h1: (props) => <h1 {...props} className="custom" /> }
+    });
+
+    return renderMarkdown("# Tiêu đề của tôi");
+    ```
+
+    #### Tiện ích `renderMarkdown()`
+    Tiện ích độc lập để render bên ngoài các component.
+
+    ```tsx
+    import { renderMarkdown } from "next-intlayer/markdown";
+
+    const jsx = renderMarkdown("# Tiêu đề của tôi", { forceBlock: true });
+    ```
+
   </Tab>
   <Tab label="Vue" value="vue">
 
@@ -608,14 +696,12 @@ Các tiện ích này **chỉ render các chuỗi Markdown thô** và độc l
   </Tab>
 </Tabs>
 
----
-
 ## Cấu hình Toàn cục với `MarkdownProvider`
 
 `MarkdownProvider` (hoặc tương đương trong framework) cấu hình pipeline render Markdown cho toàn bộ ứng dụng của bạn. Điều này áp dụng cho cả render `useIntlayer` tự động và các tiện ích hỗ trợ. Các tùy chọn được đặt ở đây là mặc định — `.use()` sẽ ghi đè chúng ở cấp độ node.
 
 <Tabs group="framework">
-  <Tab label="React / Next.js" value="react">
+  <Tab label="React" value="react">
 
     ```tsx fileName="AppProvider.tsx"
     import { MarkdownProvider } from "react-intlayer/markdown";
@@ -633,6 +719,7 @@ Các tiện ích này **chỉ render các chuỗi Markdown thô** và độc l
     );
     ```
 
+
     > Hỗ trợ MDX — bất kỳ tên component nào được sử dụng bên trong Markdown của bạn (ví dụ: `<MyCustomJSXComponent />`) đều được phân giải dựa trên bản đồ `components`.
 
     Bạn cũng có thể sử dụng trình render markdown của riêng mình:
@@ -643,6 +730,7 @@ Các tiện ích này **chỉ render các chuỗi Markdown thô** và độc l
     export const AppProvider = ({ children }) => (
       <MarkdownProvider
         renderMarkdown={async (md) => {
+          // Use dynamic import to reduce the bundle size of your application
           const { renderMarkdown } = await import('react-intlayer/markdown');
           return renderMarkdown(md);
         }}
@@ -654,6 +742,48 @@ Các tiện ích này **chỉ render các chuỗi Markdown thô** và độc l
 
     > Việc nhập trình render Markdown của bạn một cách động là một cách tuyệt vời để giảm dung lượng bundle của ứng dụng.
 
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+
+    ```tsx fileName="AppProvider.tsx"
+    import { MarkdownProvider } from "next-intlayer/markdown";
+
+    export const AppProvider = ({ children }) => (
+      <MarkdownProvider
+        components={{
+          h1: (props) => <h1 style={{color: 'green'}} {...props} />,
+          a: ({ href, ...props }) => <a style={{color: 'red'}} {...props} />,
+          MyCustomJSXComponent: (props) => <span style={{color: 'red'}} {...props} />,
+        }}
+      >
+        {children}
+      </MarkdownProvider>
+    );
+    ```
+
+
+    > Hỗ trợ MDX — bất kỳ tên component nào được sử dụng bên trong Markdown của bạn (ví dụ: `<MyCustomJSXComponent />`) đều được phân giải dựa trên bản đồ `components`.
+
+    Bạn cũng có thể sử dụng trình render markdown của riêng mình:
+
+    ```tsx fileName="AppProvider.tsx"
+    import { MarkdownProvider } from "next-intlayer/markdown";
+
+    export const AppProvider = ({ children }) => (
+      <MarkdownProvider
+        renderMarkdown={async (md) => {
+          // Use dynamic import to reduce the bundle size of your application
+          const { renderMarkdown } = await import('next-intlayer/markdown');
+          return renderMarkdown(md);
+        }}
+      >
+        {children}
+      </MarkdownProvider>
+    );
+    ```
+
+    > Việc nhập trình render Markdown của bạn một cách động là một cách tuyệt vời để giảm dung lượng bundle của ứng dụng.
+
   </Tab>
   <Tab label="Vue" value="vue">
 
@@ -679,6 +809,9 @@ Các tiện ích này **chỉ render các chuỗi Markdown thô** và độc l
     app.mount("#app");
     ```
 
+
+    > Hỗ trợ MDX — bất kỳ tên component nào được sử dụng bên trong Markdown của bạn (ví dụ: `<MyCustomJSXComponent />`) đều được phân giải dựa trên bản đồ `components`.
+
     Bạn cũng có thể sử dụng trình render markdown của riêng mình:
 
     ```typescript fileName="main.ts"
@@ -720,6 +853,9 @@ Các tiện ích này **chỉ render các chuỗi Markdown thô** và độc l
     </MarkdownProvider>
     ```
 
+
+    > Hỗ trợ MDX — bất kỳ tên component nào được sử dụng bên trong Markdown của bạn (ví dụ: `<MyCustomJSXComponent />`) đều được phân giải dựa trên bản đồ `components`.
+
     Bạn cũng có thể sử dụng trình render markdown của riêng mình:
 
     ```svelte fileName="App.svelte"
@@ -756,6 +892,9 @@ Các tiện ích này **chỉ render các chuỗi Markdown thô** và độc l
     );
     ```
 
+
+    > Hỗ trợ MDX — bất kỳ tên component nào được sử dụng bên trong Markdown của bạn (ví dụ: `<MyCustomJSXComponent />`) đều được phân giải dựa trên bản đồ `components`.
+
     Bạn cũng có thể sử dụng trình render markdown của riêng mình:
 
     ```tsx fileName="AppProvider.tsx"
@@ -792,6 +931,9 @@ Các tiện ích này **chỉ render các chuỗi Markdown thô** và độc l
     );
     ```
 
+
+    > Hỗ trợ MDX — bất kỳ tên component nào được sử dụng bên trong Markdown của bạn (ví dụ: `<MyCustomJSXComponent />`) đều được phân giải dựa trên bản đồ `components`.
+
     Bạn cũng có thể sử dụng trình render markdown của riêng mình:
 
     ```tsx fileName="AppProvider.tsx"
@@ -835,3 +977,191 @@ Các tiện ích này **chỉ render các chuỗi Markdown thô** và độc l
 
   </Tab>
 </Tabs>
+
+## Suspense
+
+Trình kết xuất Markdown của Intlayer được tải động. Mặc dù được tối ưu hóa, đoạn phân tích cú pháp cơ bản là khoảng 55kb. Tải điều này đồng bộ sẽ trì hoãn kết xuất trang ban đầu và làm suy giảm First Contentful Paint (FCP).
+
+Để ngăn chặn việc chặn giao diện người dùng, Intlayer tích hợp với Suspense API của React. Nó tìm nạp trình phân tích cú pháp trong nền và ném Promise trong khi tải xuống.
+
+Bọc bất kỳ thành phần nào kết xuất Intlayer Markdown trong ranh giới `<Suspense>`. Điều này hiển thị trạng thái dự phòng được bản địa hóa trong khi đoạn phim tải xuống, cho phép phần còn lại của DOM của bạn kết xuất ngay lập tức.
+
+Cảnh báo: Nếu bạn không cung cấp ranh giới `<Suspense>`, React sẽ đình chỉ ở cấp gốc hoặc chặn toàn bộ cây thành phần khỏi kết xuất cho đến khi đoạn 55kb được tải hoàn toàn.
+
+<Tabs>
+  <Tab label="Next.js" value="nextjs">
+
+Trong Next.js App Router, bạn có thể sử dụng React `Suspense` cho các thành phần máy khách hoặc tệp `loading.tsx` cho các thành phần máy chủ.
+
+**Thành phần máy khách:**
+
+```tsx fileName="components/MyComponent.tsx"
+"use client";
+import { useIntlayer } from "next-intlayer";
+import { Suspense } from "react";
+
+const MyComponent = () => {
+  const markdownContent = useIntlayer("my-markdown");
+
+  return (
+    <Suspense fallback={<div>Loading...</div>}>{markdownContent}</Suspense>
+  );
+};
+```
+
+**Thành phần máy chủ với `loading.tsx`:**
+
+```tsx fileName="app/loading.tsx"
+export default function Loading() {
+  return <div>Loading...</div>;
+}
+```
+
+```tsx fileName="app/page.tsx"
+import { useIntlayer } from "next-intlayer/server";
+
+const MyPage = () => {
+  const markdownContent = useIntlayer("my-markdown");
+  return <div>{markdownContent}</div>;
+};
+
+export default MyPage;
+```
+
+  </Tab>
+
+  <Tab label="React" value="react">
+
+```tsx
+import { useIntlayer } from "react-intlayer";
+import { Suspense } from "react";
+
+const MyComponent = () => {
+  const markdownContent = useIntlayer("my-markdown");
+
+  return (
+    <Suspense fallback={<div>Loading...</div>}>{markdownContent}</Suspense>
+  );
+};
+```
+
+  </Tab>
+ 
+  <Tab label="Vue" value="vue">
+
+Vue có một thành phần `<Suspense>` được tích hợp sẵn. Bọc thành phần kết xuất nội dung Markdown trong ranh giới `<Suspense>`.
+
+```vue fileName="MyComponent.vue"
+<script setup>
+import { useIntlayer } from "vue-intlayer";
+
+const { markdownContent } = useIntlayer("my-markdown");
+</script>
+
+<template>
+  <Suspense>
+    <component :is="markdownContent" />
+    <template #fallback>
+      <div>Loading...</div>
+    </template>
+  </Suspense>
+</template>
+```
+
+  </Tab>
+  <Tab label="Svelte" value="svelte">
+
+Svelte không có Suspense API tương đương. Sử dụng khối `{#await}` để xử lý kết xuất không đồng bộ của nội dung Markdown.
+
+```svelte fileName="MyComponent.svelte"
+<script lang="ts">
+import { useIntlayer } from "svelte-intlayer";
+
+const content = useIntlayer("my-markdown");
+</script>
+
+{#await $content.markdownContent}
+  <div>Loading...</div>
+{:then rendered}
+  {@html rendered}
+{/await}
+```
+
+  </Tab>
+  <Tab label="Preact" value="preact">
+
+Preact hỗ trợ Suspense API của React thông qua `preact/compat`.
+
+```tsx fileName="MyComponent.tsx"
+import { useIntlayer } from "preact-intlayer";
+import { Suspense } from "preact/compat";
+
+const MyComponent = () => {
+  const markdownContent = useIntlayer("my-markdown");
+
+  return (
+    <Suspense fallback={<div>Loading...</div>}>{markdownContent}</Suspense>
+  );
+};
+```
+
+  </Tab>
+  <Tab label="Solid" value="solid">
+
+Solid có thành phần `<Suspense>` riêng biệt từ `solid-js`.
+
+```tsx fileName="MyComponent.tsx"
+import { useIntlayer } from "solid-intlayer";
+import { Suspense } from "solid-js";
+
+const MyComponent = () => {
+  const { markdownContent } = useIntlayer("my-markdown");
+
+  return (
+    <Suspense fallback={<div>Loading...</div>}>{markdownContent}</Suspense>
+  );
+};
+```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+Angular không có Suspense API. Sử dụng chế độ xem có thể trì hoãn (`@defer`) của Angular để xử lý nội dung Markdown được tải chậm (yêu cầu Angular 17+).
+
+```typescript fileName="my.component.ts"
+import { Component } from "@angular/core";
+import { useIntlayer } from "angular-intlayer";
+
+@Component({
+  selector: "app-my",
+  template: `
+    @defer {
+      <div [innerHTML]="content().markdownContent"></div>
+    } @loading {
+      <div>Loading...</div>
+    }
+  `,
+})
+export class MyComponent {
+  content = useIntlayer("my-markdown");
+}
+```
+
+  </Tab>
+</Tabs>
+
+---
+
+## Tham chiếu tùy chọn
+
+Các tùy chọn này có thể được truyền đến `MarkdownProvider`, `MarkdownRenderer`, `useMarkdownRenderer` và `renderMarkdown`.
+
+| Option                | Type        | Default | Mô tả                                                                                 |
+| :-------------------- | :---------- | :------ | :------------------------------------------------------------------------------------ |
+| `forceBlock`          | `boolean`   | `false` | Bắt buộc đầu ra phải được bọc trong một phần tử cấp khối (ví dụ: `<div>`).            |
+| `forceInline`         | `boolean`   | `false` | Bắt buộc đầu ra phải được bọc trong một phần tử nội tuyến (ví dụ: `<span>`).          |
+| `tagfilter`           | `boolean`   | `true`  | Bật Bộ lọc thẻ GitHub để cải thiện bảo mật bằng cách loại bỏ các thẻ HTML nguy hiểm.  |
+| `preserveFrontmatter` | `boolean`   | `false` | Nếu `true`, frontmatter ở đầu chuỗi Markdown sẽ không bị tước đi.                     |
+| `components`          | `Overrides` | `{}`    | Bản đồ các thẻ HTML cho các thành phần tùy chỉnh (ví dụ: `{ h1: MyHeading }`).        |
+| `wrapper`             | `Component` | `null`  | Thành phần tùy chỉnh để bọc Markdown đã kết xuất.                                     |
+| `renderMarkdown`      | `Function`  | `null`  | Chức năng kết xuất tùy chỉnh để thay thế hoàn toàn trình biên dịch Markdown mặc định. |

package/docs/vi/interest_of_intlayer.md

@@ -224,7 +224,7 @@ Cách tiếp cận này cho phép bạn:
 
 Sao GitHub là một chỉ số mạnh mẽ về mức độ phổ biến của dự án, sự tin tưởng của cộng đồng và mức độ phù hợp lâu dài. Mặc dù không phải là thước đo trực tiếp về chất lượng kỹ thuật, chúng phản ánh số lượng nhà phát triển thấy dự án hữu ích, theo dõi tiến trình của nó và có khả năng áp dụng nó. Để ước tính giá trị của một dự án, các ngôi sao giúp so sánh sức hút giữa các lựa chọn thay thế và cung cấp thông tin chi tiết về sự phát triển của hệ sinh thái.
 
-[![Star History Chart](https://api.star-history.com/chart?repos=formatjs/formatjs%2Ci18next/react-i18next%2Ci18next/i18next%2Ci18next/next-i18next%2Clingui/js-lingui%2Camannn/next-intl%2Cintlify/vue-i18n%2Caymericzip/intlayer%2Copral/inlang&type=date&legend=top-left)](https://www.star-history.com/#formatjs/formatjs&i18next/react-i18next&i18next/i18next&i18next/next-i18next&lingui/js-lingui&amannn/next-intl&intlify/vue-i18n&opral/paraglide-js&aymericzip/intlayer)
+[![Star History Chart](https://api.star-history.com/chart?repos=aymericzip/intlayer%2Cformatjs/formatjs%2Ci18next/react-i18next%2Ci18next/i18next%2Ci18next/next-i18next%2Clingui/js-lingui%2Camannn/next-intl%2Cintlify/vue-i18n%2Ccodingcommons/typesafe-i18n%2Copral/paraglide-js&type=date&legend=top-left)](https://www.star-history.com/#aymericzip/intlayer&formatjs/formatjs&i18next/react-i18next&i18next/i18next&i18next/next-i18next&lingui/js-lingui&amannn/next-intl&intlify/vue-i18n&codingcommons/typesafe-i18n&opral/paraglide-js)
 
 ---