@intlayer/docs 9.5.4 → 9.5.6

package/docs/pt/how_works_intlayer.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-12
-updatedAt: 2026-08-30
+updatedAt: 2026-09-19
 title: Como o Intlayer funciona
 description: Aprenda como o Intlayer opera internamente. Compreenda a arquitetura e os componentes que tornam o Intlayer poderoso.
 keywords:
@@ -134,49 +134,105 @@ O Intlayer é composto por vários pacotes, cada um com um papel específico no
 
 O pacote `intlayer` é usado em aplicações para declarar conteúdo em arquivos de conteúdo.
 
-### react-intlayer
+### Frameworks de Frontend
+
+<Tabs group="framework">
+  <Tab label="React" value="react">
 
 O pacote `react-intlayer` é usado para interpretar os dicionários do Intlayer e torná-los utilizáveis em aplicações React.
 
-### next-intlayer
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
 
 O pacote `next-intlayer` é usado como uma camada sobre o `react-intlayer` para tornar os dicionários do Intlayer utilizáveis em aplicações Next.js. Ele integra recursos essenciais para fazer o Intlayer funcionar em um ambiente Next.js, como middleware de tradução, roteamento ou configuração do arquivo `next.config.js`.
 
-### vue-intlayer
+  </Tab>
+  <Tab label="Vue" value="vue">
 
 O pacote `vue-intlayer` é usado para interpretar os dicionários do Intlayer e torná-los utilizáveis em aplicações Vue.
 
-### nuxt-intlayer
+  </Tab>
+  <Tab label="Nuxt" value="nuxt">
 
 O pacote `nuxt-intlayer` é um módulo Nuxt para tornar os dicionários do Intlayer utilizáveis em aplicações Nuxt. Ele integra recursos essenciais para fazer o Intlayer funcionar em um ambiente Nuxt, como middleware de tradução, roteamento e a configuração do arquivo `nuxt.config.js`.
 
-### svelte-intlayer
+  </Tab>
+  <Tab label="Svelte" value="svelte">
 
 O pacote `svelte-intlayer` é usado para interpretar os dicionários do Intlayer e torná-los utilizáveis em aplicações Svelte.
 
-### solid-intlayer (WIP)
+  </Tab>
+  <Tab label="Solid" value="solid">
 
 O pacote `solid-intlayer` é usado para interpretar os dicionários do Intlayer e torná-los utilizáveis em aplicações Solid.js.
 
-### preact-intlayer
+  </Tab>
+  <Tab label="Preact" value="preact">
 
 O pacote `preact-intlayer` é usado para interpretar os dicionários do Intlayer e torná-los utilizáveis em aplicações Preact.
 
-### angular-intlayer (WIP)
+  </Tab>
+  <Tab label="Angular" value="angular">
 
 O pacote `angular-intlayer` é usado para interpretar os dicionários do Intlayer e torná-los utilizáveis em aplicações Angular.
 
-### express-intlayer
+  </Tab>
+  <Tab label="Astro" value="astro">
 
-O pacote `express-intlayer` é usado para utilizar o Intlayer em um backend Express.js.
+O pacote `astro-intlayer` fornece as ferramentas necessárias para integrar o Intlayer em aplicações Astro. Ele configura o roteamento baseado em locale e o gerenciamento de dicionários.
+
+  </Tab>
+  <Tab label="Remix" value="remix">
+
+O pacote `remix-intlayer` fornece as ferramentas necessárias para integrar o Intlayer em aplicações Remix. Ele configura o roteamento baseado em locale, o contexto do lado do servidor e o gerenciamento de dicionários.
 
-### react-native-intlayer
+  </Tab>
+  <Tab label="React Native" value="react-native">
 
 O pacote `react-native-intlayer` fornece ferramentas que integram plugins para o Intlayer funcionar com o Metro bundler.
 
