@intlayer/docs 8.10.0-canary.1 → 8.10.1

package/docs/zh/dictionary/markdown.md

@@ -95,34 +95,34 @@ Intlayer 支持使用 Markdown 语法定义的富文本内容。这使您可以
     ```
 
   </Tab>
-  <Tab label="自动检测" value="automatic-detection">
-    如果字符串包含常见的 Markdown 指示符（如标题、列表、链接等），Intlayer 会自动转换它。
+  <Tab label="外部文件" value="external-files">
+    使用 `file` 函数直接导入 `.md` 文件。
 
     ```typescript fileName="markdownDictionary.content.ts"
+    import { md, file, t } from "intlayer";
+
     export default {
       key: "app",
-      contentAutoTransformation: true, // 启用 Markdown 内容的自动检测 - 可以在 intlayer.config.ts 中全局设置
       content: {
-        myMarkdownContent: "## 我的标题 \n\nLorem Ipsum",
+        content: t({
+          en: md(file("./myMarkdown.en.md")),
+          zh: md(file("./myMarkdown.zh.md")),
+        }),
       },
     };
     ```
 
   </Tab>
 
-  <Tab label="外部文件" value="external-files">
-    使用 `file` 函数直接导入 `.md` 文件。
+  <Tab label="自动检测" value="automatic-detection">
+    如果字符串包含常见的 Markdown 指示符（如标题、列表、链接等），Intlayer 会自动转换它。
 
     ```typescript fileName="markdownDictionary.content.ts"
-    import { md, file, t } from "intlayer";
-
     export default {
       key: "app",
+      contentAutoTransformation: true, // 启用 Markdown 内容的自动检测 - 可以在 intlayer.config.ts 中全局设置
       content: {
-        content: t({
-          en: md(file("./myMarkdown.en.md")),
-          zh: md(file("./myMarkdown.zh.md")),
-        }),
+        myMarkdownContent: "## 我的标题 \n\nLorem Ipsum",
       },
     };
     ```
@@ -130,8 +130,6 @@ Intlayer 支持使用 Markdown 语法定义的富文本内容。这使您可以
   </Tab>
 </Tabs>
 
----
-
 ## 渲染 Markdown
 
 Intlayer 提供两种独立的方式来渲染 Markdown：
@@ -147,7 +145,7 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
 ### 1. 自动渲染（通过 `useIntlayer`）
 
 <Tabs group="framework">
-  <Tab label="React / Next.js" value="react">
+  <Tab label="React" value="react">
     Markdown 节点可以直接呈现为 JSX。
 
     ```tsx fileName="App.tsx"
@@ -197,6 +195,57 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
     {myMarkdownContent.metadata.title}
     ```
 
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    Markdown 节点可以直接呈现为 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} />, // MDX 组件
+        }}
+      >
+        <AppContent />
+      </MarkdownProvider>
+    );
+    ```
+
+    > 如果没有提供 `MarkdownProvider`，Intlayer 将使用默认的 Markdown 转 JSX 解析器渲染 markdown。
+
+    您还可以使用 `.use()` 方法提供特定节点的局部覆盖：
+
+    ```tsx
+    {myMarkdownContent.use({
+      h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,
+    })}
+    ```
+
+    您可以以字符串形式检索 Markdown：
+
+    ```tsx
+    {myMarkdownContent.value}
+    {String(myMarkdownContent)}
+    {myMarkdownContent.toString()}
+    ```
+
+    您可以像这样访问您的 markdown 元数据：
+
+    ```tsx
+    {myMarkdownContent.metadata}
+    {myMarkdownContent.metadata.title}
+    ```
+
   </Tab>
   <Tab label="Vue" value="vue">
     在 Vue 中，Markdown 内容可以使用内置的 `component` 或直接作为节点来呈现。
@@ -441,7 +490,7 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
 这些实用程序渲染 **仅限原始 Markdown 字符串** 且独立于 `useIntlayer`。当您需要从词典以外的来源渲染 Markdown 时使用它们。
 
 <Tabs group="framework">
-  <Tab label="React / Next.js" value="react">
+  <Tab label="React" value="react">
   
     #### `<MarkdownRenderer />` 组件
 
