@intlayer/docs 9.0.0-canary.5 → 9.0.0-canary.7

package/docs/pt/packages/vite-intlayer/intlayerProxy.md

@@ -0,0 +1,172 @@
+---
+createdAt: 2026-06-25
+updatedAt: 2026-06-25
+title: Documentação do plugin Vite intlayerProxy | vite-intlayer
+description: Middleware de roteamento de idioma para servidores dev/preview do Vite e SSR de produção. Lida com detecção de idioma, redirecionamentos de URL e reescritas internas.
+keywords:
+  - intlayerProxy
+  - vite
+  - plugin
+  - middleware
+  - idioma
+  - roteamento
+  - internacionalização
+  - i18n
+  - SSR
+slugs:
+  - doc
+  - packages
+  - vite-intlayer
+  - intlayerProxy
+history:
+  - version: 9.0.0
+    date: 2026-06-25
+    changes: "Mesclado configOptions em um único objeto de opções; proxy empacotado no intlayer()"
+author: aymericzip
+---
+
+# intlayerProxy
+
+O `intlayerProxy` é um plugin do Vite que registra o middleware de roteamento de idioma para **todos os ambientes**: servidor de desenvolvimento (dev server), servidor de visualização (preview server) e SSR de produção (Nitro / TanStack Start).
+
+> **A partir do Intlayer v9**, o `intlayerProxy` é incluído automaticamente dentro do plugin principal [`intlayer()`](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/packages/vite-intlayer/intlayer.md) e ativado por padrão via `routing.enableProxy: true`. Você só precisa registrá-lo separadamente se precisar de controle de nível mais baixo ou se estiver usando-o fora da configuração padrão do `intlayer()`.
+
+## Uso
+
+### Como parte do `intlayer()` (recomendado, v9+)
+
+Passe as opções do `proxy` para o plugin principal em vez de registrar o `intlayerProxy` separadamente:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
+});
+```
+
+### Standalone (quando necessário)
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { intlayer } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [intlayer()],
+});
+```
+
+## Opções
+
+```ts
+import type { IntlayerProxyPluginOptions } from "vite-intlayer";
+```
+
+Todas as opções são opcionais e passadas como um único objeto:
+
+| Opção           | Tipo                                | Descrição                                                                                                                                                                          |
+| --------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ignore`        | `(req: IncomingMessage) => boolean` | Predicado que exclui requisições do roteamento de idioma. Retorne `true` para ignorar uma requisição (ex: rotas de API, verificações de integridade).                              |
+| `configOptions` | `GetConfigurationOptions`           | Substituições de configuração do Intlayer encaminhadas para `getConfiguration()`. Use quando precisar que o proxy leia um arquivo de configuração específico ou substitua valores. |
+
+### Exemplo
+
+```ts
+intlayerProxy({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+```
+
+## createIntlayerProxyHandler
+
+O `createIntlayerProxyHandler` cria um middleware Node.js `(req, res, next)` independente de framework que contém toda a lógica de roteamento de idioma. É útil em ambientes onde a API do plugin do Vite não está disponível (ex: um servidor Node.js simples ou um módulo Nitro personalizado).
+
+```ts
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+const handler = createIntlayerProxyHandler({
+  ignore: (req) => req.url?.startsWith("/api"),
+  configOptions: { configFile: "./config/intlayer.config.ts" },
+});
+
+// Express / Connect
+app.use(handler);
+```
+
+### SSR de Produção (TanStack Start / Nitro via h3)
+
+```ts
+// server/middleware/intlayerProxy.ts
+import { fromNodeMiddleware } from "h3";
+import { createIntlayerProxyHandler } from "vite-intlayer";
+
+export default fromNodeMiddleware(
+  createIntlayerProxyHandler({
+    ignore: (req) => req.url?.startsWith("/api"),
+  })
+);
+```
+
+## Comportamento de roteamento
+
+O middleware espelha a lógica de roteamento do middleware `next-intlayer` e suporta todos os modos de roteamento do Intlayer.
+
+### Modos de roteamento
+
+| Modo            | URL visível no navegador | Comportamento                                                                                                                            |
+| --------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `prefix`        | `/pt/about`              | Padrão. Prefixo de idioma na URL. O idioma padrão redireciona para a URL sem prefixo, a menos que `prefix-all` esteja ativo.             |
+| `prefix-all`    | `/en/about`, `/pt/about` | Todos os idiomas — incluindo o padrão — são sempre prefixados.                                                                           |
+| `no-prefix`     | `/about`                 | Sem idioma na URL. O idioma é armazenado apenas em cookies; as reescritas de URL ocorrem internamente.                                   |
+| `search-params` | `/about?locale=pt`       | Idioma passado como um parâmetro de consulta. Redireciona para adicionar/atualizar o parâmetro `locale` quando ausente ou desatualizado. |
+
+### Prioridade de detecção
+
+1. Prefixo do caminho da URL (ex: `/pt/about` → `pt`).
+2. Valor do cookie / localStorage (`intlayer-locale`).
+3. Cabeçalho `Accept-Language`.
+4. `defaultLocale` da configuração.
+
+### Desvio automático (Bypass)
+
+O middleware sempre passa essas requisições diretamente sem manipulação de idioma:
+
+- Requisições que correspondem ao predicado `ignore`.
+- `/node_modules/**`
+- `/@**` – Recursos internos do Vite (`@vite/`, `@fs/`, `@id/`, etc.).
+- `/_**` – Recursos internos do servidor (`__vite_ping`, `__manifest`, etc.).
+- Requisições cujo caminho termina com uma extensão de arquivo (recursos estáticos). Se um prefixo de idioma estiver presente em um caminho de recurso estático (ex: `/pt/logo.png`), ele será removido para que o arquivo possa ser servido corretamente.
+
+### Roteamento por domínio
+
+Quando `routing.domains` está configurado nas suas configurações do Intlayer, o middleware lida com o roteamento de idioma entre domínios:
+
+- Uma requisição para `/zh/about` em `intlayer.org` é redirecionada para `https://intlayer.zh/about` quando `domains.zh = "intlayer.zh"`.
+- Uma requisição para `intlayer.zh/about` é reescrita internamente para `/zh/about` para que o parâmetro de rota `[locale]` seja preenchido.
+
+### Proteção contra loops de redirecionamento
+
+O middleware rastreia as contagens de redirecionamento por par `originalUrl → newUrl` dentro de uma janela deslizante de 2 segundos. Mais de 10 redirecionamentos dentro dessa janela retornam uma resposta `500` com um erro descritivo em vez de entrar em loop eterno.
+
+## Nitro / SSR de produção (injeção automática, v9+)
+
+Quando o `intlayerProxy` é usado como um plugin do Vite, ele carrega uma propriedade `.nitro`. O plugin de compilação `nitro/vite` lê esta propriedade e a insere em `nitroConfig.modules`, de modo que o `intlayerNitroHandler` é registrado como um middleware do servidor Nitro automaticamente — nenhuma configuração manual é necessária para o SSR de produção.
+
+O manipulador Nitro usa o modelo de evento Web Fetch API da h3 v2 (não o `fromNodeMiddleware`), por isso é compatível com todas as predefinições do Nitro: Node, Bun, Deno, runtimes edge.
+
+## Aliases depreciados
+
+| Exportação depreciada      | Substituição    |
+| -------------------------- | --------------- |
+| `intlayerMiddleware`       | `intlayerProxy` |
+| `intLayerMiddlewarePlugin` | `intlayerProxy` |

package/docs/pt/releases/v9.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2026-06-14
-updatedAt: 2026-06-23
+updatedAt: 2026-06-25
 title: Novo Intlayer v9 - O que há de novo?
 description: Descubra o que há de novo no Intlayer v9. Apresentando pacotes de compatibilidade drop-in para bibliotecas i18n populares e suporte para Collections, Variants e Dynamic Records.
 keywords:
@@ -252,6 +252,28 @@ Os plugins standalone `intlayerCompiler()` e `intlayerProxy()` permanecem export
 
 ---
 
+## React Native: importações de um único pacote
+
+Em um aplicativo React Native ou Expo, você não precisa mais alternar entre `react-intlayer` e `react-native-intlayer`. O pacote `react-native-intlayer` agora **reexporta toda a API do `react-intlayer`** (hooks, utilitários e os subcaminhos `/format`, `/html` e `/markdown`), e seu `IntlayerProvider` aplica automaticamente os polyfills do React Native.
+
+Importe tudo do único pacote `react-native-intlayer`:
+
+```tsx
+import {
+  IntlayerProvider,
+  useIntlayer,
+  useLocale,
+} from "react-native-intlayer";
+```
+
+```bash
+npm install intlayer react-native-intlayer
+```
+
+> Importar do `react-intlayer` continua funcionando, mas `react-native-intlayer` agora é o ponto de entrada único recomendado para React Native — seu provider inclui os polyfills que o provider do `react-intlayer` (orientado para web) não possui.
+
+---
+
 ## Notas de migração da v8
 
 Se você estiver atualizando da v8, observe que a v9 não inclui breaking changes. Mas aqui estão as principais mudanças:

package/docs/ru/compiler.md

@@ -81,12 +81,15 @@ npm install vite-intlayer
 
 ```ts fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayer, intlayerCompiler } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
   plugins: [
-    intlayer(),
-    intlayerCompiler(), // Добавляет плагин компилятора
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 });
 ```

package/docs/ru/custom_domains.md

@@ -172,10 +172,16 @@ GET intlayer.zh/about
 
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayerProxy()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 

package/docs/ru/custom_url_rewrites.md

@@ -340,10 +340,16 @@ export function middleware(request: NextRequest) {
 
 ```typescript fileName="vite.config.ts"
 import { defineConfig } from "vite";
-import { intlayerProxy } from "vite-intlayer";
+import { intlayer } from "vite-intlayer";
 
 export default defineConfig({
-  plugins: [intlayerProxy()],
+  plugins: [
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
+  ],
 });
 ```
 

package/docs/ru/intlayer_with_analog.md

@@ -207,7 +207,11 @@ import analog from "@analogjs/platform";
 export default defineConfig(() => ({
   plugins: [
     analog(),
-    intlayer(), // Добавьте плагин Intlayer
+    intlayer({
+      proxy: {
+        ignore: (req) => req.url?.startsWith("/api"),
+      },
+    }),
   ],
 }));
 ```

package/docs/ru/intlayer_with_astro.md

@@ -518,6 +518,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Компилятор Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Обновите ваш `vite.config.ts`, чтобы включить плагин `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -527,7 +529,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Добавляет плагин компилятора
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/ru/intlayer_with_astro_lit.md

@@ -591,6 +591,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Компилятор Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Обновите ваш `vite.config.ts`, чтобы включить плагин `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -600,7 +602,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Добавляет плагин компилятора
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/ru/intlayer_with_astro_preact.md

@@ -545,6 +545,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Компилятор Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Обновите ваш `vite.config.ts`, чтобы включить плагин `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -554,7 +556,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Добавляет плагин компилятора
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/ru/intlayer_with_astro_react.md

@@ -542,6 +542,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Компилятор Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Обновите ваш `vite.config.ts`, чтобы включить плагин `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -551,7 +553,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Добавляет плагин компилятора
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/ru/intlayer_with_astro_solid.md

@@ -542,6 +542,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Компилятор Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Обновите ваш `vite.config.ts`, чтобы включить плагин `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -551,7 +553,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Добавляет плагин компилятора
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/ru/intlayer_with_astro_svelte.md

@@ -546,6 +546,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Компилятор Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Обновите ваш `vite.config.ts`, чтобы включить плагин `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -555,7 +557,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Добавляет плагин компилятора
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/ru/intlayer_with_astro_vanilla.md

@@ -520,6 +520,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Компилятор Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Обновите ваш `vite.config.ts`, чтобы включить плагин `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -529,7 +531,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Добавляет плагин компилятора
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/ru/intlayer_with_astro_vue.md

@@ -568,6 +568,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Компилятор Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 Обновите ваш `vite.config.ts`, чтобы включить плагин `intlayerCompiler`:
 
 ```ts fileName="vite.config.ts"
@@ -577,7 +579,7 @@ import { intlayer, intlayerCompiler } from "vite-intlayer";
 export default defineConfig({
   plugins: [
     intlayer(),
-    intlayerCompiler(), // Добавляет плагин компилятора
+    intlayerCompiler(), // Adds the compiler plugin
   ],
 });
 ```

package/docs/ru/intlayer_with_lynx+react.md

@@ -223,6 +223,8 @@ if (import.meta.webpackHot) {
 Создайте файлы **объявления контента** в любом месте вашего проекта (обычно в `src/`), используя любой из форматов расширений, поддерживаемых Intlayer:
 
 - `.content.json`
+- `.content.jsonc`
+- `.content.json5`
 - `.content.ts`
 - `.content.tsx`
 - `.content.js`
@@ -230,7 +232,10 @@ if (import.meta.webpackHot) {
 - `.content.mjs`
 - `.content.mjx`
 - `.content.cjs`
-- `.content.cjx`
+- `.content.md`
+- `.content.mdx`
+- `.content.yaml`
+- `.content.yml`
 - и т.д.
 
 Пример:

package/docs/ru/intlayer_with_nextjs_16.md

@@ -997,6 +997,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Компилятор Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 ```bash packageManager="npm"
 npm install @intlayer/babel --save-dev
 ```

package/docs/ru/intlayer_with_nextjs_compiler.md

@@ -583,6 +583,8 @@ bun x intlayer extract
  </Tab>
  <Tab value='Компилятор Babel'>
 
+> Since v9, the `intlayerCompiler` is included in the `intlayer` plugin. So you don't need to add it manually.
+
 ```bash packageManager="npm"
 npm install @intlayer/babel --save-dev
 ```