@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.10

package/docs/pt/benchmark/tanstack.md

@@ -124,6 +124,28 @@ Comparamos **quatro estratégias de carregamento**:
 - **Scoped static**: Mantém o código organizado (separação lógica) sem requisitos complexos de rede extras.
 - **Scoped dynamic**: Melhor abordagem para _code splitting_ e desempenho. Minimiza a memória carregando apenas o que a visualização atual e a localidade ativa precisam.
 
+### O que medi:
+
+Executei o mesmo aplicativo multilíngue em um navegador real para cada stack, depois anotei o que realmente aparecia na rede e quanto tempo levava. Os tamanhos são relatados **após compressão web normal**, porque isso é mais próximo do que as pessoas baixam do que contagens de fonte bruta.
+
+- **Tamanho da biblioteca de internacionalização**: Após bundling, tree-shaking e minificação, o tamanho da biblioteca i18n é o tamanho dos providers (por exemplo, `NextIntlClientProvider`) + código de hooks (por exemplo, `useTranslations`) em um componente vazio. Não inclui o carregamento de arquivos de tradução. Responde o quão caro é a biblioteca antes do seu conteúdo entrar na imagem.
+
+- **JavaScript por página**: Para cada rota de benchmark, quanto script o navegador puxa naquela visita, em média entre as páginas do conjunto (e entre locales onde o relatório as agrupa). Páginas pesadas são páginas lentas.
+
+- **Vazamento de outras locales**: É o conteúdo da mesma página, mas em outro idioma que seria carregado por engano na página auditada. Este conteúdo é desnecessário e deve ser evitado. (por exemplo, conteúdo da página `/fr/about` no pacote da página `/en/about`)
+
+- **Vazamento de outras rotas**: A mesma ideia para **outras telas** no aplicativo: se a cópia delas vem junto quando você abriu apenas uma página. (por exemplo, conteúdo da página `/en/about` no pacote da página `/en/contact`). Uma pontuação alta indica splitting fraco ou pacotes muito amplos.
+
+- **Tamanho médio do pacote de componentes**: Partes comuns da UI são medidas **uma de cada vez** em vez de se esconderem dentro de um número gigante de aplicativo. Mostra se a internacionalização silenciosamente infla componentes cotidianos. Por exemplo, se o seu componente é renderizado novamente, ele carregará todos esses dados da memória. Anexar um JSON gigante a qualquer componente é como conectar um grande armazém de dados não utilizados que desacelerará o desempenho dos seus componentes.
+
+- **Responsividade da mudança de idioma**: Alterno o idioma usando o controle do próprio aplicativo e meço quanto tempo leva até que a página tenha claramente mudado, o que um visitante notaria, não uma micro-etapa de laboratório.
+
+- **Trabalho de renderização após uma mudança de idioma**: Um acompanhamento mais estreito: quanto esforço a interface levou para se redesenhar para o novo idioma uma vez que a mudança está em voo. Útil quando o tempo "sentido" e o custo do framework divergem.
+
+- **Tempo de carregamento inicial da página**: Da navegação até o navegador considerar a página totalmente carregada para os cenários que testei. Bom para comparar inicializações a frio.
+
+- **Tempo de hidratação**: Quando o aplicativo o expõe, quanto tempo o cliente gasta transformando HTML do servidor em algo que você pode realmente clicar. Um travessão nas tabelas significa que essa implementação não forneceu um valor de hidratação confiável neste benchmark.
+
 ## Estrelas do GitHub
 
 As estrelas do GitHub são um forte indicador da popularidade de um projeto, da confiança da comunidade e da relevância a longo prazo. Embora não sejam uma medida direta da qualidade técnica, elas refletem quantos desenvolvedores consideram o projeto útil, acompanham seu progresso e têm probabilidade de adotá-lo. Para estimar o valor de um projeto, as estrelas ajudam a comparar a tração entre as alternativas e fornecem insights sobre o crescimento do ecossistema.

package/docs/pt/cli/ci.md

