@intlayer/docs 9.1.3 → 9.3.0

package/docs/pt/analytics.md

@@ -0,0 +1,222 @@
+---
+createdAt: 2026-07-08
+updatedAt: 2026-07-08
+title: Intlayer Analytics | Acompanhe a exposição de conteúdo e execute testes A/B
+description: Descubra como o @intlayer/analytics rastreia visualizações de página/idioma e exposição de conteúdo, e como usá-lo para executar testes A/B em seu conteúdo do Intlayer.
+keywords:
+  - Analytics
+  - Teste A/B
+  - Audiência
+  - Internacionalização
+  - Documentação
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - analytics
+history:
+  - version: 9.0.0
+    date: 2026-07-08
+    changes: "Init doc — pacote @intlayer/analytics, rastreamento a nível de provider/node, testes A/B, dashboard"
+author: aymericzip
+---
+
+# Documentação do Intlayer Analytics
+
+O `@intlayer/analytics` é um pacote complementar opcional que informa **qual conteúdo é realmente exibido** aos seus visitantes — qual página, em qual idioma (locale) e qual trecho específico de conteúdo traduzido — para que você possa entender seu público e executar **testes A/B em conteúdos**.
+
+## Índice
+
+<TOC/>
+
+---
+
+## O que ele rastreia
+
+O `@intlayer/analytics` agrupa três tipos de eventos anônimos:
+
+| Evento             | Onde é capturado                           | O que ele te diz                                                                                                                  |
+| ------------------ | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| `page_view`        | Nível do Provider (`IntlayerProvider`)     | Qual página e idioma uma sessão visualizou, no carregamento inicial, mudança de rota ou mudança de idioma.                        |
+| `content_exposure` | Nível do Node (`useIntlayer` / plugins)    | Qual chave de dicionário / caminho de chave foi realmente resolvido e exibido — e, se parte de um experimento, qual **variante**. |
+| `conversion`       | Onde quer que você chame `useConversion()` | Um objetivo alcançado (cadastro, clique, compra...) atribuído à variante A/B a qual a sessão foi exposta.                         |
+
+Os eventos são coletados na memória e enviados como uma **única solicitação em lote (batch request) aproximadamente a cada 20 segundos** — nunca a cada toque de tecla ou renderização — portanto, a análise nunca afeta o tempo de primeira renderização ou adiciona uma requisição por interação.
+
+## Como ele potencializa testes A/B em conteúdo
+
+O Intlayer já permite que você declare [Variantes](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/index.md) de conteúdo (ex: um dicionário `hero-banner` com uma variante `control` e uma `black_friday`). O `@intlayer/analytics` fecha o ciclo:
+
+1. `getVariant(experimentKey, variants)` atribui de forma determinística cada sessão anônima a uma variante — uma função pura do id da sessão e da chave do experimento, portanto a atribuição é **estável durante toda a sessão** e não requer **viagens de ida e volta ao servidor** antes da primeira renderização (sem cintilação, sem mudança de layout).
+2. Cada evento `content_exposure` carrega a `variant` que foi mostrada.
+3. `useConversion()` permite atribuir um objetivo (ex: `"cta_click"`) a essa variante.
+4. O endpoint de resultados de experimentos do painel de controle (dashboard) compara as taxas de conversão por variante, incluindo significância estatística (um teste z).
+
+## Instalação
+
+O `@intlayer/analytics` é uma dependência **peer e opcional** — nunca instalada automaticamente por um pacote de framework. Adicione-o junto com o `intlayer`:
+
+```bash packageManager="npm"
+npm install @intlayer/analytics
+```
+
+```bash packageManager="yarn"
+yarn add @intlayer/analytics
+```
+
+```bash packageManager="pnpm"
+pnpm add @intlayer/analytics
+```
+
+```bash packageManager="bun"
+bun add @intlayer/analytics
+```
+
+Se você não instalá-lo, todos os pontos de integração se resolvem como uma operação nula (no-op) — veja [Custo zero quando não instalado](#custo-zero-quando-nao-instalado) abaixo.
+
+## Configuração
+
+O Analytics **reutiliza o bloco de configuração `editor` existente** — não há um esquema de configuração `analytics` separado para preencher:
+
+```typescript fileName="intlayer.config.ts" codeFormat={["typescript", "esm", "commonjs"]}
+import type { IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  editor: {
+    backendURL: "https://back.intlayer.org", // Também usado como endpoint de ingestão de análises
+    clientId: "your-client-id", // Também usado como chave de projeto de análises
+    clientSecret: "your-client-secret",
+  },
+};
+
+export default config;
+```
+
+- `editor.backendURL` — a URL base para a qual os eventos de analytics são enviados (`POST {backendURL}/api/analytics/events`).
+- `editor.clientId` — a chave pública do projeto atribuída a todo evento ingerido. Ele também atua como a **chave de ativação**: as análises permanecem totalmente desativadas (e eliminadas pelo tree-shaking, veja abaixo) até que o `clientId` seja configurado.
+
+Se você hospeda o Intlayer por conta própria (self-host), a análise aponta automaticamente para a sua própria instância, já que compartilha o `editor.backendURL`.
+
+## Suporte a Frameworks
+
+O Analytics está conectado ao `IntlayerProvider` compartilhado do `react-intlayer`, portanto, está disponível hoje em qualquer lugar em que esse provider seja usado:
+
+| Framework                                                | Status                                                                                             |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| React                                                    | ✅ Disponível                                                                                      |
+| Next.js (`next-intlayer`)                                | ✅ Disponível (via `react-intlayer`)                                                               |
+| React Native / Expo (`react-native-intlayer`)            | ✅ Disponível (via `react-intlayer`)                                                               |
+| Vue, Svelte, Angular, Solid, Preact, Lit, Astro, Vanilla | 🚧 Planejado — mesmo client, bindings em nível de provider seguindo o padrão do `@intlayer/editor` |
+
+## Uso
+
+### Rastreamento automático a nível de provider
+
+Nenhuma alteração de código é necessária. Assim que o `@intlayer/analytics` estiver instalado e `editor.clientId` configurado, o `IntlayerProvider` automaticamente:
+
+- inicializa o client de analytics na montagem (mount),
+- registra um `page_view` no carregamento inicial,
+- registra um `page_view` a cada mudança de idioma,
+- inicia o ciclo de limpeza (flush loop) de ~20s e limpa quaisquer eventos restantes na desmontagem / fechamento da aba (via `navigator.sendBeacon`, com fallback para `fetch(..., { keepalive: true })`).
+
+### Rastreamento automático a nível de node (nó)
+
+Toda vez que o `useIntlayer` resolve um trecho de conteúdo para exibição, o interpretador reporta um evento `content_exposure` para a exata combinação de `dictionaryKey` + caminho da chave + idioma — novamente, nenhuma alteração de código é necessária. Exposições repetidas do mesmo nó dentro de uma janela de flush são aglutinadas em um único evento com uma contagem (`count`), então uma lista renderizada 50 vezes não envia 50 eventos.
+
+### Rastreando conversões para testes A/B
+
+Use `useConversion()` para atribuir um objetivo à variante que a sessão viu:
+
+```tsx fileName="CTAButton.tsx" codeFormat="tsx"
+import { useConversion } from "react-intlayer";
+
+const CTAButton = () => {
+  const trackConversion = useConversion();
+
+  return (
+    <button
+      onClick={() =>
+        trackConversion({
+          experimentKey: "homepage-hero",
+          variant: "black_friday",
+          goal: "cta_click",
+        })
+      }
+    >
+      Começar
+    </button>
+  );
+};
+```
+
+### Resolvendo uma variante no lado do cliente (client-side)
+
+```tsx fileName="useHeroVariant.ts" codeFormat="tsx"
+import { getGlobalAnalyticsClient } from "@intlayer/analytics/client";
+
+const client = getGlobalAnalyticsClient();
+const variant = client?.getVariant("homepage-hero", [
+  "control",
+  "black_friday",
+]);
+```
+
+## Privacidade e desempenho
+
+- **Anônimo por design (Anonymous by design)**: as sessões são identificadas por um id rotativo; o backend apenas armazena um **hash SHA-256** desse id — nunca o id bruto, nunca um endereço IP.
+- **A localização é aproximada**: apenas um código de país, derivado de cabeçalhos de geolocalização do CDN (`cf-ipcountry`, `x-vercel-ip-country`, ...) — nenhum IP é lido ou armazenado.
+- **URLs excluem parâmetros de busca** por padrão, então strings de query (query strings) nunca são capturadas.
+- **Amostragem (Sampling)**: `sampleRate` permite que você mantenha apenas uma fração dos eventos de exposição de conteúdo em aplicativos de alto tráfego.
+- **Em Lotes (Batched)**: uma requisição aproximadamente a cada 20 segundos (`flushInterval`), ou mais cedo se o buffer encher (`maxBufferSize`) — nunca uma requisição por evento.
+
+### Custo zero quando não instalado
+
+O `@intlayer/analytics` segue exatamente o mesmo padrão de dependência opcional do `@intlayer/editor`:
+
+- cada ponto de integração carrega o pacote através de um **`import()` dinâmico envolto em `try/catch`** — um aplicativo que nunca instala o `@intlayer/analytics` nunca paga um custo de tamanho de bundle ou tempo de execução, e nunca vê um erro;
+- uma variável de ambiente em tempo de compilação (`INTLAYER_ANALYTICS_ENABLED`), definida automaticamente como `'false'` pelo `@intlayer/config` sempre que o `editor.clientId` não estiver configurado, permite que os bundlers **eliminem o código morto (dead-code-eliminate)** de toda a integração;
+- as análises são desativadas dentro do iframe de visualização do editor/CMS do Intlayer, para que as sessões de edição nunca sejam contabilizadas como tráfego real.
+
+## Dashboard: Página Analytics
+
+Depois que seu projeto coletar eventos, a página **Analytics** no [dashboard do Intlayer](https://app.intlayer.org/analytics) (visível na barra lateral após selecionar um projeto) mostra:
+
+- **Usuários ativos** — visitantes distintos ao longo da janela móvel selecionada (7 / 30 / 90 dias).
+- **Usuários hoje** e **usuários nos últimos 7 dias**.
+- **Visualizações de página** na janela selecionada.
+- Um **gráfico de evolução** de visitantes distintos diários.
+- Abas de detalhamento de **Idiomas (Locales)** e **Localização (Location)**, classificando seu público por idioma e país.
+
+## Referência da API do Backend
+
+Todos os endpoints de leitura exigem autenticação; a ingestão de dados é pública e atribuída via `clientId`.
+
+| Método | Endpoint                                    | Descrição                                                                    |
+| ------ | ------------------------------------------- | ---------------------------------------------------------------------------- |
+| `POST` | `/api/analytics/events`                     | Ingerir um lote de eventos (público, atribuído pelo `clientId` no corpo).    |
+| `GET`  | `/api/analytics/overview`                   | Totais de páginas/idiomas para o projeto autenticado.                        |
+| `GET`  | `/api/analytics/audience?days=30`           | Visitantes distintos, page views, série diária, detalhamento idioma + país.  |
+| `GET`  | `/api/analytics/content-stats`              | Totais de exposição por conteúdo, agrupados por chave/caminho/idioma.        |
+| `GET`  | `/api/analytics/experiments/:experimentKey` | Taxas de conversão por variante e significância estatística para testes A/B. |
+
+Você também pode chamá-los programaticamente usando o [CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_CMS.md):
+
+```ts fileName="analytics.ts"
+import { createIntlayerCMS } from "@intlayer/api";
+import { analyticsEndpoint } from "@intlayer/api/analytics";
+
+const cms = createIntlayerCMS();
+
+const { data: audience } = await analyticsEndpoint(cms).getAudience(30);
+```
+
+## Links úteis
+
+- [Dicionários Dinâmicos - Coleções & Variantes](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/dynamic_dictionaries/index.md)
+- [Intlayer CMS - CMS SDK](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_CMS.md)
+- [Editor Visual Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/intlayer_visual_editor.md)
+- [Referência de Configuração](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/configuration.md)
+- [Guia de Auto-hospedagem (Self-Hosting)](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/self_hosting.md)

package/docs/pt/bundle_optimization.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-11-25
-updatedAt: 2026-06-07
+updatedAt: 2026-08-09
 title: Otimizando o Tamanho e a Performance do Bundle i18n
 description: Reduza o tamanho do bundle da sua aplicação otimizando o conteúdo de internacionalização (i18n). Aprenda como aproveitar o tree shaking e lazy loading para dicionários usando o Intlayer.
 keywords:
@@ -16,6 +16,12 @@ slugs:
   - concept
   - bundle-optimization
 history:
+  - version: 9.2.1
+    date: 2026-08-09
+    changes: "`purge` e `minify` agora funcionam no Next.js através do `@intlayer/swc` — nenhum `babel.config.js` necessário"
+  - version: 8.12.0
+    date: 2026-06-24
+    changes: "Listar os plugins Babel na ordem de pipeline exigida (extract → purge → minify → optimize) nas tabelas de referência"
   - version: 8.12.0
     date: 2026-06-07
     changes: "Adicionado `intlayerPurgeBabelPlugin` e `intlayerMinifyBabelPlugin` para Babel/Webpack; esclarecimento do pipeline de plugins"
@@ -191,12 +197,14 @@ As vertentes pautadas do ecossistema otimizado base pelo Intlayer consistem num
 
 Este ramo abrange puramente escopos direcionados e voltados ao processo em setups no núcleo interno de implementações em formato Webpack operando com arquivos predefinidos nas bases (como é o caso natural do Babel associado de base, Webpack modular customizado em sua integridade nativa do CRA entre outros propósitos da extensão `babel.config.js` ).
 
+A tabela abaixo os lista na ordem de pipeline exigida (a mesma ordem em que devem aparecer no `babel.config.js`):
+
 | Funções do Plugin Base        | Fatores Práticos Do Recurso E Suas Integrações Com Componentes                                                                                                                 |
 | :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `intlayerExtractBabelPlugin`  | Percorre todo núcleo do escopo com premissa modular ligando fatores associativos entre funções `.content.ts` com as propostas associadas à destinação em pastas `.intlayer/`   |
-| `intlayerOptimizeBabelPlugin` | Adota premissas nativas mudando o sentido focado de `useIntlayer('key')` para abranger a otimizada base `useDictionary(hash)` gerindo implementações no escopo do `import`     |
 | `intlayerPurgeBabelPlugin`    | Mapeia e integra lógicas puramente atreladas a varreduras com intento final na premissa base de descartar os **campos sem uso das diretivas** com base final dos dicionários   |
 | `intlayerMinifyBabelPlugin`   | Transcreve sua **chave matriz base na nomeclatura compacta sob a extensão de referências nativas alfabéticas limitadas em seus núcleos** (`title` → `a`) sob suas origens JSON |
+| `intlayerOptimizeBabelPlugin` | Adota premissas nativas mudando o sentido focado de `useIntlayer('key')` para abranger a otimizada base `useDictionary(hash)` gerindo implementações no escopo do `import`     |
 
 > **Cuidado Atrelado Com A Ordem Da Execução Preestabelecida Do Arquivo Principal:** O esquema atrelado com os focos das bases de expurgo (purge) e premissas curtas em definições (minify) tendem inevitavelmente estarem e persistirem em um nível que antecede de antemão e antes que se executem e apliquem o método referencial em otimização (`optimize`) na base primária do arquivo nativo `babel.config.js`. Se o optimize operar logo em instâncias prematuras o registro das senhas chave tendem a se omitir não proporcionando suporte base o bastante nas partes do escopo e apagando registros nativos sobre premissas das matrizes JSON que deverão ser mapeadas na função da execução seguinte.
 
@@ -205,9 +213,9 @@ Tais modelos adquirem opções e propósitos associados com integrações perant
 | Helpers de Opcionais         | Integração Destinada Relacionada Ao Base |
 | :--------------------------- | :--------------------------------------- |
 | `getExtractPluginOptions()`  | `intlayerExtractBabelPlugin`             |
-| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin`            |
 | `getPurgePluginOptions()`    | `intlayerPurgeBabelPlugin`               |
 | `getMinifyPluginOptions()`   | `intlayerMinifyBabelPlugin`              |
+| `getOptimizePluginOptions()` | `intlayerOptimizeBabelPlugin`            |
 
 ### O Setup Por Trás De Vite (`vite-intlayer`)
 
@@ -220,6 +228,20 @@ O usuário da base focada na plataforma gerada do esquema no Vite não fará man
 | Dictionary minify                  | Base análoga e integrada de premissas com ligações nos escritos pautando referências no molde JSON nativo voltada do `intlayerMinifyBabelPlugin`                                                                                                                           |
 | Babel transform                    | Associa parâmetros no suporte transformativo que atua nas esferas associativas dos diretórios voltados do renome natural em conjunto focado ao `intlayerMinifyBabelPlugin` e também ao respectivo processo preestabelecido da função modular `intlayerOptimizeBabelPlugin` |
 
+### Plugin SWC (`@intlayer/swc`)
+
+Os usuários do Next.js também **nunca configuram isto diretamente**. Desde a **v9.2.1**, o `withIntlayer()` no `next.config.ts` executa todo o pipeline — purge, minificação e reescrita de imports — apenas a partir das flags `build.purge` e `build.minify`.
+
+O trabalho é dividido em dois, porque um plugin Wasm do SWC transforma um arquivo por vez e não tem acesso ao sistema de arquivos:
+
+| Passagem                                           | Onde é executada                 | O que faz                                                                                              |
+| :------------------------------------------------- | :------------------------------- | :----------------------------------------------------------------------------------------------------- |
+| Análise de uso + purge/minificação do JSON         | Node, dentro de `withIntlayer()` | Lê cada arquivo-fonte de componente, reescreve `.intlayer/**/*.json` e produz as tabelas de renomeação |
+| Reescrita do código-fonte (`content.title` → `.a`) | `@intlayer/swc` (Wasm)           | Aplica as tabelas de renomeação aos acessos de propriedade correspondentes no seu código               |
+| Reescrita de imports (`useIntlayer` → dict)        | `@intlayer/swc` (Wasm)           | Igual ao `intlayerOptimizeBabelPlugin`                                                                 |
+
+Decidir _quais_ campos não são usados e _qual_ alias cada um recebe exige estado entre arquivos e E/S de arquivos, então essa metade roda no Node; o plugin SWC recebe apenas as tabelas resultantes.
+
 ## Etapas Em Modos Variados (Plataformas)
 
 <Tabs>
@@ -227,10 +249,12 @@ O usuário da base focada na plataforma gerada do esquema no Vite não fará man
 
 ### Next.js
 
-Os propósitos focais relativos com ecossistemas formatados a propósitos otimizados necessitam aderirem sobre implementações preteridas nativas associadas aos componentes pautados em referências no padrão construtivo em `@intlayer/swc`. Esse foco ocorre puramente de maneira interna pois essa vertente pautada trabalha perante construções atreladas sobre formatos definidos sob escopo formatado nativamente pelo formato modular `SWC`.
+O Next.js requer o plugin `@intlayer/swc`, porque o Next.js usa SWC para as builds. Desde a **v9.2.1**, este único pacote cobre todo o pipeline — otimização (reescrita de imports), purge e minificação.
 
 > Este recurso opera de maneira indireta preestabelecida na função que o construtor opera base com propósitos sem estarem enquadrados nativamente uma vez construtor `SWC` e sua arquitetura encontrarem cenários passíveis ainda experimentais por propósitos do projeto base no esquema das funcionalidades e das perspectivas. Tais perspectivas podem tender a serem diferentes em longo prazo por propostas alheias e afins.
 
+> **Next.js 16.1.0 é a versão mínima.** É a primeira versão construída sobre a ABI de plugins Wasm do SWC compatível com versões futuras; versões anteriores rejeitam o plugin. O `withIntlayer` lê a sua versão do Next.js e simplesmente não registra o plugin abaixo da 16.1.0 — essas builds continuam a ser bem-sucedidas, apenas rodam sem a otimização de bundle.
+
 <Tabs>
  <Tab value="npm">
 
@@ -265,32 +289,40 @@ intlayer-swc-plugin = "*"
 
 Os processos automatizam os engajamentos atrelando sua extensão integrativa assim em propostas isoladas.
 
-O panorama atua mediante referências relacionadas do **purge e também atrelado a extensões minificadas (minify)** para proporcionar ligações atreladas mediante inserção atrelada com apoio referencial focado de `@intlayer/babel`. Como ocorrem as ligações base no transformativo `SWC` os plugins Babel operam em vias em propósitos associados com pre-procedimentos base.
+As passagens de **purge e minificação** (remoção e renomeação de campos) não exigem nenhum pacote adicional nem `babel.config.js`. Envolva a sua configuração com `withIntlayer` e ative as flags no `intlayer.config.ts`:
 
-```bash packageManager="npm"
-npm install -D @intlayer/babel
+```typescript fileName="next.config.ts"
+import { withIntlayer } from "next-intlayer/server";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {/* sua configuração */};
+
+export default withIntlayer(nextConfig);
 ```
 
-```javascript fileName="babel.config.js"
-const {
-  intlayerPurgeBabelPlugin,
-  intlayerMinifyBabelPlugin,
-  getPurgePluginOptions,
-  getMinifyPluginOptions,
-} = require("@intlayer/babel");
+```typescript fileName="intlayer.config.ts"
+import type { IntlayerConfig } from "intlayer";
 
-module.exports = {
-  presets: ["next/babel"],
-  plugins: [
-    // Purge: Otimiza seu diretório na base focada sem o envolvimento associativo sobre chaves nulas JSON formatadas nas origens de suporte ".intlayer/**/*.json"
-    [intlayerPurgeBabelPlugin, getPurgePluginOptions()],
-    // Minify: Trata chaves nativas da função JSON diminuindo na transcrição compacta da implementação
-    [intlayerMinifyBabelPlugin, getMinifyPluginOptions()],
-    // Note: Foco sem amparo de obrigatoriedade perante a relação e ligações do `@intlayer/swc` por ser passível ao suporte da formatação relativa focado no formato com rescrição no `useIntlayer` em vias perante `useDictionary`.
-  ],
+const config: IntlayerConfig = {
+  build: {
+    purge: true, // remove campos de conteúdo não usados do JSON empacotado
+    minify: true, // renomeia as chaves dos campos para aliases curtos
+  },
 };
+
+export default config;
 ```
 
+Durante o `next build`, o `withIntlayer` analisa seus fontes, reescreve os dicionários compilados e repassa as tabelas de renomeação resultantes ao `@intlayer/swc`, que atualiza os acessos de propriedade correspondentes no seu código.
+
+> Use o `withIntlayer` assíncrono, não o `withIntlayerSync`. A variante síncrona não executa o pipeline de análise, então purge e minificação não têm efeito com ela.
+
+> Purge e minificação são executados apenas no `next build` — o pipeline de otimização fica desligado durante o `next dev`.
+
+> Eles também são desativados quando chamadores de adaptadores de compatibilidade estão configurados (`swcExtraCallers`, definidos pelos pacotes de compatibilidade como `@intlayer/next-intl` ou `@intlayer/react-i18next`): esses pontos de chamada são invisíveis para o analisador de uso, então o purge removeria campos que o código ainda lê. A reescrita de imports permanece ativa.
+
+**Versões anteriores (antes da 9.2.1)** exigiam `@intlayer/babel` e um `babel.config.js` declarando `intlayerPurgeBabelPlugin` e `intlayerMinifyBabelPlugin`. Esse arquivo não é mais necessário e pode ser excluído.
+
  </Tab>
  <Tab value="vite">
 
@@ -442,6 +474,8 @@ export default config;
 
 > Os propósitos associativos das exclusões nas transformações focando nas extensões da minimização acabam por pautar no pulo perante processos integrando false no seu escopo no otimizador e false focando nos diretórios `editor.enabled`.
 
+> No Next.js, a minificação também é ignorada quando o `@intlayer/swc` não está instalado ou não pode ser carregado (Next.js abaixo da 16.1.0). O plugin é a metade que reescreve os acessos no código-fonte, então renomear os dicionários sem ele deixaria seu código lendo nomes de campos que não existem mais.
+
 > Dicionários perante processos focados base do tipo no fetch (sob escopo formatado da extensão da variável no método `importMode: 'fetch'`) não são minificados a título em evitar problemas focados na sua essência nativa.
 
 ### Foco Modular Constante Relativo Em Extensões (Exclusões Focadas)
@@ -470,7 +504,7 @@ export default config;
 { "title": "…", "subtitle": "…" }
 ```
 
-> Processos atrelados pautando focos purificados são limitados atrelados nos parâmetros atrelados nos propósitos e diretórios de optimize em restrições do false no otimizador integrando ao formato modular no limite focando no suporte das formatações base false nos diretórios da edição e formatos no construto formatado da extensão construtiva.
+> Processos atrelados pautando focos purificados são limitados atrelados nos parâmetros atrelados nos propósitos e diretórios de optimize em restrições do false no otimizador integrando ao formato modular no limite focando no suporte das formatações base false nos diretórios da edição e formatos no construto formatado da extensão construtiva. No Next.js ele é adicionalmente ignorado quando o `@intlayer/swc` está indisponível e quando chamadores de adaptadores de compatibilidade estão configurados.
 
 > Processos perante o uso na purificação também são suspensos perante focos no método nativo que limitam análises do suporte da base com dados referenciados da função de predefinições e diretrizes voltadas atrelando propósitos de extensão.
 

package/docs/pt/configuration.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-13
-updatedAt: 2026-07-11
+updatedAt: 2026-08-06
 title: Configuração (Configuration)
 description: Saiba como configurar o Intlayer para a sua aplicação. Entenda as várias configurações e opções disponíveis para personalizar o Intlayer conforme as suas necessidades.
 keywords:
@@ -14,6 +14,9 @@ slugs:
   - concept
   - configuration
 history:
+  - version: 9.1.3
+    date: 2026-08-06
+    changes: "Tornar `routing.enableProxy` de três estados: não definido (auto), `true`, `false`"
   - version: 9.0.0
     date: 2026-07-11
     changes: "Adicionada a configuração `analytics`"
@@ -235,6 +238,19 @@ const config: IntlayerConfig = {
      */
     mode: "prefix-no-default",
 
+    /**
+     * Ativa o proxy de roteamento de locales do Intlayer (middleware).
+     * Trata deteção de locale, redirecionamentos e rewrites em dev, preview e SSR.
+     * - não definido (auto): os servidores de dev e preview mantêm o roteamento
+     *   guiado pela URL, ignorando o locale armazenado em cookies e cabeçalhos.
+     *   Os prefixos continuam a ser resolvidos, o locale continua a ser persistido
+     *   e a deteção Accept-Language continua a aplicar-se. Em produção age como `true`.
+     * - true: comportamento completo em todos os ambientes.
+     * - false: sem roteamento de locales.
+     * Padrão: undefined (auto)
+     */
+    enableProxy: undefined,
+
     /**
      * Onde armazenar o idioma selecionado pelo utilizador.
      * Opções: 'cookie', 'localStorage', 'sessionStorage', 'header', ou um array destes.
@@ -716,13 +732,14 @@ Os analytics são estritamente opt-in: nada é recolhido a menos que `analytics.
 
 Definições que controlam o comportamento do roteamento, incluindo estrutura de URL, armazenamento de idiomas e gestão de middleware.
 
-| Campo      | Descrição                                                                                                                                                                                                               | Tipo                                                                                                                                                                                                         | Padrão                 | Exemplo                                                                                                                                                                                     | Nota                                                                                                                                                                                                                                                                                                    |
-| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mode`     | Modo de roteamento de URL para a gestão de idiomas.                                                                                                                                                                     | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) ou `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: idioma gerido por outros meios. `'search-params'`: `/dashboard?locale=fr` | Não afeta a gestão de cookies ou armazenamento de idiomas.                                                                                                                                                                                                                                              |
-| `storage`  | Configuração para o armazenamento do idioma no cliente.                                                                                                                                                                 | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                          | Veja a tabela de Opções de Armazenamento abaixo.                                                                                                                                                                                                                                                        |
-| `basePath` | O caminho base para os URLs da aplicação.                                                                                                                                                                               | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                                 | Se a app está em `https://example.com/my-app`, basePath é `'/my-app'` e os URLs tornam-se `https://example.com/my-app/en`.                                                                                                                                                                              |
-| `rewrite`  | Regras de reescrita de URL personalizadas que anulam o modo de roteamento padrão para caminhos específicos. Suporta parâmetros dinâmicos `[param]`.                                                                     | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | Veja o exemplo abaixo                                                                                                                                                                       | • Regras de reescrita têm precedência sobre `mode`.<br/>• Funciona com Next.js e Vite.<br/>• `getLocalizedUrl()` aplica as regras correspondentes automaticamente.<br/>• Veja [Reescritas de URL Personalizadas](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/custom_url_rewrites.md). |
-| `domains`  | Mapeia idiomas para nomes de host de domínio para roteamento baseado em domínio. Quando definido, as URLs para um idioma usam esse domínio como base (URL absoluta) e nenhum prefixo de idioma é adicionado ao caminho. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                                 | • O protocolo padrão é `https://` quando não incluído no nome do host.<br/>• O próprio domínio identifica o idioma, portanto nenhum prefixo `/zh/` é adicionado.<br/>• `getLocalizedUrl('/', 'zh')` retorna `https://intlayer.zh/`.                                                                     |
+| Campo         | Descrição                                                                                                                                                                                                               | Tipo                                                                                                                                                                                                         | Padrão                 | Exemplo                                                                                                                                                                                     | Nota                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`        | Modo de roteamento de URL para a gestão de idiomas.                                                                                                                                                                     | `'prefix-no-default'` &#124; <br/> `'prefix-all'` &#124; <br/> `'no-prefix'` &#124; <br/> `'search-params'`                                                                                                  | `'prefix-no-default'`  | `'prefix-no-default'`: `/dashboard` (en) ou `/fr/dashboard` (fr). `'prefix-all'`: `/en/dashboard`. `'no-prefix'`: idioma gerido por outros meios. `'search-params'`: `/dashboard?locale=fr` | Não afeta a gestão de cookies ou armazenamento de idiomas.                                                                                                                                                                                                                                                                                                                                                        |
+| `enableProxy` | Ativa o proxy de roteamento de locales do Intlayer (middleware).                                                                                                                                                        | `boolean` &#124; <br/> `undefined`                                                                                                                                                                           | `undefined` (auto)     | `true`                                                                                                                                                                                      | • Não definido (auto): os servidores de dev e preview ignoram o locale armazenado em cookies/cabeçalhos como fonte de redirecionamento; prefixos, persistência e deteção `Accept-Language` continuam a aplicar-se. Em produção age como `true`.<br/>• `true`: comportamento completo em todo o lado.<br/>• `false`: sem roteamento de locales. No Next.js, o middleware `intlayerProxy` passa a ser transparente. |
+| `storage`     | Configuração para o armazenamento do idioma no cliente.                                                                                                                                                                 | `false` &#124; <br/> `'cookie'` &#124; <br/> `'localStorage'` &#124; <br/> `'sessionStorage'` &#124; <br/> `'header'` &#124; <br/> `CookiesAttributes` &#124; <br/> `StorageAttributes` &#124; <br/> `Array` | `['cookie', 'header']` | `'localStorage'` <br/> `[{ type: 'cookie', name: 'custom-locale', secure: true }]`                                                                                                          | Veja a tabela de Opções de Armazenamento abaixo.                                                                                                                                                                                                                                                                                                                                                                  |
+| `basePath`    | O caminho base para os URLs da aplicação.                                                                                                                                                                               | `string`                                                                                                                                                                                                     | `''`                   | `'/my-app'`                                                                                                                                                                                 | Se a app está em `https://example.com/my-app`, basePath é `'/my-app'` e os URLs tornam-se `https://example.com/my-app/en`.                                                                                                                                                                                                                                                                                        |
+| `rewrite`     | Regras de reescrita de URL personalizadas que anulam o modo de roteamento padrão para caminhos específicos. Suporta parâmetros dinâmicos `[param]`.                                                                     | `Record<string, StrictModeLocaleMap<string>>`                                                                                                                                                                | `undefined`            | Veja o exemplo abaixo                                                                                                                                                                       | • Regras de reescrita têm precedência sobre `mode`.<br/>• Funciona com Next.js e Vite.<br/>• `getLocalizedUrl()` aplica as regras correspondentes automaticamente.<br/>• Veja [Reescritas de URL Personalizadas](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/custom_url_rewrites.md).                                                                                                           |
+| `domains`     | Mapeia idiomas para nomes de host de domínio para roteamento baseado em domínio. Quando definido, as URLs para um idioma usam esse domínio como base (URL absoluta) e nenhum prefixo de idioma é adicionado ao caminho. | `Partial<Record<Locale, string>>`                                                                                                                                                                            | `undefined`            | `{ zh: 'intlayer.zh', fr: 'intlayer.org' }`                                                                                                                                                 | • O protocolo padrão é `https://` quando não incluído no nome do host.<br/>• O próprio domínio identifica o idioma, portanto nenhum prefixo `/zh/` é adicionado.<br/>• `getLocalizedUrl('/', 'zh')` retorna `https://intlayer.zh/`.                                                                                                                                                                               |
 
 **Exemplo de `rewrite`**:
 

package/docs/pt/dictionary/file.md

@@ -23,7 +23,9 @@ history:
 author: aymericzip
 ---
 
-# Conteúdo de Arquivo / Incorporando Arquivos no Intlayer
+# Conteúdo de Arquivo / Incorporação de Arquivos no Intlayer
+
+No Intlayer, a função `file` permite incorporar conteúdo de arquivo externo em um dicionário. Esta abordagem garante que o Intlayer reconheça o arquivo de origem, permitindo integração perfeita com o Editor Visual do Intlayer e CMS.
 
 ## Como Funciona a Incorporação de Arquivos
 

package/docs/pt/dictionary/nesting.md

@@ -64,6 +64,53 @@ export default firstDictionary;
 }
 ```
 
+### Referenciamento com Nest
+
+Agora, crie outro módulo de conteúdo que usa a função `nest` para referenciar o conteúdo acima. Você pode referenciar todo o conteúdo ou um valor aninhado específico:
+
+```typescript fileName="secondDictionary.content.ts" contentDeclarationFormat={["typescript", "esm", "commonjs"]}
+import { nest, type Dictionary } from "intlayer";
+
+const myNestingContent = {
+  key: "key_of_my_second_dictionary",
+  content: {
+    // Referencia todo o dicionário:
+    fullNestedContent: nest("key_of_my_first_dictionary"),
+    // Referencia um valor aninhado específico:
+    partialNestedContent: nest(
+      "key_of_my_first_dictionary",
+      "subContent.contentNumber"
+    ),
+  },
+} satisfies Dictionary;
+
+export default myNestingContent;
+```
+
+```json fileName="secondDictionary.content.json" contentDeclarationFormat="json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "key_of_my_second_dictionary",
+  "content": {
+    "fullNestedContent": {
+      "nodeType": "nested",
+      "nested": {
+        "dictionaryKey": "key_of_my_first_dictionary"
+      }
+    },
+    "partialNestedContent": {
+      "nodeType": "nested",
+      "nested": {
+        "dictionaryKey": "key_of_my_first_dictionary",
+        "path": "subContent.contentNumber"
+      }
+    }
+  }
+}
+```
+
+Como segundo parâmetro, você pode especificar um caminho para um valor aninhado dentro desse conteúdo. Quando nenhum caminho é fornecido, todo o conteúdo do dicionário referenciado é retornado.
+
 ## Configurando o Aninhamento
 
 <Tabs group="framework">
@@ -258,36 +305,6 @@ document.getElementById("nested")!.textContent = content.partialNestedContent;
   </Tab>
 </Tabs>
 
-## Usando Aninhamento com React Intlayer
-
-Para usar conteúdo aninhado em um componente React, utilize o hook `useIntlayer` do pacote `react-intlayer`. Este hook recupera o conteúdo correto com base na chave especificada. Aqui está um exemplo de como usá-lo:
-
-```tsx fileName="**/*.tsx" codeFormat={["typescript", "esm"]}
-import type { FC } from "react";
-import { useIntlayer } from "react-intlayer";
-
-const NestComponent: FC = () => {
-  const { fullNestedContent, partialNestedContent } = useIntlayer(
-    "key_of_my_second_dictionary"
-  );
-
-  return (
-    <div>
-      <p>
-        Conteúdo Aninhado Completo: {JSON.stringify(fullNestedContent)}
-        {/* Saída: {"content": "content", "subContent": {"contentNumber": 0, "contentString": "string"}} */}
-      </p>
-      <p>
-        Valor Aninhado Parcial: {partialNestedContent}
-        {/* Saída: 0 */}
-      </p>
-    </div>
-  );
-};
-
-export default NestComponent;
-```
-
 ## Recursos Adicionais
 
 Para mais informações detalhadas sobre configuração e uso, consulte os seguintes recursos: