@intlayer/docs 8.11.1 → 8.11.3

package/docs/pl/lsp.md

@@ -0,0 +1,351 @@
+---
+createdAt: 2025-06-07
+updatedAt: 2026-05-31
+title: Serwer Intlayer LSP
+description: Dowiedz się, jak serwer językowy Intlayer zapewnia funkcję "Przejdź do definicji" i inne funkcje IDE dla useIntlayer, getIntlayer oraz powiązanych wywołań we wszystkich obsługiwanych edytorach.
+keywords:
+  - LSP
+  - Serwer Językowy
+  - Przejdź do definicji
+  - IDE
+  - Intlayer
+  - VS Code
+  - Neovim
+  - TypeScript
+slugs:
+  - doc
+  - lsp
+history:
+  - version: 8.12.0
+    date: 2026-06-01
+    changes: "Release LSP"
+---
+
+# Serwer Intlayer LSP
+
+**Serwer Językowy Intlayer (LSP)** to implementacja protokołu [Language Server Protocol (LSP)](https://microsoft.github.io/language-server-protocol/), która wzbogaca Twoje IDE o inteligencję rozumiejącą strukturę Intlayer. Obecnie zapewnia funkcję **Przejdź do definicji (Go to Definition)** dla wywołań kluczy słownika, umożliwiając bezpośrednie przejście od `useIntlayer("my-key")` w komponencie do pliku `.content.ts`, który go deklaruje.
+
+---
+
+## Dlaczego warto używać LSP?
+
+Gdy używasz Intlayer, połączenie między wywołaniem takim jak `useIntlayer("homepage")` a jego deklaracją w `src/homepage.content.ts` jest niejawne. Bez odpowiednich narzędzi musisz szukać tego pliku ręcznie. LSP sprawia, że to powiązanie staje się jawne:
+
+**Świadomość agentów AI**
+
+Agenci kodujący AI (Cursor, Windsurf, GitHub Copilot, Claude Code, Codex) polegają na serwerze językowym w celu rozpoznawania symboli i rozumienia relacji między plikami. Dzięki uruchomionemu Intlayer LSP agenci mogą śledzić wywołanie `useIntlayer("key")` z powrotem do jego deklaracji, co daje im dokładny kontekst dotyczący dostępnych kluczy treści, struktury każdego słownika oraz plików do odczytu lub edycji.
+
+**Przejdź do definicji**
+
+Umieść kursor na dowolnym ciągu klucza słownika wewnątrz obsługiwanego wywołania pobierającego i naciśnij `F12` (lub `Cmd/Ctrl+Kliknięcie`). Edytor otworzy plik deklaracji treści i ustawi kursor w linii `key:`.
+
+**Obsługa scalonych słowników**
+
+Klucz może być podzielony na wiele plików treści (Intlayer scala je). Serwer zwraca jedną lokalizację (`Location`) na plik źródłowy, dzięki czemu możesz przejść do każdej deklaracji.
+
+**Działa wszędzie**
+
+Obsługuje wszystkie pakiety `*-intlayer` (`next-intlayer`, `react-intlayer`, `vue-intlayer`, `svelte-intlayer`, `solid-intlayer`, `preact-intlayer`, `angular-intlayer`, `lit-intlayer`, `express-intlayer`, `hono-intlayer`, `fastify-intlayer`, `adonis-intlayer`, `intlayer`).
+
+### Obsługiwane wywołania pobierające
+
+Serwer wykrywa następujące wywołania funkcji i wyodrębnia pierwszy argument jako klucz słownika:
+
+| Funkcja       | Przykład                      |
+| ------------- | ----------------------------- |
+| `useIntlayer` | `useIntlayer("hero")`         |
+| `getIntlayer` | `getIntlayer("hero", locale)` |
+
+Typy generyczne TypeScript oraz dodatkowe argumenty są ignorowane — liczy się tylko klucz słownika.
+
+> Funkcje `useDictionary` i `getDictionary` przyjmują jako pierwszy argument już zaimportowany obiekt `Dictionary`, a nie klucz tekstowy, dlatego nie korzystają z funkcji Przejdź do definicji i nie są śledzone przez serwer.
+
+---
+
+## Instalacja
+
+Serwer LSP jest dystrybuowany jako część pakietu `@intlayer/lsp`:
+
+```bash packageManager="npm"
+npm install --save-dev @intlayer/lsp
+```
+
+```bash packageManager="yarn"
+yarn add --dev @intlayer/lsp
+```
+
+```bash packageManager="pnpm"
+pnpm add --save-dev @intlayer/lsp
+```
+
+```bash packageManager="bun"
+bun add --dev @intlayer/lsp
+```
+
+Pakiet udostępnia plik wykonywalny `intlayer-lsp`, którego edytory używają jako serwera.
+
+---
+
+## Konfiguracja jako plugin Claude Code
+
+Serwer Intlayer LSP jest dostępny jako **plugin Claude Code** hostowany bezpośrednio w repozytorium GitHub Intlayer. Jego instalacja daje Claude Code natywną świadomość funkcji Przejdź do definicji dla wszystkich wywołań `useIntlayer` / `getIntlayer`.
+
+### 1. Zainstaluj plik wykonywalny serwera językowego
+
+```bash packageManager="npm"
+npm install -g @intlayer/lsp
+```
+
+```bash packageManager="yarn"
+yarn global add @intlayer/lsp
+```
+
+```bash packageManager="pnpm"
+pnpm add -g @intlayer/lsp
+```
+
+To polecenie umieści plik binarny `intlayer-lsp` w Twojej ścieżce PATH, co jest wywoływane przez wpis `lspServers` w pluginie.
+
+### 2. Zarejestruj rynek Intlayer i zainstaluj plugin
+
+```bash
+claude plugin marketplace add intlayer@github:aymericzip/intlayer
+claude plugin install intlayer-lsp@intlayer
+claude plugin enable intlayer-lsp@intlayer
+```
+
+Claude Code doda `"intlayer-lsp@intlayer": true` do Twoich `enabledPlugins` i automatycznie uruchomi serwer językowy dla obsługiwanych typów plików (`.ts`, `.tsx`, `.js`, `.jsx`, `.vue`, `.svelte`).
+
+### 3. Włącz narzędzie LSP (jeśli nie jest jeszcze aktywne)
+
+Niektóre wersje Claude Code wymagają ustawienia flagi funkcji LSP. Dodaj poniższy wpis do pliku `~/.claude/settings.json`, jeśli funkcja Przejdź do definicji nie działa po instalacji:
+
+```json fileName="~/.claude/settings.json"
+{
+  "env": {
+    "ENABLE_LSP_TOOL": "1"
+  }
+}
+```
+
+Uruchom ponownie Claude Code — od teraz będzie on używał `goToDefinition`, `findReferences` oraz innych operacji LSP podczas nawigacji po kodzie Intlayer zamiast powracać do `grep`.
+
+---
+
+## Konfiguracja w VS Code (przez rozszerzenie — zalecane)
+
+Jeśli masz zainstalowane [rozszerzenie Intlayer dla VS Code](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension), serwer językowy uruchomi się automatycznie. Nie jest wymagana żadna dodatkowa konfiguracja.
+
+> Zobacz [dokumentację rozszerzenia VS Code](https://intlayer.org/doc/vs-code-extension) w celu uzyskania szczegółów instalacji i innych funkcji.
+
+---
+
+## Ręczna konfiguracja w VS Code
+
+Jeśli nie używasz rozszerzenia Intlayer, możesz połączyć serwer językowy ręcznie, korzystając z ogólnego rozszerzenia klienta LSP, takiego jak [**vscode-glspc**](https://marketplace.visualstudio.com/items?itemName=sibiraj-s.vscode-scss-formatter) lub pisząc własne małe rozszerzenie. Zalecanym podejściem jest użycie oficjalnego rozszerzenia Intlayer.
+
+Dla odniesienia, serwer uruchamia się za pomocą pliku binarnego `intlayer-lsp` przez stdio:
+
+```json fileName=".vscode/settings.json"
+{
+  "intlayer.languageServer.command": "npx",
+  "intlayer.languageServer.args": ["@intlayer/lsp"]
+}
+```
+
+Rozszerzenie Intlayer odczytuje te ustawienia, aby uruchomić serwer. Jeśli polegasz wyłącznie na rozszerzeniu, konfiguracja ręczna nie jest potrzebna.
+
+---
+
+## Konfiguracja w Cursor
+
+[Cursor](https://www.cursor.com/) to fork VS Code z wbudowanymi funkcjami AI. Korzysta z tego samego ekosystemu rozszerzeń, więc **rozszerzenie Intlayer dla VS Code** działa bez żadnej dodatkowej konfiguracji — zainstaluj je raz, a Cursor wykryje je automatycznie.
+
+Jeśli wolisz ręczną konfigurację, Cursor odczytuje również plik `.vscode/settings.json` z katalogu głównego obszaru roboczego, więc powyższy fragment kodu dla VS Code ma zastosowanie bezpośrednio.
+
+---
+
+## Konfiguracja w Windsurf
+
+[Windsurf](https://windsurf.com/) (stworzony przez Codeium) to kolejny edytor oparty na VS Code. Zainstaluj rozszerzenie Intlayer z VS Code Marketplace, a serwer językowy aktywuje się automatycznie, dokładnie tak samo jak w VS Code i Cursor.
+
+W przypadku ręcznej konfiguracji utwórz plik `.vscode/settings.json` w katalogu głównym projektu:
+
+```json fileName=".vscode/settings.json"
+{
+  "intlayer.languageServer.command": "npx",
+  "intlayer.languageServer.args": ["@intlayer/lsp"]
+}
+```
+
+---
+
+## Konfiguracja w Zed
+
+[Zed](https://zed.dev/) posiada natywną obsługę LSP poprzez swoje ustawienia językowe. Dodaj wpis do ustawień użytkownika Zed (`~/.config/zed/settings.json`):
+
+```json fileName="~/.config/zed/settings.json"
+{
+  "lsp": {
+    "intlayer-lsp": {
+      "binary": {
+        "path": "npx",
+        "arguments": ["--yes", "@intlayer/lsp"]
+      }
+    }
+  },
+  "languages": {
+    "TypeScript": {
+      "language_servers": ["intlayer-lsp", "..."]
+    },
+    "TSX": {
+      "language_servers": ["intlayer-lsp", "..."]
+    },
+    "JavaScript": {
+      "language_servers": ["intlayer-lsp", "..."]
+    },
+    "Vue.js": {
+      "language_servers": ["intlayer-lsp", "..."]
+    },
+    "Svelte": {
+      "language_servers": ["intlayer-lsp", "..."]
+    }
+  }
+}
+```
+
+Znak zastępczy `"..."` informuje edytor Zed, aby zachował domyślne serwery językowe obok serwera Intlayer.
+
+---
+
+## Konfiguracja dla AI Agent CLI (Claude Code, Codex itp.)
+
+**Claude Code** posiada pierwszorzędną obsługę pluginów LSP — postępuj zgodnie z instrukcjami w sekcji [Konfiguracja jako plugin Claude Code](#konfiguracja-jako-plugin-claude-code) powyżej, aby uzyskać pełną funkcjonalność Przejdź do definicji bezpośrednio w sesjach terminala.
+
+**OpenAI Codex** oraz inne narzędzia konsolowe nie działają jeszcze jako klienci LSP — odczytują i zapisują pliki bezpośrednio, zamiast utrzymywać trwałą sesję serwera językowego. Dla tych narzędzi wartość uruchomionego LSP pojawia się pośrednio: gdy serwer jest aktywny w towarzyszącym edytorze (VS Code, Cursor, Windsurf, ...), bieżący indeks edytora jest dostępny dla każdego agenta AI, który może odpytać go za pomocą dostarczonego przez edytor kontekstu (np. Cursor Composer, Windsurf Cascade, GitHub Copilot Chat).
+
+Jeśli pracujesz wyłącznie w terminalu bez otwartego edytora, możesz uruchomić serwer językowy w tle, aby był gotowy na podłączenie dowolnego edytora do tego samego obszaru roboczego w przyszłości:
+
+```bash
+# Utrzymuj serwer aktywny w tle
+npx @intlayer/lsp &
+```
+
+---
+
+## Ręczna konfiguracja w Neovim
+
+Używając [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig), zarejestruj niestandardową konfigurację serwera:
+
+```lua fileName="~/.config/nvim/init.lua"
+local lspconfig = require('lspconfig')
+local configs = require('lspconfig.configs')
+
+if not configs.intlayer_lsp then
+  configs.intlayer_lsp = {
+    default_config = {
+      -- Uruchom serwer za pomocą npx, aby uniknąć instalacji globalnej
+      cmd = { 'npx', '--yes', '@intlayer/lsp' },
+      filetypes = {
+        'typescript',
+        'typescriptreact',
+        'javascript',
+        'javascriptreact',
+        'vue',
+        'svelte',
+      },
+      root_dir = lspconfig.util.root_pattern(
+        'intlayer.config.ts',
+        'intlayer.config.js',
+        'package.json'
+      ),
+    },
+  }
+end
+
+lspconfig.intlayer_lsp.setup({})
+```
+
+Po ponownym uruchomieniu Neovim, naciśnięcie `gd` nad kluczem Intlayer wywoła funkcję Przejdź do definicji.
+
+---
+
+## Ręczna konfiguracja w innych edytorach
+
+Każdy edytor obsługujący protokół Language Server Protocol może korzystać z `@intlayer/lsp`. Specyfikacja serwera:
+
+- **Transport** – Node.js IPC / stdio (standard)
+- **Plik wykonywalny** – `npx @intlayer/lsp` (lub lokalnie zainstalowany plik binarny `intlayer-lsp`)
+- **Możliwości** – `definitionProvider: true`, `textDocumentSync: Incremental`
+
+Skonsultuj się z dokumentacją LSP swojego edytora, aby uzyskać dokładny format konfiguracji (np. `languageserver.json` dla [coc.nvim](https://github.com/neoclide/coc.nvim) lub ustawienia klienta LSP w [Helix](https://helix-editor.com)).
+
+### Przykład: coc.nvim
+
+```json fileName="~/.config/nvim/coc-settings.json"
+{
+  "languageserver": {
+    "intlayer": {
+      "command": "npx",
+      "args": ["@intlayer/lsp"],
+      "filetypes": [
+        "typescript",
+        "typescriptreact",
+        "javascript",
+        "javascriptreact",
+        "vue",
+        "svelte"
+      ],
+      "rootPatterns": [
+        "intlayer.config.ts",
+        "intlayer.config.js",
+        "package.json"
+      ]
+    }
+  }
+}
+```
+
+### Przykład: Helix
+
+```toml fileName="~/.config/helix/languages.toml"
+[[language]]
+name = "typescript"
+language-servers = ["intlayer-lsp", "typescript-language-server"]
+
+[[language]]
+name = "tsx"
+language-servers = ["intlayer-lsp", "typescript-language-server"]
+
+[language-server.intlayer-lsp]
+command = "npx"
+args = ["@intlayer/lsp"]
+```
+
+---
+
+## Jak to działa
+
+Gdy serwer się uruchamia, odczytuje konfigurację Intlayer z głównego katalogu obszaru roboczego za pomocą `getConfiguration()`. Daje mu to ścieżki `build` i `system` niezbędne do znalezienia skompilowanych słowników.
+
+Przy każdym żądaniu **Przejdź do definicji**:
+
+1. Serwer odczytuje pełny tekst otwartego dokumentu.
+2. Skanuje w poszukiwaniu wywołań pobierających (`useIntlayer`, `getIntlayer` itp.) za pomocą wyrażenia regularnego.
+3. Sprawdza, czy pozycja kursora znajduje się wewnątrz jednego z tych wywołań.
+4. Jeśli tak, wyodrębnia klucz słownika (grupa przechwytująca 3 wyrażenia regularnego) i wywołuje `getUnmergedDictionaries()`, aby zlokalizować każdy plik treści, który deklaruje ten klucz.
+5. Odczytuje każdy pasujący plik i znajduje dokładną linię zawierającą `key: "<klucz>"`, aby precyzyjnie ustawić kursor.
+6. Zwraca tablicę obiektów `Location` — po jednym na plik źródłowy.
+
+Konfiguracja jest pobierana leniwie (lazy) i buforowana na sesję; resetuje się przy każdym żądaniu `initialize` (np. przy otwarciu nowego folderu obszaru roboczego).
+
+---
+
+## Rozwiązywanie problemów
+
+| Symptom                              | Prawdopodobna przyczyna            | Rozwiązanie                                                                                       |
+| ------------------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------- |
+| Przejdź do definicji nic nie robi    | Serwer nie działa                  | Sprawdź, czy `@intlayer/lsp` jest zainstalowany i czy edytor go uruchamia                         |
+| Wykryto nieprawidłowy katalog główny | Wiele folderów w obszarze roboczym | Upewnij się, że folder zawierający `intlayer.config.ts` jest pierwszym folderem obszaru roboczego |
+| Nie znaleziono definicji dla klucza  | Konfiguracja nie została wczytana  | Sprawdź, czy `intlayer.config.ts` (lub `.js`) istnieje w katalogu głównym obszaru roboczego       |
+| Serwer ulega awarii przy starcie     | Wersja Node.js jest zbyt stara     | Wymaga Node.js ≥ 14.18                                                                            |

package/docs/pl/releases/v7.md

@@ -66,7 +66,7 @@ Nowy system cache’owania:
 
 - Przechowuje skompilowane deklaracje treści, aby uniknąć zbędnego przetwarzania
 - Wykrywa zmiany i przebudowuje tylko zmodyfikowane pliki
-- Znacząco skraca czas budowania dużych projektów
+- Znacząco skraca czas budowania (build time) dużych projektów
 
 ---
 

package/docs/pl/releases/v8.md

@@ -754,7 +754,7 @@ export default {
 
 ## Walidacja schematów treści
 
-W Intlayer v8 wprowadzono walidację schematów dla słowników. Teraz możesz definiować wielokrotnego użytku schematy walidacji w konfiguracji przy użyciu Zod i stosować je w plikach z zawartością. Dzięki temu Twoja zawartość zawsze będzie zgodna z oczekiwaną strukturą, a błędy zostaną wykryte podczas budowania.
+W Intlayer v8 wprowadzono walidację schematów dla słowników. Teraz możesz definiować wielokrotnego użytku schematy walidacji w konfiguracji przy użyciu Zod i stosować je w plikach z zawartością. Dzięki temu Twoja zawartość zawsze będzie zgodna z oczekiwaną strukturą, a błędy zostaną wykryte podczas budowania (build time).
 
 ### 1. Zdefiniuj schematy
 
@@ -1062,7 +1062,7 @@ Właściwość boolean `live` została oznaczona jako przestarzała na rzecz bar
 
 ### Tryby
 
-- **`static`** (Domyślny): Słownik jest dołączany podczas budowania. Najlepsze dla wydajności.
+- **`static`** (Domyślny): Słownik jest dołączany podczas budowania (build time). Najlepsze dla wydajności.
 - **`dynamic`**: Słownik jest ładowany w czasie wykonywania (np. przez pobranie JSON lub użycie Suspense).
 - **`fetch`**: Słownik jest pobierany z CMS/serwera w czasie wykonywania i synchronizowany.
 

package/docs/pt/agent_skills.md

@@ -72,7 +72,7 @@ npx skills add aymericzip/intlayer-skills
 
 **intlayer-astro**
 
-- Fornece ao agente os conhecimentos necessários para lidar com traduções do lado do servidor e padrões de roteamento localizados exclusivos do ecossistema Astro.
+- Fornece ao agente os conhecimentos necessários para lidar com traduções do lado do servidor e padrões de roteamento por localeizados exclusivos do ecossistema Astro.
 
 **intlayer-content**
 
@@ -80,7 +80,7 @@ npx skills add aymericzip/intlayer-skills
 
 **intlayer-next-js**
 
-- Dá ao agente a profundidade necessária para implementar i18n em componentes Server e Client de Next.js, assegurando a otimização SEO e um roteamento localizado suave.
+- Dá ao agente a profundidade necessária para implementar i18n em componentes Server e Client de Next.js, assegurando a otimização SEO e um roteamento por localeizado suave.
 
 **intlayer-react**
 

package/docs/pt/dictionary/html.md

@@ -280,7 +280,7 @@ Você pode configurar a renderização de HTML globalmente para toda a sua aplic
     );
     ```
 
-    > Importar dinamicamente o seu renderizador de HTML é uma boa maneira de reduzir o tamanho do pacote da sua aplicação.
+    > Importar dinamicamente o seu renderizador de HTML é uma boa maneira de reduzir o tamanho do bundle da sua aplicação.
 
   </Tab>
   <Tab label="Vue" value="vue">
@@ -325,7 +325,7 @@ Você pode configurar a renderização de HTML globalmente para toda a sua aplic
     app.mount("#app");
     ```
 
-    > Importar dinamicamente o seu renderizador de HTML é uma boa maneira de reduzir o tamanho do pacote da sua aplicação.
+    > Importar dinamicamente o seu renderizador de HTML é uma boa maneira de reduzir o tamanho do bundle da sua aplicação.
 
   </Tab>
   <Tab label="Svelte" value="svelte">
@@ -379,7 +379,7 @@ Você pode configurar a renderização de HTML globalmente para toda a sua aplic
     );
     ```
 
-    > Importar dinamicamente o seu renderizador de HTML é uma boa maneira de reduzir o tamanho do pacote da sua aplicação.
+    > Importar dinamicamente o seu renderizador de HTML é uma boa maneira de reduzir o tamanho do bundle da sua aplicação.
 
   </Tab>
   <Tab label="Solid" value="solid">
@@ -415,7 +415,7 @@ Você pode configurar a renderização de HTML globalmente para toda a sua aplic
     );
     ```
 
-    > Importar dinamicamente o seu renderizador de HTML é uma boa maneira de reduzir o tamanho do pacote da sua aplicação.
+    > Importar dinamicamente o seu renderizador de HTML é uma boa maneira de reduzir o tamanho do bundle da sua aplicação.
 
   </Tab>
   <Tab label="Angular" value="angular">
@@ -452,7 +452,7 @@ Você pode configurar a renderização de HTML globalmente para toda a sua aplic
     };
     ```
 
-    > Importar dinamicamente o seu renderizador de HTML é uma boa maneira de reduzir o tamanho do pacote da sua aplicação.
+    > Importar dinamicamente o seu renderizador de HTML é uma boa maneira de reduzir o tamanho do bundle da sua aplicação.
 
   </Tab>
 </Tabs>

package/docs/pt/dictionary/markdown.md

@@ -17,6 +17,9 @@ slugs:
   - content
   - markdown
 history:
+  - version: 8.11.0
+    date: 2026-05-28
+    changes: "Permitir a pré-análise do AST do Markdown para SSR / hidratação"
   - version: 8.10.0
     date: 2026-05-19
     changes: "Adicionado suporte a arquivos `.content.md`"
@@ -737,7 +740,7 @@ 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.
+    > Importar dinamicamente o seu renderizador de Markdown é uma ótima maneira de reduzir o tamanho do bundle da sua aplicação.
 
   </Tab>
   <Tab label="Next.js" value="nextjs">
@@ -779,7 +782,7 @@ 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.
+    > Importar dinamicamente o seu renderizador de Markdown é uma ótima maneira de reduzir o tamanho do bundle da sua aplicação.
 
   </Tab>
   <Tab label="Vue" value="vue">
@@ -830,7 +833,7 @@ O `MarkdownProvider` (ou o seu equivalente do framework) configura o pipeline de
     app.mount("#app");
     ```
 
-    > Importar dinamicamente o seu renderizador de Markdown é uma ótima maneira de reduzir o tamanho do pacote da sua aplicação.
+    > Importar dinamicamente o seu renderizador de Markdown é uma ótima maneira de reduzir o tamanho do bundle da sua aplicação.
 
   </Tab>
   <Tab label="Svelte" value="svelte">
@@ -870,7 +873,7 @@ O `MarkdownProvider` (ou o seu equivalente do framework) configura o pipeline de
     </MarkdownProvider>
     ```
 
-    > Importar dinamicamente o seu renderizador de Markdown é uma ótima maneira de reduzir o tamanho do pacote da sua aplicação.
+    > Importar dinamicamente o seu renderizador de Markdown é uma ótima maneira de reduzir o tamanho do bundle da sua aplicação.
 
   </Tab>
   <Tab label="Preact" value="preact">
@@ -909,7 +912,7 @@ 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.
+    > Importar dinamicamente o seu renderizador de Markdown é uma ótima maneira de reduzir o tamanho do bundle da sua aplicação.
 
   </Tab>
   <Tab label="Solid" value="solid">
@@ -948,7 +951,7 @@ 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.
+    > Importar dinamicamente o seu renderizador de Markdown é uma ótima maneira de reduzir o tamanho do bundle da sua aplicação.
 
   </Tab>
   <Tab label="Angular" value="angular">
@@ -970,7 +973,7 @@ O `MarkdownProvider` (ou o seu equivalente do framework) configura o pipeline de
     export class AppModule {}
     ```
 
-    > Importar dinamicamente o seu renderizador de Markdown é uma ótima maneira de reduzir o tamanho do pacote da sua aplicação.
+    > Importar dinamicamente o seu renderizador de Markdown é uma ótima maneira de reduzir o tamanho do bundle da sua aplicação.
 
   </Tab>
 </Tabs>
@@ -1149,6 +1152,164 @@ export class MyComponent {
 
 ---
 
+## Renderização no Lado do Servidor (SSR) e Hidratação
+
+Em comparação com outros analisadores de Markdown, como remark / rehype, o Intlayer Markdown é livre de dependências e roda tanto no cliente quanto no servidor.
+
+No entanto, o Intlayer otimiza a análise para frameworks de Renderização no Lado do Servidor (SSR) (como Next.js App Router, React Router, Nuxt, SvelteKit, etc.).
+
+Em vez de enviar strings Markdown brutas para o cliente e analisá-las no navegador (o que acarreta uma perda de desempenho), o Intlayer permite pré-analisar o Markdown em uma Árvore de Sintaxe Abstrata (AST) no servidor.
+
+Você pode usar a função `parseMarkdown` do pacote Intlayer do seu framework no lado do servidor para gerar uma AST serializável (objeto `ParsedMarkdown`) e passá-la diretamente para o frontend. Todos os utilitários de renderização do Intlayer (como `<MarkdownRenderer>`, `useMarkdownRenderer`, etc.) aceitam automaticamente esse objeto AST e o renderizam perfeitamente.
+
+### Exemplo em uma Arquitetura Servidor/Cliente
+
+<Tabs group="framework">
+  <Tab label="React Router" value="react">
+
+    ```tsx fileName="server.ts"
+    import { parseMarkdown } from "react-intlayer/markdown";
+
+    // 1. No servidor: Analisar o markdown em uma AST serializável
+    export const loader = async () => {
+      const markdownString = "## My title \n\nLorem Ipsum";
+      const ast = parseMarkdown(markdownString);
+
+      // Retornar a AST como JSON para o cliente
+      return Response.json({ content: ast });
+    };
+    ```
+
+    ```tsx fileName="client.tsx"
+    import { useLoaderData } from "react-router";
+    import { MarkdownRenderer } from "react-intlayer/markdown";
+
+    // 2. No cliente: Renderizar a AST diretamente sem reanalisar
+    export default function Page() {
+      const { content } = useLoaderData();
+
+      // O renderizador aceita uma string bruta ou a AST analisada
+      return <MarkdownRenderer content={content} />;
+    }
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+
+    ```tsx fileName="app/page.tsx"
+    import { parseMarkdown } from "next-intlayer/markdown";
+    import { MarkdownRenderer } from "next-intlayer/markdown";
+
+    export default async function Page() {
+      // 1. Analisar o markdown em uma AST serializável no servidor
+      const markdownString = "## My title \n\nLorem Ipsum";
+      const ast = parseMarkdown(markdownString);
+
+      // 2. Renderizar a AST diretamente
+      // Em um Server Component, isso funciona perfeitamente e passa a AST
+    // diretamente para os componentes de cliente subjacentes, se necessário.
+      return <MarkdownRenderer content={ast} />;
+    }
+    ```
+
+  </Tab>
+  <Tab label="Vue / Nuxt" value="vue">
+
+    ```vue fileName="pages/index.vue"
+    <script setup lang="ts">
+    import { parseMarkdown } from "vue-intlayer/markdown";
+    import { MarkdownRenderer } from "vue-intlayer/markdown";
+
+    // 1. Buscar e analisar o markdown em uma AST no servidor
+    const { data: ast } = await useAsyncData('markdown', () => {
+      const markdownString = "## My title \n\nLorem Ipsum";
+      return parseMarkdown(markdownString);
+    });
+    </script>
+
+    <template>
+      <!-- 2. No cliente: Renderizar a AST diretamente sem reanalisar -->
+      <MarkdownRenderer :content="ast" />
+    </template>
+    ```
+
+  </Tab>
+  <Tab label="SvelteKit" value="svelte">
+
+    ```typescript fileName="+page.server.ts"
+    import { parseMarkdown } from "svelte-intlayer/markdown";
+
+    // 1. No servidor: Analisar o markdown em uma AST serializável
+    export const load = async () => {
+      const markdownString = "## My title \n\nLorem Ipsum";
+      const ast = parseMarkdown(markdownString);
+
+      // Retornar a AST para o cliente
+      return { content: ast };
+    };
+    ```
+
+    ```svelte fileName="+page.svelte"
+    <script lang="ts">
+      import { MarkdownRenderer } from "svelte-intlayer/markdown";
+      export let data;
+    </script>
+
+    <!-- 2. No cliente: Renderizar a AST diretamente sem reanalisar -->
+    <MarkdownRenderer value={data.content} />
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+    O SSR do Angular normalmente resolve os dados no servidor durante o carregamento inicial e hidrata no cliente. Você pode usar resolvers para passar a AST.
+
+    ```typescript fileName="app.resolver.ts"
+    import { Injectable } from "@angular/core";
+    import { Resolve } from "@angular/router";
+    import { parseMarkdown, type ParsedMarkdown } from "angular-intlayer/markdown";
+
+    @Injectable({ providedIn: "root" })
+    export class MarkdownResolver implements Resolve<ParsedMarkdown> {
+      resolve(): ParsedMarkdown {
+        const markdownString = "## My title \n\nLorem Ipsum";
+        // 1. No servidor: Analisar o markdown em uma AST serializável
+        return parseMarkdown(markdownString);
+      }
+    }
+    ```
+
+    ```typescript fileName="app.component.ts"
+    import { Component } from "@angular/core";
+    import { ActivatedRoute } from "@angular/router";
+    import { IntlayerMarkdownService, type ParsedMarkdown } from "angular-intlayer/markdown";
+
+    @Component({
+      selector: "app-root",
+      template: `<div [innerHTML]="renderedMarkdown"></div>`,
+    })
+    export class AppComponent {
+      renderedMarkdown: string = "";
+
+      constructor(
+        private route: ActivatedRoute,
+        private markdownService: IntlayerMarkdownService
+      ) {
+        // 2. No cliente: Renderizar a AST diretamente sem reanalisar
+        this.route.data.subscribe((data) => {
+          this.renderedMarkdown = this.markdownService.renderMarkdown(
+            data.markdownAst
+          ) as string;
+        });
+      }
+    }
+    ```
+
+  </Tab>
+</Tabs>
+
+Esse padrão garante que a lógica de análise do Markdown seja executada inteiramente no servidor, reduzindo significativamente o tempo de execução no cliente e melhorando a velocidade de hidratação inicial.
+
 ## Referência de opções
 
 Essas opções podem ser passadas para `MarkdownProvider`, `MarkdownRenderer`, `useMarkdownRenderer` e `renderMarkdown`.