@@ -140,6 +140,28 @@ steps:
     run: npx intlayer ci fill
 ```
 
+## GitHub Actions Scaffolding
+
+Quando você executa `intlayer init`, o Intlayer detecta seu gerenciador de pacotes (npm, yarn, pnpm ou bun) e cria dois workflows do GitHub Actions em `.github/workflows/`, com comandos que correspondem a esse gerenciador de pacotes:
+
+- **`intlayer-fill.yml`** — Em cada pull request, compila os dicionários e executa `intlayer fill --git-diff --mode complete` para gerar traduções ausentes para os dicionários alterados, depois confirma o resultado de volta ao branch do PR.
+- **`intlayer-test.yml`** — Em cada pull request, compila os dicionários e executa `intlayer test`, falhando a verificação quando traduções de locales obrigatórias estão ausentes.
+
+Os arquivos de workflow existentes nunca são sobrescritos. Para pular o scaffolding inteiramente, execute:
+
+```bash
+npx intlayer init --no-github-actions
+```
+
+### Fornecendo acesso à IA para o workflow de preenchimento
+
+O `intlayer-fill.yml` gerado requer acesso à IA. Duas opções estão disponíveis (configuradas no bloco `env` do workflow):
+
+1. **Sua própria chave de provedor de IA** — Adicione um secret `AI_API_KEY` nas configurações do seu repositório (Settings → Secrets and variables → Actions). O workflow o encaminha via `--provider`, `--model` e `--api-key`.
+2. **Chaves de acesso do Intlayer CMS** — Adicione os secrets `INTLAYER_CLIENT_ID` e `INTLAYER_CLIENT_SECRET` e integre-os na seção `editor` do seu `intlayer.config`. As chaves de acesso do CMS concedem acesso à IA através do backend do Intlayer.
+
+O workflow `intlayer-test.yml` não requer nenhum acesso à IA.
+
 ## Tratamento de erros
 
 - Se `INTLAYER_PROJECT_CREDENTIALS` não estiver definida, o comando sairá com um erro.

package/docs/pt/cli/doc-review.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2024-08-11
-updatedAt: 2025-11-22
+updatedAt: 2026-06-17
 title: Revisar Documento
 description: Aprenda como revisar arquivos de documentação para qualidade, consistência e completude em diferentes locais.
 keywords:
@@ -15,6 +15,10 @@ slugs:
   - concept
   - cli
   - doc-review
+history:
+  - version: 9.0.0
+    date: 2026-06-17
+    changes: "Adicionar opção --log"
 author: aymericzip
 ---
 
@@ -55,8 +59,110 @@ Para a maioria dos casos de uso,
 
 ## Argumentos:
 
-O comando `doc review` aceita os mesmos argumentos que o `doc translate`, permitindo que você revise arquivos de documentação específicos e aplique verificações de qualidade.
+**Opções de lista de arquivos:**
 
-Se você ativou uma das opções do git, o comando revisará apenas a parte dos arquivos que está sendo alterada. O script processará dividindo o arquivo em chunks e revisará cada chunk. Se não houver alterações no chunk, o script o pulará para acelerar o processo de revisão e limitar o custo da API do Provedor de IA.
+- **`--doc-pattern [docPattern...]`**: Padrões glob para corresponder aos arquivos de documentação a serem revisados.
 
-Para uma lista completa de argumentos, consulte a documentação do comando [Translate Document](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/cli/doc-translate.md).
+  > Exemplo: `npx intlayer doc review --doc-pattern "docs/**/*.md" "src/**/*.mdx"`
+
+- **`--excluded-glob-pattern [excludedGlobPattern...]`**: Padrões glob para excluir da revisão.
+
+  > Exemplo: `npx intlayer doc review --excluded-glob-pattern "docs/internal/**"`
+
+- **`--skip-if-modified-before [skipIfModifiedBefore]`**: Pular o arquivo se ele foi modificado antes do tempo especificado.
+  - Pode ser um tempo absoluto como "2025-12-05" (string ou Date)
+  - Pode ser um tempo relativo em ms `1 * 60 * 60 * 1000` (1 hora)
+  - Esta opção verifica o tempo de atualização do arquivo usando o método `fs.stat`. Portanto, pode ser impactada pelo Git ou outras ferramentas que modificam o arquivo.
+
+  > Exemplo: `npx intlayer doc review --skip-if-modified-before "2025-12-05"`
+
+- **`--skip-if-modified-after [skipIfModifiedAfter]`**: Pular o arquivo se ele foi modificado dentro do tempo especificado.
+  - Pode ser um tempo absoluto como "2025-12-05" (string ou Date)
+  - Pode ser um tempo relativo em ms `1 * 60 * 60 * 1000` (1 hora)
+  - Esta opção verifica o tempo de atualização do arquivo usando o método `fs.stat`. Portanto, pode ser impactada pelo Git ou outras ferramentas que modificam o arquivo.
+
+  > Exemplo: `npx intlayer doc review --skip-if-modified-after "2025-12-05"`
+
+- **`--skip-if-exists`**: Pular o arquivo se ele já existir.
+
+  > Exemplo: `npx intlayer doc review --skip-if-exists`
+
+**Opções de modo de revisão:**
+
+- **`--log`**: Modo apenas de registro (log-only). Não traduz com IA; em vez disso, registra os blocos que precisam de atenção (com números de linha e conteúdo) para as localidades base e de destino, a fim de ajudar outro agente a gerar as traduções.
+
+  > Exemplo: `npx intlayer doc review --log`
+
+**Opções de saída da entrada:**
+
+- **`--locales [locales...]`**: Locais de destino para revisar a documentação.
+
+  > Exemplo: `npx intlayer doc review --locales fr es de`
+
+- **`--base-locale [baseLocale]`**: Local de origem (documento base) para comparar.
+
+  > Exemplo: `npx intlayer doc review --base-locale en`
+
+**Opções de processamento de arquivos:**
+
+- **`--nb-simultaneous-file-processed [nbSimultaneousFileProcessed]`**: Número de arquivos para processar simultaneamente para a revisão.
+
+  > Exemplo: `npx intlayer doc review --nb-simultaneous-file-processed 5`
+
+**Opções de IA:**
+
+- **`--model [model]`**: O modelo de IA a ser usado para a revisão (exemplo: `gpt-3.5-turbo`).
+- **`--provider [provider]`**: O provedor de IA a ser usado para a revisão.
+- **`--temperature [temperature]`**: Configuração de temperatura para o modelo de IA.
+- **`--api-key [apiKey]`**: Forneça sua própria chave de API para o serviço de IA.
+- **`--application-context [applicationContext]`**: Forneça contexto adicional para a revisão de IA.
+- **`--data-serialization [dataSerialization]`**: O formato de serialização de dados a ser usado nas funcionalidades de IA do Intlayer. Opções: `json` (padrão, confiável), `toon` (menos tokens, menos consistente).
+- **`--custom-prompt [prompt]`**: Personalize o prompt base usado para a revisão. (Nota: Para a maioria dos casos de uso, a opção `--custom-instructions` é recomendada, pois oferece melhor controle.)
+
+  > Exemplo: `npx intlayer doc review --model deepseek-chat --provider deepseek --temperature 0.5 --api-key sk-1234567890 --application-context "Minha aplicação é uma loja de gatos"`
+
+**Opções de variáveis de ambiente:**
+
+- **`--env`**: Especifica o ambiente (exemplo: `development`, `production`).
+- **`--env-file [envFile]`**: Fornece um arquivo de ambiente personalizado para carregar variáveis.
+- **`--base-dir`**: Especifica o diretório base do projeto.
+- **`--no-cache`**: Desativa o cache.
+
+  > Exemplo: `npx intlayer doc review --base-dir ./docs --env-file .env.production.local`
+
+**Opções de log:**
+
+- **`--verbose`**: Ativa o log detalhado para depuração. (padrão para true usando CLI)
+
+  > Exemplo: `npx intlayer doc review --verbose`
+
+**Opções de instruções personalizadas:**
+
+- **`--custom-instructions [customInstructions]`**: Instruções personalizadas adicionadas ao prompt. Útil para aplicar regras específicas relacionadas à formatação, tradução de URLs, etc.
+
+  > Exemplo: `npx intlayer doc review --custom-instructions "Evite traduzir URLs e mantenha o formato markdown"`
+
+  > Exemplo: `npx intlayer doc review --custom-instructions "$(cat ./instructions.md)"`
+
+**Opções do Git:**
+
+- **`--git-diff`**: Executa apenas em arquivos que incluem alterações da base (padrão `origin/main`) para o branch atual (padrão: `HEAD`).
+- **`--git-diff-base`**: Especifica a referência base para o git diff (padrão `origin/main`).
+- **`--git-diff-current`**: Especifica a referência atual para o git diff (padrão: `HEAD`).
+- **`--uncommitted`**: Inclui alterações não comitadas.
+- **`--unpushed`**: Inclui alterações não enviadas.
+- **`--untracked`**: Inclui arquivos não rastreados.
+
+  > Exemplo: `npx intlayer doc review --git-diff --git-diff-base origin/main --git-diff-current HEAD`
+
+  > Exemplo: `npx intlayer doc review --uncommitted --unpushed --untracked`
+
+> Note que o caminho do arquivo de saída será determinado substituindo os seguintes padrões:
+>
+> - `/{{baseLocale}}/` por `/{{locale}}/` (Unix)
+> - `\{{baseLocale}}\` por `\{{locale}}\` (Windows)
+> - `_{{baseLocale}}.` por `_{{locale}}.`
+> - `{{baseLocale}}_` por `{{locale}}_`
+> - `.{{baseLocaleName}}.` por `.{{localeName}}.`
+>
+> Se o padrão não for encontrado, o arquivo de saída adicionará `.{{locale}}` na extensão do arquivo. `./my/file.md` será revisado e atualizado para `./my/file.fr.md` para o idioma francês.

package/docs/pt/cli/fill.md

@@ -47,6 +47,14 @@ Pontos-chave:
 - Preserva traduções existentes ao não sobrescrevê-las.
 - Processa arquivos, partes e locales em paralelo usando um sistema de fila para aumentar a velocidade.
 
+## Pontos-Chave:
+
+- Divide arquivos JSON grandes em chunks para se manter dentro dos limites da janela de contexto do modelo de IA.
+- Retenta a tradução se o formato de saída estiver incorreto.
+- Incorpora contexto específico da aplicação e do arquivo para melhor precisão na tradução.
+- Preserva traduções existentes sem sobrescrevê-las.
+- Processa arquivos, chunks e locales em paralelo usando um sistema de fila para aumentar a velocidade.
+
 ## Apelidos:
 
 - `npx intlayer dictionaries fill`

package/docs/pt/cli/index.md

@@ -17,7 +17,7 @@ slugs:
   - concept
   - cli
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-11
     changes: "Adicionar comando scan"
   - version: 8.6.4

package/docs/pt/cli/login.md

@@ -78,42 +78,6 @@ bun x intlayer login --cms-url https://intlayer.org
 
 ### Opções de Configuração
 
-Você também pode usar opções comuns de configuração:
-
-- `--env-file <path>`: Caminho para o arquivo de ambiente
-- `-e, --env <env>`: Ambiente de execução
-- `--base-dir <dir>`: Diretório base do projeto
-- `--verbose`: Habilitar saída detalhada (padrão: true)
-- `--prefix <prefix>`: Prefixo para logs
-
-## Como Funciona
-
-1. **Inicialização do servidor local**: O comando inicia um servidor HTTP local em uma porta aleatória para receber credenciais do CMS
-
-Especifique a URL do Intlayer CMS para se conectar durante a autenticação.
-
-- **Tipo**: `string`
-- **Padrão**: O valor configurado em `intlayer.config.*` ou `https://intlayer.org`
-- **Exemplo**:
-
-```bash packageManager="npm"
-npx intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="yarn"
-yarn intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="pnpm"
-pnpm intlayer login --cms-url https://intlayer.org
-```
-
-```bash packageManager="bun"
-bun x intlayer login --cms-url https://intlayer.org
-```
-
-### Opções de Configuração
-
 Você também pode usar opções de configuração comuns:
 
 - `--env-file <path>`: Caminho para o arquivo de ambiente