-### lynx-intlayer
+  </Tab>
+  <Tab label="Lit" value="lit">
+
+O pacote `lit-intlayer` fornece ferramentas e componentes para interpretar e usar dicionários do Intlayer em aplicações Lit.
+
+  </Tab>
+  <Tab label="Vanilla JS" value="vanilla">
+
+O pacote `vanilla-intlayer` fornece ferramentas para integrar o Intlayer em aplicações JavaScript vanilla, HTML ou PHP.
+
+  </Tab>
+</Tabs>
+
+### Frameworks de Backend
+
+<Tabs group="backend">
+  <Tab label="Express" value="express">
+
+O pacote `express-intlayer` é usado para utilizar o Intlayer em um backend Express.js.
+
+  </Tab>
+  <Tab label="Fastify" value="fastify">
+
+O pacote `fastify-intlayer` fornece um plugin para aplicações Fastify para tratar da internacionalização. Ele detecta o locale do utilizador e decora o objeto request.
 
-O pacote `lynx-intlayer` fornece ferramentas que integram plugins para o Intlayer funcionar com o Lynx bundler.
+  </Tab>
+  <Tab label="Hono" value="hono">
+
+O pacote `hono-intlayer` fornece um middleware para aplicações Hono para lidar com a internacionalização. Ele detecta a localidade do usuário e preenche o objeto de contexto.
+
+  </Tab>
+  <Tab label="Elysia" value="elysia">
+
+O pacote `elysia-intlayer` fornece um plugin para aplicações Elysia para tratar da internacionalização. Ele deteta o locale do utilizador e injeta um objeto `intlayer` no contexto da rota.
+
+  </Tab>
+  <Tab label="AdonisJS" value="adonis">
+
+O pacote `adonis-intlayer` fornece um middleware para aplicações AdonisJS para lidar com a internacionalização. Ele detecta o locale do usuário e fornece funções de tradução.
+
+  </Tab>
+</Tabs>
 
 ### vite-intlayer
 
