@intlayer/docs 8.10.0-canary.1 → 8.10.1

package/docs/ko/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")),
+          ko: md(file("./myMarkdown.ko.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")),
-          ko: md(file("./myMarkdown.ko.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 to JSX 파서를 사용하여 마크다운을 렌더링합니다.
+
+    `.use()` 메서드를 사용하여 특정 노드에 대한 로컬 재정의를 제공할 수도 있습니다:
+
+    ```tsx
+    {myMarkdownContent.use({
+      h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,
+    })}
+    ```
+
+    문자열로 Markdown을 가져올 수 있습니다:
+
+    ```tsx
+    {myMarkdownContent.value}
+    {String(myMarkdownContent)}
+    {myMarkdownContent.toString()}
+    ```
+
+    그리고 다음과 같이 마크다운 메타데이터에 접근할 수 있습니다:
+
+    ```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` 맵에서 확인됩니다.
 
     자체 마크다운 렌더러를 사용할 수도 있습니다:
@@ -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` 맵에서 확인됩니다.
+
+    자체 마크다운 렌더러를 사용할 수도 있습니다:
+
+    ```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` 맵에서 확인됩니다.
+
     자체 마크다운 렌더러를 사용할 수도 있습니다:
 
     ```typescript fileName="main.ts"
@@ -720,6 +853,9 @@ Markdown 렌더링은 **MDX**를 지원합니다 — Markdown 내에서 이름
     </MarkdownProvider>
     ```
 
+
+    > MDX 지원 — Markdown 내부에서 사용된 모든 컴포넌트 이름(예: `<MyCustomJSXComponent />`)은 `components` 맵에서 확인됩니다.
+
     자체 마크다운 렌더러를 사용할 수도 있습니다:
 
     ```svelte fileName="App.svelte"
@@ -756,6 +892,9 @@ Markdown 렌더링은 **MDX**를 지원합니다 — Markdown 내에서 이름
     );
     ```
 
+
+    > MDX 지원 — Markdown 내부에서 사용된 모든 컴포넌트 이름(예: `<MyCustomJSXComponent />`)은 `components` 맵에서 확인됩니다.
+
     자체 마크다운 렌더러를 사용할 수도 있습니다:
 
     ```tsx fileName="AppProvider.tsx"
@@ -792,6 +931,9 @@ Markdown 렌더링은 **MDX**를 지원합니다 — Markdown 내에서 이름
     );
     ```
 
+
+    > MDX 지원 — Markdown 내부에서 사용된 모든 컴포넌트 이름(예: `<MyCustomJSXComponent />`)은 `components` 맵에서 확인됩니다.
+
     자체 마크다운 렌더러를 사용할 수도 있습니다:
 
     ```tsx fileName="AppProvider.tsx"
@@ -835,3 +977,191 @@ Markdown 렌더링은 **MDX**를 지원합니다 — Markdown 내에서 이름
 
   </Tab>
 </Tabs>
+
+## 서스펜스 (Suspense)
+
+Intlayer Markdown 렌더러는 동적으로 로드됩니다. 최적화되어 있지만 기본 구문 분석기 청크는 약 55kb입니다. 이를 동기적으로 로드하면 초기 페이지 렌더링이 지연되고 FCP(First Contentful Paint)가 저하됩니다.
+
+UI 차단을 방지하기 위해 Intlayer는 React의 Suspense API와 통합됩니다. 백그라운드에서 구문 분석기를 가져오고 다운로드하는 동안 Promise를 던집니다.
+
+Intlayer Markdown을 렌더링하는 구성 요소를 `<Suspense>` 경계로 래핑하십시오. 이렇게 하면 청크가 다운로드되는 동안 현지화된 대체 상태가 표시되어 나머지 DOM이 즉시 렌더링될 수 있습니다.
+
+경고: `<Suspense>` 경계를 제공하지 않으면 React는 55kb 청크가 완전히 로드될 때까지 루트 수준에서 일시 중지하거나 전체 구성 요소 트리의 렌더링을 차단합니다.
+
+<Tabs>
+  <Tab label="Next.js" value="nextjs">
+
+Next.js 앱 라우터에서는 클라이언트 구성 요소에 대해 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에 해당하는 기능이 없습니다. Markdown 콘텐츠의 비동기 렌더링을 처리하려면 `{#await}` 블록을 사용하십시오.
+
+```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가 없습니다. 지연 로드된 Markdown 콘텐츠를 처리하려면 Angular의 지연된 보기(`@defer`)를 사용하십시오(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`  | 위험한 HTML 태그를 제거하여 보안을 강화하기 위해 GitHub 태그 필터를 활성화합니다. |
+| `preserveFrontmatter` | `boolean`   | `false` | `true`인 경우 Markdown 문자열의 시작 부분에 있는 프런트매터가 제거되지 않습니다.  |
+| `components`          | `Overrides` | `{}`    | HTML 태그를 사용자 정의 구성 요소에 매핑(예: `{ h1: MyHeading }`).                |
+| `wrapper`             | `Component` | `null`  | 렌더링된 Markdown을 래핑하는 사용자 정의 구성 요소입니다.                         |
+| `renderMarkdown`      | `Function`  | `null`  | 기본 Markdown 컴파일러를 완전히 교체하는 사용자 정의 렌더링 기능입니다.           |

package/docs/ko/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/nl/interest_of_intlayer.md

@@ -224,7 +224,7 @@ Deze aanpak stelt u in staat om:
 
 GitHub-sterren zijn een sterke indicator voor de populariteit van een project, het vertrouwen van de gemeenschap en de relevantie op de lange termijn. Hoewel ze geen directe maatstaf zijn voor technische kwaliteit, weerspiegelen ze hoeveel ontwikkelaars het project nuttig vinden, de voortgang ervan volgen en het waarschijnlijk zullen adopteren. Voor het schatten van de waarde van een project helpen sterren om de tractie tussen alternatieven te vergelijken en bieden ze inzichten in de groei van het ecosysteem.
 
-[![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)
 
 ---