package/docs/pt/cli/scan.md

@@ -18,7 +18,7 @@ slugs:
   - cli
   - scan
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-11
     changes: "Adicionar comando scan"
 author: aymericzip

package/docs/pt/compat/i18n-js.md

@@ -0,0 +1,44 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrar de i18n-js para Intlayer"
+description: "Aprenda como migrar sua aplicação de i18n-js para Intlayer usando o adaptador de compatibilidade."
+keywords:
+  - i18n-js
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - i18n-js
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrar de i18n-js para Intlayer
+
+Fazer a transição da biblioteca `i18n-js` para Intlayer é uma migração altamente otimizada projetada para transferir grandes configurações de traduções para o sistema de resolução de arquivos estruturado do Intlayer.
+
+## O que fazer
+
+Execute o seguinte comando de configuração em seu repositório:
+
+```bash
+npx intlayer init
+```
+
+Com `intlayer.config.ts` preparado, você pode adicionar o alias do Intlayer à configuração do seu bundler para que qualquer importação de `i18n-js` aponte para o pacote de compatibilidade `@intlayer/i18n-js`.
+
+## O que faz sob o capô
+
+`i18n-js` acessa namespaces através de expressões como `i18n.t('scope.key', {name})` juntamente com fallbacks de locale e mapeamentos de pluralização específicos.
+
+Sob o capô:
+
+- **Interpolação:** O adaptador de compatibilidade analisa facilmente mapeamentos `%{name}` em seu valor de dicionário de runtime alvo.
+- **Pluralização:** Substitui subchaves `one/other` e as mapeia contra os poderosos mecanismos de pluralização subjacentes do Intlayer (`Intl.PluralRules`), abstraindo mapeamentos manuais.
+- **Locales:** Em vez de carregar payloads monolíticos de linguagem no bootstrap, dicionários são servidos de forma otimizada com base na configuração de contexto atual via configuração nativa do Intlayer.

