@intlayer/docs 8.10.0-canary.1 → 8.10.1

package/docs/pt/dictionary/markdown.md

@@ -95,34 +95,34 @@ Você pode declarar conteúdo Markdown usando a função `md` ou simplesmente co
     ```
 
   </Tab>
-  <Tab label="Detecção Automática" value="automatic-detection">
-    Se a string contiver indicadores Markdown comuns (como cabeçalhos, listas, links, etc.), o Intlayer a transformará automaticamente.
+  <Tab label="Arquivos Externos" value="external-files">
+    Importe arquivos `.md` diretamente usando a função `file`.
 
     ```typescript fileName="markdownDictionary.content.ts"
+    import { md, file, t } from "intlayer";
+
     export default {
       key: "app",
-      contentAutoTransformation: true, // Ativar detecção automática de conteúdo Markdown - Pode ser definido globalmente em intlayer.config.ts
       content: {
-        myMarkdownContent: "## Meu título \n\nLorem Ipsum",
+        content: t({
+          en: md(file("./myMarkdown.en.md")),
+          pt: md(file("./myMarkdown.pt.md")),
+        }),
       },
     };
     ```
 
   </Tab>
 
-  <Tab label="Arquivos Externos" value="external-files">
-    Importe arquivos `.md` diretamente usando a função `file`.
+  <Tab label="Detecção Automática" value="automatic-detection">
+    Se a string contiver indicadores Markdown comuns (como cabeçalhos, listas, links, etc.), o Intlayer a transformará automaticamente.
 
     ```typescript fileName="markdownDictionary.content.ts"
-    import { md, file, t } from "intlayer";
-
     export default {
       key: "app",
+      contentAutoTransformation: true, // Ativar detecção automática de conteúdo Markdown - Pode ser definido globalmente em intlayer.config.ts
       content: {
-        content: t({
-          en: md(file("./myMarkdown.en.md")),
-          pt: md(file("./myMarkdown.pt.md")),
-        }),
+        myMarkdownContent: "## Meu título \n\nLorem Ipsum",
       },
     };
     ```
@@ -130,8 +130,6 @@ Você pode declarar conteúdo Markdown usando a função `md` ou simplesmente co
   </Tab>
 </Tabs>
 
----
-
 ## Renderizando Markdown
 
 O Intlayer fornece duas maneiras independentes de renderizar Markdown:
@@ -147,7 +145,7 @@ A renderização do Markdown suporta **MDX** — use qualquer componente JSX/fra
 ### 1. Renderização Automática (através de `useIntlayer`)
 
 <Tabs group="framework">
-  <Tab label="React / Next.js" value="react">
+  <Tab label="React" value="react">
     Nós Markdown podem ser renderizados diretamente como JSX.
 
     ```tsx fileName="App.tsx"
@@ -197,6 +195,57 @@ A renderização do Markdown suporta **MDX** — use qualquer componente JSX/fra
     {myMarkdownContent.metadata.title}
     ```
 
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+    Nós Markdown podem ser renderizados diretamente como 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} />, // Componente MDX
+        }}
+      >
+        <AppContent />
+      </MarkdownProvider>
+    );
+    ```
+
+    > Se o `MarkdownProvider` não estiver presente, o Intlayer renderizará o markdown usando o parser padrão Markdown-para-JSX.
+
+    Você também pode fornecer substituições locais para nós específicos usando o método `.use()`:
+
+    ```tsx
+    {myMarkdownContent.use({
+      h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,
+    })}
+    ```
+
+    Você pode recuperar o Markdown como string:
+
+    ```tsx
+    {myMarkdownContent.value}
+    {String(myMarkdownContent)}
+    {myMarkdownContent.toString()}
+    ```
+
+    E você pode acessar os metadados do markdown assim:
+
+    ```tsx
+    {myMarkdownContent.metadata}
+    {myMarkdownContent.metadata.title}
+    ```
+
   </Tab>
   <Tab label="Vue" value="vue">
     No Vue, o conteúdo Markdown pode ser renderizado usando a tag nativa `component` ou diretamente como um nó.
@@ -441,7 +490,7 @@ A renderização do Markdown suporta **MDX** — use qualquer componente JSX/fra
 Estes utilitários renderizam **apenas strings Markdown brutas** e são independentes do `useIntlayer`. Use-os quando precisar renderizar Markdown de fontes além de seus dicionários.
 
 <Tabs group="framework">
-  <Tab label="React / Next.js" value="react">
+  <Tab label="React" value="react">
   
     #### Componente `<MarkdownRenderer />`
 