@@ -186,6 +242,10 @@ Inclui o plugin Vite para integrar o Intlayer com o [Vite bundler](https://vite.
 
 Inclui os comandos e plugins `react-scripts-intlayer` para integrar o Intlayer com aplicações baseadas no Create React App. Esses plugins são baseados no [craco](https://craco.js.org/) e incluem configurações adicionais para o empacotador [Webpack](https://webpack.js.org/).
 
+### eslint-plugin-intlayer
+
+O pacote `eslint-plugin-intlayer` fornece regras de ESLint e oxlint para detectar strings não traduzidas, validar definições de dicionário e garantir as melhores práticas de i18n.
+
 ### intlayer-editor
 
 O pacote `intlayer-editor` é usado para permitir o uso do editor visual. Este pacote, opcional, pode ser instalado em aplicações e será utilizado pelo pacote `react-intlayer`.
@@ -219,6 +279,18 @@ O pacote `@intlayer/cli` é um pacote NPM usado para declarar os scripts relacio
 
 O pacote `@intlayer/mcp` fornece um servidor MCP (Model Context Protocol) que oferece assistência para IDE com inteligência artificial, adaptada ao ecossistema Intlayer. Ele carrega automaticamente a documentação e integra-se com o Intlayer CLI.
 
+### @intlayer/lsp
+
+O pacote `@intlayer/lsp` fornece um servidor Language Server Protocol (LSP) sob medida para o Intlayer. Ele traz recursos de IDE como Ir para a definição, Encontrar referências, visualizações prévias ao passar o mouse, autocompletar chaves de dicionário e avisos de diagnóstico.
+
+### @intlayer/ai
+
+O pacote `@intlayer/ai` fornece capacidades de SDK para aplicações Intlayer, permitindo tradução automatizada e geração de conteúdo impulsionada por IA.
+
+### @intlayer/analytics
+
+O pacote `@intlayer/analytics` fornece ferramentas para coletar métricas de impressão de conteúdo, análises por página/locale e nível de nó, e potencializa testes A/B de conteúdo.
+
 ### @intlayer/dictionaries-entry
 
 O pacote `@intlayer/dictionaries-entry` retorna o caminho de entrada dos dicionários Intlayer: os dicionários mesclados a partir de sua raiz, e os não mesclados, remotos, dinâmicos e fetch a partir de seus subcaminhos `/unmerged`, `/remote`, `/dynamic` e `/fetch`. Como é impossível pesquisar o sistema de arquivos a partir do navegador, usar bundlers como Webpack ou Rollup para recuperar o caminho de entrada dos dicionários não é viável. O pacote e seus subcaminhos são projetados para serem aliasados, permitindo a otimização do empacotamento em vários bundlers, como Vite, Webpack e Turbopack.

package/docs/pt/intlayer_visual_editor.md

@@ -278,6 +278,13 @@ O editor carrega a aplicação em um iframe; por isso, a Política de Segurança
 
 Ele foi projetado primariamente para ambientes locais de desenvolvimento e staging, onde um reload ou rebuild é aceitável. Para editar conteúdo diretamente em produção sem intervenção de deploy, utilize o [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_CMS.md) e seus dicionários remotos.
 
+</Question>
+<Question title="Qual é o custo do editor visual? É excessivo se eu não precisar dele?">
+
+O editor visual do Intlayer tem **custo zero** na sua aplicação se não estiver configurado. A lógica extra só é carregada se explicitamente ativada e necessária.
+
+Mesmo quando ativado, o impacto é extremamente leve (+5 KB, carregado dinamicamente apenas quando ativado), pois a maior parte da lógica é tratada pelo editor do servidor em [app.intlayer.org](https://app.intlayer.org) ou através do pacote `intlayer-editor`. Se você precisa apenas de uma solução simples de tradução sem edição visual, o Intlayer não adiciona nenhuma sobrecarga à sua aplicação.
+
 </Question>
 <Question title="O editor visual é gratuito?">
 

package/docs/pt/intlayer_with_astro.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-03-07
-updatedAt: 2026-08-30
+updatedAt: 2026-09-20
 title: "Astro i18n - Guia completo para traduzir seu aplicativo"
 description: "Sem mais i18next. O guia 2026 para criar uma aplicação Astro multilíngue (i18n). Traduza com agentes de IA e otimize o tamanho do bundle, SEO e desempenho."
 keywords:
@@ -18,6 +18,9 @@ slugs:
 applicationTemplate: https://github.com/aymericzip/intlayer-astro-template
 applicationShowcase: https://intlayer-astro-template.vercel.app
 history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Adicionados os hooks useIntlayer / useLocale e o middleware Astro.locals ao astro-intlayer"
   - version: 8.9.0
     date: 2026-05-04
     changes: "Atualizar o uso da API useIntlayer do Solid para acesso direto a propriedades"
@@ -152,7 +155,7 @@ bun add intlayer astro-intlayer
   O pacote principal que fornece ferramentas de i18n para gerenciamento de configuração, traduções, [declaração de conteúdo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/content_file.md), transpilação e [comandos CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/cli/index.md).
 
 - **astro-intlayer**
-  Inclui o plugin de integração do Astro para vincular o Intlayer ao [bundler Vite](https://vite.dev/guide/why.html#why-bundle-for-production), bem como o middleware para detectar o idioma preferido do usuário, gerenciar cookies e lidar com redirecionamentos de URL.
+  Inclui o plugin de integração do Astro para integrar o Intlayer com o [bundler Vite](https://vite.dev/guide/why.html#why-bundle-for-production), um middleware que resolve o locale de cada requisição em `Astro.locals.intlayer`, e os hooks `useIntlayer` / `useDictionary` / `useLocale`. O mesmo caminho de importação resolve para a implementação de servidor no seu frontmatter `.astro` e para a de cliente (suportada por `vanilla-intlayer`) em blocos `<script>`.
 
 </Step>
 <Step number={2} title="Configurar seu Projeto">
@@ -230,26 +233,28 @@ export default appContent;
 </Step>
 <Step number={5} title="Usar o conteúdo no Astro">
 
-Você pode consumir os dicionários diretamente nos seus arquivos `.astro` usando os ajudantes principais exportados do `intlayer`.
+Consuma seus dicionários em arquivos `.astro` com os hooks exportados pelo `astro-intlayer`. Eles compartilham as assinaturas do `react-intlayer`: `useIntlayer("key")` retorna o conteúdo de um dicionário e `useLocale()` o locale atual, sem necessidade de passar argumentos.
+
+O locale vem do middleware `astro-intlayer`, que a integração registra à frente do seu próprio `src/middleware.ts`. Ele o resolve para cada requisição, a partir do prefixo da URL, depois do locale persistido pelo cliente (cookie ou cabeçalho), depois de `Accept-Language`, e o armazena em `Astro.locals.intlayer`. Páginas pré-renderizadas usam apenas a URL, pois são renderizadas uma única vez para cada visitante.
+
+Você também deve adicionar metadados de SEO como hreflang e links canônicos a cada página e incluir um seletor de idiomas para permitir que os usuários mudem de idioma.
 
 ```astro fileName="src/pages/index.astro"
 ---
+import { useIntlayer, useLocale } from "astro-intlayer";
 import {
-  getIntlayer,
-  getLocaleFromPath,
   getLocalizedUrl,
   defaultLocale,
   localeMap,
   getHTMLTextDir,
-  type LocalesValues,
 } from "intlayer";
 import LocaleSwitcher from "../components/LocaleSwitcher.astro";
 
-// Get the current locale from the URL (e.g. /es/about -> 'es')
-const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
+// Locale resolvido pelo middleware (ex. /pt/about -> 'pt')
+const { locale } = useLocale();
 
-// Get the content for the 'app' dictionary
-const { title } = getIntlayer("app", locale);
+// Conteúdo do dicionário 'app' para este locale
+const { title } = useIntlayer("app");
 ---
 
 <!doctype html>
@@ -301,6 +306,8 @@ const { title } = getIntlayer("app", locale);
 </html>
 ```
 
+> `Astro.locals.intlayer` também expõe `locale`, `defaultLocale` e `availableLocales` aos seus próprios middlewares e endpoints. Passe um locale ou seletor como segundo argumento (`useIntlayer("app", "fr")`, `useIntlayer("faq", { item: 2 })`) para sobrescrever o locale da requisição em uma chamada.
+
 </Step>
 <Step number={6} title="Roteamento Localizado">
 
@@ -330,44 +337,51 @@ A integração do Astro adiciona um middleware Vite que ajuda no roteamento sens
 
 ```astro fileName="src/components/LocaleSwitcher.astro"
 ---
-import {
-  locales,
-  getLocaleName,
-  getLocalizedUrl,
-  getLocaleFromPath,
-  getPathWithoutLocale,
-  type LocalesValues,
-} from "intlayer";
+import { useLocale } from "astro-intlayer";
+import { getLocaleName, getLocalizedUrl, getPathWithoutLocale } from "intlayer";
 
-const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
+const { locale, availableLocales } = useLocale();
 const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
 ---
 
-<nav>
-  {
-    locales.map((localeItem) => (
-      <a
-        href={getLocalizedUrl(pathWithoutLocale, localeItem)}
-        data-locale={localeItem}
-        aria-current={localeItem === locale ? "page" : undefined}
-      >
-        {getLocaleName(localeItem)}
-      </a>
-    ))
-  }
+<nav aria-label="Languages">
+  <ul>
+    {
+      availableLocales.map((localeItem) => (
+        <li key={localeItem} class="p-1">
+          <a
+            href={getLocalizedUrl(pathWithoutLocale, localeItem)}
+            data-locale={localeItem}
+            aria-current={localeItem === locale ? "page" : undefined}
+          >
+            {getLocaleName(localeItem)}
+          </a>
+        </li>
+      ))
+    }
+  </ul>
 </nav>
 
 <script>
-  import { setLocaleInStorageClient, getLocalizedUrl, type LocalesValues } from "intlayer";
+  // No navegador, o mesmo import resolve para a implementação do cliente
+  import { useLocale } from "astro-intlayer";
+  import { getLocalizedUrl, type LocalesValues } from "intlayer";
+
+  // Salva a escolha no cookie de locale e navega para a URL localizada
+  const { setLocale } = useLocale({
+    onLocaleChange: (newLocale) => {
+      window.location.href = getLocalizedUrl(window.location.pathname, newLocale);
+    },
+  });
 
   const localeLinks = document.querySelectorAll("[data-locale]");
 
   localeLinks.forEach((link) => {
-    link.addEventListener("click", (e) => {
+    link.addEventListener("click", (event) => {
       const locale = link.getAttribute("data-locale") as LocalesValues;
 
-      // Atualizar o cookie de locale
-      setLocaleInStorageClient(locale);
+      event.preventDefault();
+      setLocale(locale);
     });
   });
 </script>
@@ -377,6 +391,13 @@ const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
     display: flex;
     gap: 1rem;
   }
+  ul {
+    display: flex;
+    list-style: none;
+    padding: 0;
+    margin: 0;
+    gap: 0.5rem;
+  }
   a[aria-current="page"] {
     font-weight: bold;
     text-decoration: underline;
@@ -384,8 +405,11 @@ const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);
 </style>
 ```
 
-> **Nota sobre Persistência:**
-> Usar `setLocaleInStorageClient` no script do lado do cliente garante que a preferência de idioma do usuário seja salva em um cookie. Isso permite que o middleware Intlayer lembre da escolha e redirecione automaticamente o usuário para seu idioma preferido em visitas futuras.
+> **Nota sobre persistência:**
+> `setLocale` do `useLocale` do lado do cliente salva a preferência de idioma do usuário em um cookie. Isso permite que o Intlayer lembre da escolha e redirecione automaticamente o usuário para seu idioma preferido em visitas futuras: páginas renderizadas sob demanda (um adaptador com `output: 'server'` ou `prerender = false`) são redirecionadas pelo middleware Intlayer antes que qualquer HTML seja enviado, enquanto páginas pré-renderizadas, servidas como arquivos estáticos, são redirecionadas por um pequeno script que a integração injeta em cada página. Defina `routing.enableProxy` como `false` para desativar ambos. No `astro dev`, o cookie é ignorado como fonte de redirecionamento, a menos que `routing.enableProxy` esteja definido como `true`, para que um cookie antigo não sequestre as páginas em que você está trabalhando.
+>
+> **Intercompatibilidade servidor / cliente:**
+> `astro-intlayer` resolve para seus hooks de servidor no frontmatter (lendo `Astro.locals`) e para os hooks de cliente do `vanilla-intlayer` em blocos `<script>` e ilhas, com os mesmos nomes e formato de conteúdo. `setLocale` e `onChange` atuam apenas no cliente, chame `installIntlayer()` lá uma vez para inicializar o armazenamento do cliente. `astro-intlayer/client` expõe a entrada do cliente explicitamente.
 
 </Step>
 <Step number={8} title="Sitemap e Robots.txt">
@@ -409,10 +433,10 @@ const pathList: SitemapUrlEntry[] = [
   { path: "/about", changefreq: "monthly", priority: 0.7 },
 ];
 
-const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
-
 export const GET: APIRoute = async ({ site }) => {
-  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
+  const xmlOutput = generateSitemap(pathList, {
+    siteUrl: "https://example.com",
+  });
 
   return new Response(xmlOutput, {
     headers: { "Content-Type": "application/xml" },
@@ -459,7 +483,6 @@ Continue usando seu framework favorito para construir sua aplicação.
 - Intlayer + Solid: [Intlayer with Solid](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_with_astro_solid.md)
 - Intlayer + Preact: [Intlayer with Preact](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_with_astro_preact.md)
 - Intlayer + Lit: [Intlayer with Lit](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_with_astro_lit.md)
-- Intlayer + Vanilla JS: [Intlayer with Vanilla JS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_with_astro_vanilla.md)
 </Step>
 
 <Step number={15} title="Extraia o conteúdo de seus componentes" isOptional={true}>
@@ -529,21 +552,7 @@ bun x intlayer extract
  </Tab>
  <Tab value='Babel compiler'>
 
-> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
-
-Atualize seu `vite.config.ts` para incluir o plugin `intlayerCompiler`:
-
-```ts fileName="vite.config.ts"
-import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
-
-export default defineConfig({
-  plugins: [
-    intlayer(),
-    intlayerCompiler(), // Adds the compiler plugin
-  ],
-});
-```
+Compile sua aplicação para transformar seus componentes e extrair o conteúdo
 
 ```bash packageManager="npm"
 npm run build # Ou npm run dev

package/docs/pt/intlayer_with_astro_lit.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-04-24
-updatedAt: 2026-08-30
+updatedAt: 2026-09-20
 title: "Astro + Lit i18n - Guia completo para traduzir seu aplicativo"
 description: "Sem mais i18next. O guia 2026 para criar uma aplicação Astro + Lit multilíngue (i18n). Traduza com agentes de IA e otimize o tamanho do bundle, SEO e desempenho."
 keywords:
@@ -19,6 +19,9 @@ slugs:
   - lit
   applicationTemplate: https://github.com/aymericzip/intlayer-astro-template
 history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Uso dos hooks useIntlayer / useLocale do astro-intlayer na página Astro"
   - version: 8.9.0
     date: 2026-05-04
     changes: "Atualizar o uso da API useIntlayer do Solid para acesso direto a propriedades"
@@ -150,7 +153,7 @@ bun add intlayer astro-intlayer lit lit-intlayer @astrojs/lit
   O pacote principal que fornece ferramentas de i18n para gerenciamento de configuração, traduções, [declaração de conteúdo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/content_file.md), transpilação e [comandos CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/cli/index.md).
 
 - **astro-intlayer**
-  Inclui o plugin de integração do Astro para vincular o Intlayer ao [bundler Vite](https://vite.dev/guide/why.html#why-bundle-for-production), bem como o middleware para detectar o idioma preferido do usuário, gerenciar cookies e lidar com redirecionamentos de URL.
+  Inclui o plugin de integração do Astro para integrar o Intlayer com o [bundler Vite](https://vite.dev/guide/why.html#why-bundle-for-production), um middleware que resolve o locale de cada requisição em `Astro.locals.intlayer`, e os hooks `useIntlayer` / `useDictionary` / `useLocale`. O mesmo caminho de importação resolve para a implementação de servidor no seu frontmatter `.astro` e para a de cliente (suportada por `vanilla-intlayer`) em blocos `<script>`.
 
 - **lit**
   Pacote principal do Lit para criar Web Components rápidos e leves.
@@ -245,19 +248,21 @@ export default litDemoContent;
 </Step>
 <Step number={5} title="Usar o conteúdo no Astro">
 
-Você pode consumir os dicionários diretamente nos seus arquivos `.astro` usando os ajudantes principais exportados do `intlayer`. Você também deve adicionar metadados de SEO (como hreflang e links canônicos) a cada página. Os custom elements Lit são importados via um `<script>` no cliente e colocados no corpo da página.
+Consuma seus dicionários em arquivos `.astro` com os hooks exportados pelo `astro-intlayer`. Eles compartilham as assinaturas do `react-intlayer`: `useIntlayer("key")` retorna o conteúdo de um dicionário e `useLocale()` o locale atual, sem necessidade de passar argumentos.
+
+O locale vem do middleware `astro-intlayer`, que a integração registra à frente do seu próprio `src/middleware.ts`. Ele o resolve para cada requisição, a partir do prefixo da URL, depois do locale persistido pelo cliente (cookie ou cabeçalho), depois de `Accept-Language`, e o armazena em `Astro.locals.intlayer`. Páginas pré-renderizadas usam apenas a URL, pois são renderizadas uma única vez para cada visitante.
+
+Os custom elements Lit são importados via um `<script>` no cliente e colocados no corpo da página.
 
 ```astro fileName="src/pages/[...locale]/index.astro"
 ---
+import { useIntlayer, useLocale } from "astro-intlayer";
 import {
-  getIntlayer,
-  getLocaleFromPath,
   getLocalizedUrl,
-  getHTMLTextDir,
   getPrefix,
   localeMap,
   defaultLocale,
-  type LocalesValues,
+  getHTMLTextDir,
 } from "intlayer";
 
 export const getStaticPaths = () => {
@@ -266,8 +271,11 @@ export const getStaticPaths = () => {
   }));
 };
 
-const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
-const { greeting } = getIntlayer("lit-demo", locale);
+// Locale resolvido pelo middleware (ex. /pt/about -> 'pt')
+const { locale } = useLocale();
+
+// Conteúdo do dicionário 'lit-demo' para este locale
+const { greeting } = useIntlayer("lit-demo");
 ---
 
 <!doctype html>
@@ -326,6 +334,8 @@ const { greeting } = getIntlayer("lit-demo", locale);
 > <img src={String(content.image.src)} alt={String(content.image)} />
 > ```
 
+> `Astro.locals.intlayer` também expõe `locale`, `defaultLocale` e `availableLocales` aos seus próprios middlewares e endpoints. Passe um locale ou seletor como segundo argumento (`useIntlayer("app", "fr")`, `useIntlayer("faq", { item: 2 })`) para sobrescrever o locale da requisição em uma chamada.
+
 > **Nota sobre a configuração de roteamento:**
 > A estrutura de diretórios que você usa depende da configuração `middleware.routing` no `intlayer.config.ts`:
 >
@@ -482,10 +492,10 @@ const pathList: SitemapUrlEntry[] = [
   { path: "/about", changefreq: "monthly", priority: 0.7 },
 ];
 
-const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
-
 export const GET: APIRoute = async ({ site }) => {
-  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
+  const xmlOutput = generateSitemap(pathList, {
+    siteUrl: "https://example.com",
+  });
 
   return new Response(xmlOutput, {
     headers: { "Content-Type": "application/xml" },
@@ -585,21 +595,7 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilador Babel'>
 
-> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
-
-Atualize seu `vite.config.ts` para incluir o plugin `intlayerCompiler`:
-
-```ts fileName="vite.config.ts"
-import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
-
-export default defineConfig({
-  plugins: [
-    intlayer(),
-    intlayerCompiler(), // Adds the compiler plugin
-  ],
-});
-```
+Compile sua aplicação para transformar seus componentes e extrair o conteúdo
 
 ```bash packageManager="npm"
 npm run build # Ou npm run dev

package/docs/pt/intlayer_with_astro_preact.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-04-24
-updatedAt: 2026-08-30
+updatedAt: 2026-09-20
 title: "Astro + Preact i18n - Guia completo para traduzir seu aplicativo"
 description: "Sem mais i18next. O guia 2026 para criar uma aplicação Astro + Preact multilíngue (i18n). Traduza com agentes de IA e otimize o tamanho do bundle, SEO e desempenho."
 keywords:
@@ -19,6 +19,9 @@ slugs:
 applicationTemplate: https://github.com/aymericzip/intlayer-astro-template
 applicationShowcase: https://intlayer-astro-template.vercel.app
 history:
+  - version: 9.5.5
+    date: 2026-09-19
+    changes: "Uso dos hooks useIntlayer / useLocale do astro-intlayer na página Astro"
   - version: 8.9.0
     date: 2026-05-04
     changes: "Atualizar o uso da API useIntlayer do Solid para acesso direto a propriedades"
@@ -150,7 +153,7 @@ bun add intlayer astro-intlayer preact preact-intlayer @astrojs/preact
   O pacote principal que fornece ferramentas de i18n para gerenciamento de configuração, traduções, [declaração de conteúdo](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dictionary/content_file.md), transpilação e [comandos CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/cli/index.md).
 
 - **astro-intlayer**
-  Inclui o plugin de integração do Astro para vincular o Intlayer ao [bundler Vite](https://vite.dev/guide/why.html#why-bundle-for-production), bem como o middleware para detectar o idioma preferido do usuário, gerenciar cookies e lidar com redirecionamentos de URL.
+  Inclui o plugin de integração do Astro para integrar o Intlayer com o [bundler Vite](https://vite.dev/guide/why.html#why-bundle-for-production), um middleware que resolve o locale de cada requisição em `Astro.locals.intlayer`, e os hooks `useIntlayer` / `useDictionary` / `useLocale`. O mesmo caminho de importação resolve para a implementação de servidor no seu frontmatter `.astro` e para a de cliente (suportada por `vanilla-intlayer`) em blocos `<script>`.
 
 - **preact**
   Pacote principal do Preact - uma alternativa rápida e leve ao React.
@@ -243,19 +246,21 @@ export default appContent;
 </Step>
 <Step number={5} title="Usar o conteúdo no Astro">
 
-Você pode consumir os dicionários diretamente nos seus arquivos `.astro` usando os ajudantes principais exportados do `intlayer`. Você também deve adicionar metadados de SEO (como hreflang e links canônicos) a cada página e introduzir uma island de Preact para conteúdo interativo no lado do cliente.
+Consuma seus dicionários em arquivos `.astro` com os hooks exportados pelo `astro-intlayer`. Eles compartilham as assinaturas do `react-intlayer`: `useIntlayer("key")` retorna o conteúdo de um dicionário e `useLocale()` o locale atual, sem necessidade de passar argumentos.
+
+O locale vem do middleware `astro-intlayer`, que a integração registra à frente do seu próprio `src/middleware.ts`. Ele o resolve para cada requisição, a partir do prefixo da URL, depois do locale persistido pelo cliente (cookie ou cabeçalho), depois de `Accept-Language`, e o armazena em `Astro.locals.intlayer`. Páginas pré-renderizadas usam apenas a URL, pois são renderizadas uma única vez para cada visitante.
+
+Você também deve adicionar metadados de SEO (como hreflang e links canônicos) a cada página e introduzir uma island de Preact para conteúdo interativo no lado do cliente.
 
 ```astro fileName="src/pages/[...locale]/index.astro"
 ---
+import { useIntlayer, useLocale } from "astro-intlayer";
 import {
-  getIntlayer,
-  getLocaleFromPath,
   getLocalizedUrl,
-  getHTMLTextDir,
   getPrefix,
   localeMap,
   defaultLocale,
-  type LocalesValues,
+  getHTMLTextDir,
 } from "intlayer";
 import { PreactIsland } from "../../components/preact/ReactIsland";
 
@@ -265,8 +270,11 @@ export const getStaticPaths = () => {
   }));
 };
 
-const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;
-const { title } = getIntlayer("app", locale);
+// Locale resolvido pelo middleware (ex. /pt/about -> 'pt')
+const { locale } = useLocale();
+
+// Conteúdo do dicionário 'app' para este locale
+const { title } = useIntlayer("app");
 ---
 
 <!doctype html>
@@ -322,6 +330,8 @@ const { title } = getIntlayer("app", locale);
 > <img src={String(content.image.src)} alt={String(content.image)} />
 > ```
 
+> `Astro.locals.intlayer` também expõe `locale`, `defaultLocale` e `availableLocales` aos seus próprios middlewares e endpoints. Passe um locale ou seletor como segundo argumento (`useIntlayer("app", "fr")`, `useIntlayer("faq", { item: 2 })`) para sobrescrever o locale da requisição em uma chamada.
+
 > **Nota sobre a configuração de roteamento:**
 > A estrutura de diretórios que você usa depende da configuração `middleware.routing` no `intlayer.config.ts`:
 >
@@ -438,10 +448,10 @@ const pathList: SitemapUrlEntry[] = [
   { path: "/about", changefreq: "monthly", priority: 0.7 },
 ];
 
-const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";
-
 export const GET: APIRoute = async ({ site }) => {
-  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });
+  const xmlOutput = generateSitemap(pathList, {
+    siteUrl: "https://example.com",
+  });
 
   return new Response(xmlOutput, {
     headers: { "Content-Type": "application/xml" },
@@ -541,21 +551,7 @@ bun x intlayer extract
  </Tab>
  <Tab value='Compilador Babel'>
 
-> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
-
-Atualize seu `vite.config.ts` para incluir o plugin `intlayerCompiler`:
-
-```ts fileName="vite.config.ts"
-import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
-
-export default defineConfig({
-  plugins: [
-    intlayer(),
-    intlayerCompiler(), // Adds the compiler plugin
-  ],
-});
-```
+Compile sua aplicação para transformar seus componentes e extrair o conteúdo
 
 ```bash packageManager="npm"
 npm run build # Ou npm run dev
@@ -722,6 +718,13 @@ Sim: [formas plurais](https://github.com/aymericzip/intlayer/blob/main/docs/docs
 
 Por meio do [editor visual](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_visual_editor.md), que roda em sua própria infraestrutura e permite editar textos diretamente no app em execução, ou pelo [CMS](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_CMS.md), que externaliza o conteúdo para que ele possa ser alterado sem novos deploys.
 
+</Question>
+<Question title="Qual é o custo do editor visual? É excessivo se eu não precisar dele?">
+
+O [editor visual do Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_visual_editor.md) tem **custo zero** na sua aplicação se não estiver configurado. A lógica extra só é carregada se explicitamente ativada e necessária.
+
+Mesmo quando ativado, o impacto é extremamente leve (+5 KB, carregado dinamicamente apenas quando ativado), pois a maior parte da lógica é tratada pelo editor do servidor em [app.intlayer.org](https://app.intlayer.org) ou através do pacote `intlayer-editor`. Se você precisa apenas de uma solução simples de tradução sem edição visual, o Intlayer não adiciona nenhuma sobrecarga à sua aplicação.
+
 </Question>
 <Question title="O Intlayer é gratuito e de código aberto?">