package/docs/pt/compat/i18next.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrar do i18next para Intlayer"
+description: "Aprenda como migrar sua aplicação Vanilla JS/TS do i18next para Intlayer usando o adaptador de compatibilidade."
+keywords:
+  - i18next
+  - vanilla
+  - javascript
+  - typescript
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrar de i18next para Intlayer
+
+Para um tutorial passo a passo detalhado, consulte nosso [i18next Migration Guide](../migration_from_i18next_to_intlayer.md) completo.
+
+Intlayer replica perfeitamente as características de runtime do núcleo do `i18next`. Utilizando o pacote de compatibilidade, suas aplicações Vanilla ou módulos internos podem continuar aproveitando a sintaxe familiar.
+
+## O que fazer
+
+Para começar, inicialize o Intlayer no seu projeto:
+
+```bash
+npx intlayer init
+```
+
+Se você está usando Vite, inclua o plugin do Intlayer para rotear importações para `@intlayer/i18next`:
+
+```typescript fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { i18nextVitePlugin } from "@intlayer/i18next/plugin";
+
+export default defineConfig({
+  plugins: [i18nextVitePlugin()],
+});
+```
+
+## O que funciona nos bastidores
+
+O `i18nextVitePlugin` cria aliases para importações de `i18next` para `@intlayer/i18next`, evitando inchamento de bundle por inclusões de arquivos JSON.
+
+Nos bastidores:
+
+- **Configuração de instância:** `createInstance` analisa e aplica corretamente fallbacks de namespace enquanto aproveita o pipeline de compilação do Intlayer para recuperação de dicionários.
+- **Interpolação:** Suporte nativo para substituições `{{name}}` e aninhamento `$t(key)` recursivamente.
+- **Contexto e plurais:** Identifica e resolve formatos de sufixo como `key_male` e `key_one`/`key_other` avaliando contra `Intl.PluralRules` padrão.
+- **Retorno de objetos:** O modo `returnObjects: true` extrai com segurança árvores de dicionários do Intlayer.