@@ -479,6 +528,45 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
     const jsx = renderMarkdown("# 我的标题", { forceBlock: true });
     ```
 
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+  
+    #### `<MarkdownRenderer />` 组件
+
+    使用特定选项渲染 Markdown 字符串。
+
+    ```tsx
+    import { MarkdownRenderer } from "next-intlayer/markdown";
+
+    <MarkdownRenderer forceBlock={true} tagfilter={true}>
+      {"# 我的标题"}
+    </MarkdownRenderer>
+    ```
+
+    #### `useMarkdownRenderer()` 钩子
+
+    获取预配置的渲染器函数。
+
+    ```tsx
+    import { useMarkdownRenderer } from "next-intlayer/markdown";
+
+    const renderMarkdown = useMarkdownRenderer({
+      forceBlock: true,
+      components: { h1: (props) => <h1 {...props} className="custom" /> }
+    });
+
+    return renderMarkdown("# 我的标题");
+    ```
+
+    #### `renderMarkdown()` 实用程序
+    组件外部渲染的独立实用程序。
+
+    ```tsx
+    import { renderMarkdown } from "next-intlayer/markdown";
+
+    const jsx = renderMarkdown("# 我的标题", { forceBlock: true });
+    ```
+
   </Tab>
   <Tab label="Vue" value="vue">
 
@@ -608,14 +696,12 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
   </Tab>
 </Tabs>
 
----
-
 ## 使用 `MarkdownProvider` 进行全局配置
 
 `MarkdownProvider`（或其框架对应的组件）为整个应用程序配置 Markdown 渲染管道。它适用于自动 `useIntlayer` 渲染和辅助实用程序。此处设置的选项为默认值 — `.use()` 在节点级别将其覆盖。
 
 <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 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
     );
     ```
 
+
     > 支持 MDX — Markdown 内部使用的任何组件名称（例如 `<MyCustomJSXComponent />`）都会根据 `components` 映射进行解析。
 
     您还可以使用自己的 markdown 渲染器：
@@ -643,6 +730,7 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
     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 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
 
     > 动态导入您的 Markdown 渲染器是减少应用程序包大小的好方法。
 
+  </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>
+    );
+    ```
+
+
+    > 支持 MDX — Markdown 内部使用的任何组件名称（例如 `<MyCustomJSXComponent />`）都会根据 `components` 映射进行解析。
+
+    您还可以使用自己的 markdown 渲染器：
+
+    ```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>
+    );
+    ```
+
+    > 动态导入您的 Markdown 渲染器是减少应用程序包大小的好方法。
+
   </Tab>
   <Tab label="Vue" value="vue">
 
@@ -679,6 +809,9 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
     app.mount("#app");
     ```
 
+
+    > 支持 MDX — Markdown 内部使用的任何组件名称（例如 `<MyCustomJSXComponent />`）都会根据 `components` 映射进行解析。
+
     您还可以使用自己的 markdown 渲染器：
 
     ```typescript fileName="main.ts"
@@ -720,6 +853,9 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
     </MarkdownProvider>
     ```
 
+
+    > 支持 MDX — Markdown 内部使用的任何组件名称（例如 `<MyCustomJSXComponent />`）都会根据 `components` 映射进行解析。
+
     您还可以使用自己的 markdown 渲染器：
 
     ```svelte fileName="App.svelte"
@@ -756,6 +892,9 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
     );
     ```
 
+
+    > 支持 MDX — Markdown 内部使用的任何组件名称（例如 `<MyCustomJSXComponent />`）都会根据 `components` 映射进行解析。
+
     您还可以使用自己的 markdown 渲染器：
 
     ```tsx fileName="AppProvider.tsx"
@@ -792,6 +931,9 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
     );
     ```
 