@@ -479,6 +528,45 @@ Estes utilitários renderizam **apenas strings Markdown brutas** e são independ
     const jsx = renderMarkdown("# Meu Título", { forceBlock: true });
     ```
 
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+  
+    #### Componente `<MarkdownRenderer />`
+
+    Renderiza uma string Markdown com opções específicas.
+
+    ```tsx
+    import { MarkdownRenderer } from "next-intlayer/markdown";
+
+    <MarkdownRenderer forceBlock={true} tagfilter={true}>
+      {"# Meu Título"}
+    </MarkdownRenderer>
+    ```
+
+    #### Hook `useMarkdownRenderer()`
+
+    Obtém uma função de renderização pré-configurada.
+
+    ```tsx
+    import { useMarkdownRenderer } from "next-intlayer/markdown";
+
+    const renderMarkdown = useMarkdownRenderer({
+      forceBlock: true,
+      components: { h1: (props) => <h1 {...props} className="custom" /> }
+    });
+
+    return renderMarkdown("# Meu Título");
+    ```
+
+    #### Utilitário `renderMarkdown()`
+    Utilitário autônomo para renderização fora dos componentes.
+
+    ```tsx
+    import { renderMarkdown } from "next-intlayer/markdown";
+
+    const jsx = renderMarkdown("# Meu Título", { forceBlock: true });
+    ```
+
   </Tab>
   <Tab label="Vue" value="vue">
 
@@ -608,14 +696,12 @@ Estes utilitários renderizam **apenas strings Markdown brutas** e são independ
   </Tab>
 </Tabs>
 
----
-
 ## Configuração Global com `MarkdownProvider`
 
 O `MarkdownProvider` (ou o seu equivalente do framework) configura o pipeline de renderização Markdown para toda a sua aplicação. Aplica-se tanto para a renderização automática do `useIntlayer` quanto para os utilitários auxiliares. Opções definidas aqui são os padrões — o `.use()` substitui-os em nível de nó.
 
 <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 @@ O `MarkdownProvider` (ou o seu equivalente do framework) configura o pipeline de
     );
     ```
 
+
     > O MDX é suportado — qualquer nome de componente usado dentro do seu Markdown (ex: `<MyCustomJSXComponent />`) é resolvido com base no mapa de `components`.
 
     Você também pode usar seu próprio renderizador de markdown:
@@ -643,6 +730,7 @@ O `MarkdownProvider` (ou o seu equivalente do framework) configura o pipeline de
     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 @@ O `MarkdownProvider` (ou o seu equivalente do framework) configura o pipeline de
 
     > Importar dinamicamente o seu renderizador de Markdown é uma ótima maneira de reduzir o tamanho do pacote da sua aplicação.
 
+  </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>
+    );
+    ```
+
+
+    > O MDX é suportado — qualquer nome de componente usado dentro do seu Markdown (ex: `<MyCustomJSXComponent />`) é resolvido com base no mapa de `components`.
+
+    Você também pode usar seu próprio renderizador de 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>
+    );
+    ```
+
+    > Importar dinamicamente o seu renderizador de Markdown é uma ótima maneira de reduzir o tamanho do pacote da sua aplicação.
+
   </Tab>
   <Tab label="Vue" value="vue">
 
@@ -679,6 +809,9 @@ O `MarkdownProvider` (ou o seu equivalente do framework) configura o pipeline de
     app.mount("#app");
     ```
 
+
+    > O MDX é suportado — qualquer nome de componente usado dentro do seu Markdown (ex: `<MyCustomJSXComponent />`) é resolvido com base no mapa de `components`.
+
     Você também pode usar seu próprio renderizador de markdown:
 
     ```typescript fileName="main.ts"
@@ -720,6 +853,9 @@ O `MarkdownProvider` (ou o seu equivalente do framework) configura o pipeline de
     </MarkdownProvider>
     ```
 
+
+    > O MDX é suportado — qualquer nome de componente usado dentro do seu Markdown (ex: `<MyCustomJSXComponent />`) é resolvido com base no mapa de `components`.
+
     Você também pode usar seu próprio renderizador de markdown:
 
     ```svelte fileName="App.svelte"
@@ -756,6 +892,9 @@ O `MarkdownProvider` (ou o seu equivalente do framework) configura o pipeline de
     );
     ```
 
+
+    > O MDX é suportado — qualquer nome de componente usado dentro do seu Markdown (ex: `<MyCustomJSXComponent />`) é resolvido com base no mapa de `components`.
+
     Você também pode usar seu próprio renderizador de markdown:
 
     ```tsx fileName="AppProvider.tsx"