package/docs/pt/compat/index.md

@@ -0,0 +1,51 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Adaptadores de Compatibilidade Intlayer"
+description: "Migre sua solução i18n existente para Intlayer sem atrito usando adaptadores de compatibilidade."
+keywords:
+  - compat
+  - migration
+  - internationalization
+  - i18n
+  - Intlayer
+slugs:
+  - doc
+  - compatibility
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Adaptadores de Compatibilidade Intlayer
+
+Migrar uma aplicação grande para uma nova biblioteca de internacionalização pode ser intimidante. Para facilitar essa transição, Intlayer fornece **adaptadores de compatibilidade** para as bibliotecas i18n mais populares do ecossistema.
+
+Esses pacotes de adaptadores expõem a **mesma API pública exata** das suas bibliotecas i18n existentes, mas delegam todo o trabalho de tradução para Intlayer em tempo de execução.
+
+## Como funciona
+
+Quando você usa um compat adapter, não precisa reescrever as importações da sua aplicação ou mudar como você usa seus hooks e componentes de tradução. Em vez disso, os plugins bundler do Intlayer fazem automaticamente um alias das suas importações existentes para os pacotes compat do Intlayer.
+
+Por exemplo, um desenvolvedor substitui `import { useTranslation } from 'react-i18next'` por `import { useTranslation } from '@intlayer/react-i18next'` (feito automaticamente via plugin bundler), e a aplicação continua funcionando com traduções agora servidas a partir dos dicionários do Intlayer. As chaves também são tipadas contra seus dicionários do Intlayer!
+
+## Adaptadores Compat Disponíveis
+
+Escolha sua biblioteca existente abaixo para ver como migrar perfeitamente:
+
+- [Vue I18n](./vue-i18n.md)
+- [Transloco](./transloco.md)
+- [React Intl](./react-intl.md)
+- [Svelte I18n](./svelte-i18n.md)
+- [React i18next](./react-i18next.md)
+- [Polyglot.js](./polyglot.md)
+- [NuxtJS I18n](./nuxtjs-i18n.md)
+- [NGX Translate](./ngx-translate.md)
+- [Next Translate](./next-translate.md)
+- [Next Intl](./next-intl.md)
+- [Next i18next](./next-i18next.md)
+- [i18next](./i18next.md)
+- [Lingui](./lingui.md)
+- [I18n-js](./i18n-js.md)