+
+    > 支持 MDX — Markdown 内部使用的任何组件名称（例如 `<MyCustomJSXComponent />`）都会根据 `components` 映射进行解析。
+
     您还可以使用自己的 markdown 渲染器：
 
     ```tsx fileName="AppProvider.tsx"
@@ -835,3 +977,191 @@ Markdown 渲染支持 **MDX** — 在您的 Markdown 中直接按名称使用任
 
   </Tab>
 </Tabs>
+
+## Suspense (悬念)
+
+Intlayer Markdown渲染器是动态加载的。虽然经过优化，但底层解析器块的大小约为55kb。同步加载会延迟初始页面渲染，并降低首次内容绘制（FCP）。
+
+为防止阻塞UI，Intlayer集成了React的Suspense API。它在后台获取解析器，并在下载期间抛出Promise。
+
+将渲染Intlayer Markdown的任何组件包装在`<Suspense>`边界中。这会在下载块时显示本地化的后备状态，从而允许立即渲染DOM的其余部分。
+
+警告：如果不提供`<Suspense>`边界，React将在根级别暂停或阻止整个组件树的渲染，直到55kb的块完全加载完毕。
+
+<Tabs>
+  <Tab label="Next.js" value="nextjs">
+
+在Next.js App Router中，您可以为客户端组件使用React `Suspense`，或为服务器组件使用`loading.tsx`文件。
+
+**客户端组件：**
+
+```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>
+  );
+};
+```
+
+**带有`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内置了`<Suspense>`组件。将渲染Markdown内容的组件包装在`<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没有Suspense API的等效项。使用`{#await}`块处理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通过`preact/compat`支持React的Suspense API。
+
+```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有自己的来自`solid-js`的`<Suspense>`组件。
+
+```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没有Suspense API。使用Angular的可延迟视图（`@defer`）来处理延迟加载的Markdown内容（需要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>
+
+---
+
+## 选项参考
+
+这些选项可传递给`MarkdownProvider`、`MarkdownRenderer`、`useMarkdownRenderer`和`renderMarkdown`。
+
+| Option                | Type        | Default | 描述                                                       |
+| :-------------------- | :---------- | :------ | :--------------------------------------------------------- |
+| `forceBlock`          | `boolean`   | `false` | 强制将输出包装在块级元素（例如`<div>`）中。                |
+| `forceInline`         | `boolean`   | `false` | 强制将输出包装在内联元素（例如`<span>`）中。               |
+| `tagfilter`           | `boolean`   | `true`  | 启用GitHub标签过滤器以通过剥离危险的HTML标签来提高安全性。 |
+| `preserveFrontmatter` | `boolean`   | `false` | 如果为`true`，则不会剥离Markdown字符串开头的frontmatter。  |
+| `components`          | `Overrides` | `{}`    | HTML标签到自定义组件的映射（例如`{ h1: MyHeading }`）。    |
+| `wrapper`             | `Component` | `null`  | 用于包装渲染Markdown的自定义组件。                         |
+| `renderMarkdown`      | `Function`  | `null`  | 自定义渲染函数，用于完全替换默认的Markdown编译器。         |

package/docs/zh/interest_of_intlayer.md

@@ -224,7 +224,7 @@ export const ComponentExample = () => {
 
 GitHub 星数是项目受欢迎程度、社区信任和长期相关性的有力指标。虽然星数不是技术质量的直接衡量标准，但它们反映了有多少开发人员发现该项目有用、关注其进展并可能采用它。在评估项目价值时，星数有助于比较不同方案的吸引力，并提供对生态系统增长的见解。
 
-[![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)
 
 ---
 

package/docs/zh-TW/interest_of_intlayer.md

@@ -224,7 +224,7 @@ export const ComponentExample = () => {
 
 GitHub 星數是專案受歡迎程度、社區信任和長期相關性的有力指標。雖然星數不是技術質量的直接衡量標準，但它們反映了有多少開發人員發現該專案有用、關注其進展並可能採用它。在評估專案價值時，星數有助於比較不同方案的吸引力，並提供對生態系統增長的見解。
 
-[![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)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intlayer/docs",
-  "version": "8.10.0-canary.1",
+  "version": "8.10.1",
   "private": false,
   "description": "Intlayer documentation",
   "keywords": [
@@ -72,13 +72,13 @@
     "watch": "webpack --config ./webpack.config.ts --watch"
   },
   "dependencies": {
-    "@intlayer/config": "8.10.0-canary.1",
-    "@intlayer/core": "8.10.0-canary.1",
-    "@intlayer/types": "8.10.0-canary.1"
+    "@intlayer/config": "8.10.1",
+    "@intlayer/core": "8.10.1",
+    "@intlayer/types": "8.10.1"
   },
   "devDependencies": {
-    "@intlayer/api": "8.10.0-canary.1",
-    "@intlayer/cli": "8.10.0-canary.1",
+    "@intlayer/api": "8.10.1",
+    "@intlayer/cli": "8.10.1",
     "@types/node": "25.9.1",
     "@utils/ts-config": "1.0.4",
     "@utils/ts-config-types": "1.0.4",
@@ -87,7 +87,7 @@
     "rimraf": "6.1.3",
     "tsdown": "0.22.00",
     "typescript": "6.0.3",
-    "vitest": "4.1.6"
+    "vitest": "4.1.7"
   },
   "engines": {
     "node": ">=14.18"