@@ -792,6 +931,9 @@ O `MarkdownProvider` (ou o seu equivalente do framework) configura o pipeline de
     );
     ```
 
+
+    > O MDX é suportado — qualquer nome de componente usado dentro do seu Markdown (ex: `<MyCustomJSXComponent />`) é resolvido com base no mapa de `components`.
+
     Você também pode usar seu próprio renderizador de markdown:
 
     ```tsx fileName="AppProvider.tsx"
@@ -835,3 +977,191 @@ O `MarkdownProvider` (ou o seu equivalente do framework) configura o pipeline de
 
   </Tab>
 </Tabs>
+
+## Suspense
+
+O renderizador Markdown do Intlayer é carregado dinamicamente. Embora otimizado, o chunk do analisador subjacente tem aproximadamente 55 kb. Carregar isso de forma síncrona atrasa a renderização inicial da página e degrada o First Contentful Paint (FCP).
+
+Para evitar o bloqueio da interface do usuário, o Intlayer se integra com a API Suspense do React. Ele busca o analisador em segundo plano e lança uma Promise durante o download.
+
+Envolva qualquer componente que renderize o Intlayer Markdown em um limite `<Suspense>`. Isso exibe um estado de fallback localizado enquanto o chunk é baixado, permitindo que o restante de seu DOM seja renderizado imediatamente.
+
+Aviso: Se você não fornecer um limite `<Suspense>`, o React irá suspender no nível raiz ou bloquear a renderização de toda a árvore de componentes até que o chunk de 55 kb seja totalmente carregado.
+
+<Tabs>
+  <Tab label="Next.js" value="nextjs">
+
+No Next.js App Router, você pode usar o React `Suspense` para componentes do cliente ou um arquivo `loading.tsx` para componentes do servidor.
+
+**Componente do Cliente:**
+
+```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>
+  );
+};
+```
+
+**Componente do Servidor com `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 tem um componente `<Suspense>` integrado. Envolva o componente que renderiza o conteúdo Markdown em um limite `<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">
+
+O Svelte não tem um equivalente à API Suspense. Use um bloco `{#await}` para lidar com a renderização assíncrona do conteúdo 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">
+
+O Preact suporta a API Suspense do React via `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 tem seu próprio componente `<Suspense>` do `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 não tem uma API Suspense. Use as exibições adiáveis (`@defer`) para lidar com o conteúdo Markdown carregado lentamente (requer 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>
+
+---
+
+## Referência de opções
+
+Essas opções podem ser passadas para `MarkdownProvider`, `MarkdownRenderer`, `useMarkdownRenderer` e `renderMarkdown`.
+
+| Option                | Type        | Default | Descrição                                                                                            |
+| :-------------------- | :---------- | :------ | :--------------------------------------------------------------------------------------------------- |
+| `forceBlock`          | `boolean`   | `false` | Força a saída a ser envolvida em um elemento de nível de bloco (ex: `<div>`).                        |
+| `forceInline`         | `boolean`   | `false` | Força a saída a ser envolvida em um elemento em linha (ex: `<span>`).                                |
+| `tagfilter`           | `boolean`   | `true`  | Habilita o GitHub Tag Filter para melhor segurança removendo tags HTML perigosas.                    |
+| `preserveFrontmatter` | `boolean`   | `false` | Se `true`, o frontmatter no início da string Markdown não será removido.                             |
+| `components`          | `Overrides` | `{}`    | Um mapa de tags HTML para componentes personalizados (ex: `{ h1: MyHeading }`).                      |
+| `wrapper`             | `Component` | `null`  | Um componente personalizado para envolver o Markdown renderizado.                                    |
+| `renderMarkdown`      | `Function`  | `null`  | Uma função de renderização personalizada para substituir completamente o compilador Markdown padrão. |

package/docs/pt/interest_of_intlayer.md

@@ -224,7 +224,7 @@ Esta abordagem permite que você:
 
 As estrelas do GitHub são um forte indicador da popularidade de um projeto, da confiança da comunidade e da relevância a longo prazo. Embora não sejam uma medida direta da qualidade técnica, elas refletem quantos desenvolvedores consideram o projeto útil, acompanham seu progresso e têm probabilidade de adotá-lo. Para estimar o valor de um projeto, as estrelas ajudam a comparar a tração entre as alternativas e fornecem insights sobre o crescimento do ecossistema.
 
-[![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)
 
 ---