package/docs/pt/compat/lingui.md

@@ -0,0 +1,44 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrar do Lingui para Intlayer"
+description: "Aprenda como migrar sua aplicação do Lingui para Intlayer usando o adaptador de compatibilidade."
+keywords:
+  - lingui
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - lingui
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrar do Lingui para Intlayer
+
+Se seu projeto atualmente depende da compilação baseada em macros do Lingui, a transição para Intlayer permite que você mantenha seus poderosos fluxos de trabalho de macros enquanto os respalda nativamente com a estratégia de compilação JSON do Intlayer.
+
+## O que fazer
+
+Para começar, inicialize o Intlayer no seu projeto:
+
+```bash
+npx intlayer init
+```
+
+Isso cria seu `intlayer.config.ts`. Certifique-se de manter `@lingui/babel-plugin-lingui-macro` / `@lingui/swc-plugin` na sua etapa de build para executar _antes_ do compilador Intlayer. Em seguida, use o alias do plugin bundler para rotear `@lingui/core` e `@lingui/react` para `@intlayer/lingui`.
+
+## O que acontece nos bastidores
+
+Lingui utiliza macros (como `` t`Hello ${name}` `` e `<Trans>`) que são compiladas em chamadas de tempo de execução como `i18n._(id, values)`.
+
+Nos bastidores:
+
+- **Macros:** Elas são compiladas precisamente como antes, garantindo nenhuma interrupção na sua sintaxe de origem.
+- **Tradução em tempo de execução:** O `i18n._()` com alias utiliza dicionários Intlayer. IDs explicitamente nomeados e IDs hash são totalmente mapeados usando plugins de sincronização `.po` do Intlayer para agregar e remover chaves com segurança.
+- **Capacidades ICU:** O suporte para pluralização, seleção e variantes ICU permanece robusto devido ao parser ICU unificado do Intlayer, garantindo resultados de renderização idênticos.

package/docs/pt/compat/next-i18next.md

@@ -0,0 +1,57 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrar de next-i18next para Intlayer"
+description: "Aprenda como migrar sua aplicação Next.js de next-i18next para Intlayer usando o adaptador de compatibilidade."
+keywords:
+  - next-i18next
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-i18next
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrar de next-i18next para Intlayer
+
+Para um tutorial completo e detalhado passo a passo, consulte nosso [Guia de Migração next-i18next](../migration_from_next-i18next_to_intlayer.md).
+
+O Intlayer manipula todas as implementações do Next.js Pages Router e App Router de forma transparente. Usar o adapter permite que você migre sua implementação de `next-i18next` sem reescrever nenhum código.
+
+## O que fazer
+
+Para começar, execute:
+
+```bash
+npx intlayer init
+```
+
+Isso cria o arquivo de configuração necessário do Intlayer. Para integrar o Intlayer nos bastidores, atualize seu `next.config.ts`:
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
+
+const withIntlayer = createNextI18nPlugin();
+
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+## O que faz sob o capô
+
+O `createNextI18nPlugin` compõe o comportamento nativo do Next.js junto com o plugin central `next-intlayer`, injetando todos os aliases Webpack/Turbopack necessários para `next-i18next`, `react-i18next`, e `i18next`.
+
+Sob o capô:
+
+- **`serverSideTranslations` & `appWithTranslation`:** Agora funcionam como wrappers para os loaders internos do Intlayer, contornando a injeção estática de grandes JSONs.
+- **Client hooks:** Delega imediatamente para `@intlayer/react-i18next` mantendo todas as funcionalidades de formatação, plurais e namespaces aninhados.

package/docs/pt/compat/next-intl.md

@@ -0,0 +1,59 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrar de next-intl para Intlayer"
+description: "Aprenda como migrar sua aplicação Next.js de next-intl para Intlayer usando o adaptador de compatibilidade."
+keywords:
+  - next-intl
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-intl
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrar de next-intl para Intlayer
+
+Para um tutorial completo e detalhado passo a passo, consulte nosso [Guia de Migração next-intl](../migration_from_next-intl_to_intlayer.md).
+
+Migrar de `next-intl` para Intlayer permite que você mantenha seu roteamento de aplicação e sintaxe completamente intactos.
+
+## O que fazer
+
+Execute o seguinte comando no seu repositório:
+
+```bash
+npx intlayer init
+```
+
+Isso criará um `intlayer.config.ts`. No seu `next.config.ts`, use o wrapper do plugin para injetar perfeitamente os aliases `next-intl` em direção a `@intlayer/next-intl`.
+
+```typescript fileName="next.config.ts"
+import type { NextConfig } from "next";
+import { createNextIntlPlugin } from "@intlayer/next-intl/plugin";
+
+const withIntlayer = createNextIntlPlugin();
+
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+## O que faz nos bastidores
+
+O wrapper do bundler substitui traduções, mas **mantém os recursos de `next-intl/navigation` intactos** (p.ex. `Link`, `redirect`, `usePathname`).
+
+Nos bastidores:
+
+- **ICU runtime:** Plurais (`=0`, `one`, `other`), select/selectordinal, argumentos `#` e argumentos formatados (`{ts, date, long}`) funcionam corretamente usando o resolver compartilhado `resolveMessage(..., 'icu')`.
+- **`useTranslations()` & `getTranslations()`:** As chamadas de escopo simples extraem o primeiro segmento de chave como o identificador de dicionário correto. Namespaces aninhados se dividem graciosamente em caminhos de dicionário e prefixos.
+- **Rich formatting:** Tanto `t.rich()` quanto `t.markup()` são totalmente implementados nativamente, convertendo nós semelhantes a HTML em chunks React renderizados.
+- **`useFormatter`:** `relativeTime`, `list`, `dateTimeRange` e formatos nomeados da configuração fazem ponte para os formatadores nativos `Intl` principais.

package/docs/pt/compat/next-translate.md

@@ -0,0 +1,45 @@
+---
+createdAt: 2026-06-13
+updatedAt: 2026-06-13
+title: "Migrar do Next Translate para Intlayer"
+description: "Aprenda como migrar sua aplicação Next.js do next-translate para Intlayer usando o adaptador de compatibilidade."
+keywords:
+  - next-translate
+  - nextjs
+  - intlayer
+  - migration
+  - compat
+slugs:
+  - doc
+  - compatibility
+  - next-translate
+history:
+  - version: 9.0.0
+    date: 2026-06-13
+    changes: "Init history"
+author: aymericzip
+---
+
+# Migrar do Next Translate para o Intlayer
+
+Migrar de `next-translate` para Intlayer é uma substituição praticamente imediata que mantém sua sintaxe e tags existentes.
+
+## O que fazer
+
+Initialize Intlayer in your project:
+
+```bash
+npx intlayer init
+```
+
+O CLI irá scaffolding sua configuração. Você pode então aplicar o plugin Intlayer no seu `next.config.ts`, que injeta aliases de subpath em build-time mapeando `next-translate/useTranslation` para `@intlayer/next-translate`.
+
+## O que faz nos bastidores
+
+`next-translate` fornece hooks como `useTranslation('ns')`, `t('ns:key.path')`, e o componente `<Trans>`.
+
+Nos bastidores:
+
+- **Interpolação & Plurais:** Depende fortemente do comportamento do adaptador `react-i18next`. Tratados dinamicamente são placeholders `{{var}}` e pluralização mapeada a partir de sufixos como `key_0`, `key_one`, e `key_other`.
+- **Componente `<Trans>`:** Diretamente suportado para análise de tags semelhantes a HTML juntamente com uma prop `components` baseada em array.
+- **Namespaces:** Alias de subpath garante que sua `useTranslation` referencia os namespaces corretos do dicionário interno sem modificação manual.