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

package/docs/pt/autoFill.md

@@ -16,6 +16,9 @@ slugs:
   - concept
   - auto-fill
 history:
+  - version: 7.0.0
+    date: 2025-10-23
+    changes: "Renomear `fill` para `fill` e atualizar comportamento"
   - version: 6.0.0
     date: 2025-09-20
     changes: "Adicionada configuração global"
@@ -28,11 +31,77 @@ history:
 author: aymericzip
 ---
 
-# Traduções de Arquivos de Declaração de Conteúdo com Preenchimento Automático
+# Traduzir Traduções de Arquivo de Declaração de Conteúdo
 
 **Arquivos de declaração de conteúdo com preenchimento automático** são uma forma de acelerar seu fluxo de trabalho de desenvolvimento.
 
-O mecanismo de preenchimento automático funciona através de uma relação _mestre-escravo_ entre arquivos de declaração de conteúdo. Quando o arquivo principal (mestre) é atualizado, o Intlayer aplicará automaticamente essas alterações aos arquivos de declaração derivados (preenchidos automaticamente).
+## Entender o comportamento
+
+O comando `fill` inclui dois modos:
+
+- **Completo**: Preenche automaticamente todo o conteúdo faltante para cada localidade e edita o arquivo atual ou outro arquivo se especificado. Ou seja, o modo completo irá pular a tradução do conteúdo existente, se já foi traduzido.
+- **Revisão**: Preenche automaticamente **todo** o conteúdo para cada localidade e gera para um arquivo específico ou outro arquivo se especificado.
+
+O comando fill irá processar todos os seus arquivos de declaração de conteúdo de localidade. Ou seja, não irá processar seu conteúdo remoto do CMS. O CMS inclui seu próprio gerenciamento de traduções.
+Se você usar plugins como `@intlayer/sync-json-plugin`, o Intlayer transformará os arquivos JSON em arquivos de declaração de conteúdo por localidade. Ou seja, eles serão processados pelo comando `fill`.
+
+Os novos arquivos gerados incluem uma instrução `filled` como metadados do dicionário. Esta instrução será usada pelo Intlayer para saber se o arquivo foi preenchido automaticamente ou não e pular este arquivo de ser traduzido novamente se presente.
+
+O Intlayer também considerará a seguinte instrução para preenchimento automático:
+
+- Do seu `.content.{ts|js|json}` → instrução `fill`
+- Do seu arquivo de configuração `.intlayer.config.ts` → instrução `dictionary.fill`
+- Será definido como `true` por padrão caso contrário
+
+Para arquivos de declaração de conteúdo por localidade, a instrução `true` será substituída por `./{{fileName}}.fill.content.json`. Isto é porque um arquivo de declaração de conteúdo por localidade não pode receber conteúdo localizado adicional. Portanto, irá gerar um novo arquivo para não sobrescrever o arquivo existente.
+
+## Comportamento Padrão
+
+Por padrão, `fill` é definido como `true` globalmente, o que significa que o Intlayer irá preencher automaticamente todos os arquivos de conteúdo e editar o arquivo em si. Este comportamento pode ser customizado de várias formas:
+
+### Opções de Configuração Global
+
+1. **`fill: true` (padrão)** - Preenche automaticamente todas as localidades e edita o arquivo atual
+2. **`fill: false`** - Desabilita preenchimento automático para este arquivo de conteúdo
+3. **`fill: "./relative/path/to/file"`** - Cria/atualiza o arquivo especificado sem editar o arquivo atual apontando para um caminho relativo resolvido com base na localização do arquivo atual
+4. **`fill: "/absolute/path/to/file"`** - Cria/atualiza o arquivo especificado sem editar o arquivo atual apontando para um caminho relativo resolvido com base na localização do diretório base (campo `baseDir` no arquivo de configuração `.intlayer.config.ts`)
+5. **`fill: "C:\\absolute\path\to\file"`** - Cria/atualiza o arquivo especificado sem editar o arquivo atual apontando para um caminho absoluto resolvido com base no seu sistema operacional
+6. **`fill: { [key in Locales]?: string }`** - Cria/atualiza o arquivo especificado para cada localidade
+
+### Mudanças de Comportamento v7
+
+Na v7, o comportamento do comando `fill` foi atualizado:
+
+- **`fill: true`** - Reescreve o arquivo atual com conteúdo preenchido para todas as localidades
+- **`fill: "path/to/file"`** - Preenche o arquivo especificado sem modificar o arquivo atual
+- **`fill: false`** - Desabilita preenchimento automático completamente
+
+Ao usar uma opção de caminho para escrever em outro arquivo, o mecanismo de preenchimento funciona através de uma relação _mestre-escravo_ entre arquivos de declaração de conteúdo. O arquivo principal (mestre) serve como fonte da verdade e, quando é atualizado, o Intlayer aplicará automaticamente essas alterações aos arquivos de declaração derivados (preenchidos) especificados pelo caminho.
+
+### Customização Por Localidade
+
+Você também pode customizar o comportamento para cada localidade usando um objeto:
+
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  content: {
+    internationalization: {
+      locales: [Locales.ENGLISH, Locales.FRENCH, Locales.POLISH],
+      defaultLocale: Locales.ENGLISH,
+      requiredLocales: [Locales.ENGLISH], // Recomendado para evitar a propriedade 'pl' está faltando no tipo '{ en: string; xxx } na sua função t
+    },
+  },
+  dictionary: {
+    fill: {
+      en: true, // Preenche e edita o arquivo atual para Inglês
+      fr: "./translations/fr.json", // Cria arquivo separado para Francês
+      es: false, // Desabilita preenchimento para Espanhol
+    },
+  },
+};
+```
+
+Isto permite que você tenha comportamentos de preenchimento diferentes para diferentes localidades dentro do mesmo projeto.
 
 ```ts fileName="src/components/example/example.content.ts"
 import { Locales, type Dictionary } from "intlayer";
@@ -40,7 +109,7 @@ import { Locales, type Dictionary } from "intlayer";
 const exampleContent = {
   key: "example",
   locale: Locales.ENGLISH,
-  autoFill: "./example.content.json",
+  fill: "./example.content.json",
   content: {
     contentExample: "Este é um exemplo de conteúdo",
   },
@@ -50,7 +119,7 @@ const exampleContent = {
 export default exampleContent;
 ```
 
-Aqui está um [arquivo de declaração de conteúdo por localidade](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/per_locale_file.md) usando a instrução `autoFill`.
+Aqui está um [arquivo de declaração de conteúdo por localidade](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/per_locale_file.md) usando a instrução `fill`.
 
 Então, quando você executar o seguinte comando:
 
@@ -89,6 +158,40 @@ O Intlayer irá gerar automaticamente o arquivo de declaração derivado em `src
 
 Posteriormente, ambos os arquivos de declaração serão mesclados em um único dicionário, acessível usando o hook padrão `useIntlayer("example")` (react) / composable (vue).
 
+## Configuração Global
+
+Você pode configurar a configuração de preenchimento automático global no arquivo `intlayer.config.ts`.
+
+```ts fileName="intlayer.config.ts"
+import { type IntlayerConfig, Locales } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+  },
+  dictionary: {
+    // Gera automaticamente traduções faltantes para todos os dicionários
+    fill: "./{{fileName}}Filled.content.ts",
+    //
+    // fill: "/messages/{{locale}}/{{key}}/{{fileName}}.content.json",
+    //
+    // fill: true, // gera automaticamente traduções faltantes para todos os dicionários como usando "./{{fileName}}.content.json"
+    //
+    // fill: {
+    //   en: "./{{fileName}}.en.content.json",
+    //   fr: "./{{fileName}}.fr.content.json",
+    //   es: "./{{fileName}}.es.content.json",
+    // },
+  },
+};
+
+export default config;
+```
+
+Você ainda pode ajustar melhor por dicionário usando o campo `fill` em arquivos de conteúdo. O Intlayer irá primeiro considerar a configuração por dicionário e então voltar para a configuração global.
+
 ## Formato do Arquivo Preenchido Automaticamente
 
 O formato recomendado para arquivos de declaração preenchidos automaticamente é **JSON**, que ajuda a evitar restrições de formatação. No entanto, o Intlayer também suporta `.ts`, `.js`, `.mjs`, `.cjs` e outros formatos.
@@ -96,7 +199,7 @@ O formato recomendado para arquivos de declaração preenchidos automaticamente
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
   key: "example",
-  autoFill: "./example.filled.content.ts",
+  fill: "./example.filled.content.ts",
   content: {
     // Seu conteúdo
   },
@@ -116,12 +219,12 @@ src/components/example/example.filled.content.ts
 
 ## Caminhos Absolutos
 
-O campo `autoFill` também suporta caminhos absolutos.
+O campo `fill` também suporta caminhos absolutos.
 
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
   key: "example",
-  autoFill: "/messages/example.content.json",
+  fill: "/messages/example.content.json",
   content: {
     // Seu conteúdo
   },
@@ -136,12 +239,12 @@ Isso irá gerar o arquivo em:
 
 ## Geração Automática de Arquivos de Declaração de Conteúdo Por Localidade
 
-O campo `autoFill` também suporta a geração de arquivos de declaração de conteúdo **por localidade**.
+O campo `fill` também suporta a geração de arquivos de declaração de conteúdo **por localidade**.
 
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
   key: "example",
-  autoFill: {
+  fill: {
     fr: "./example.fr.content.json",
     es: "./example.es.content.json",
   },
@@ -160,12 +263,12 @@ Isso irá gerar dois arquivos separados:
 
 ## Filtrar Autofill para Localidade Específica
 
-Usar um objeto para o campo `autoFill` permite aplicar filtros e gerar apenas arquivos de localidades específicas.
+Usar um objeto para o campo `fill` permite aplicar filtros e gerar apenas arquivos de localidades específicas.
 
 ```ts fileName="src/components/example/example.content.ts"
 const exampleContent = {
   key: "example",
-  autoFill: {
+  fill: {
     fr: "./example.fr.content.json",
   },
   content: {
@@ -178,7 +281,7 @@ Isso irá gerar apenas o arquivo de tradução em francês.
 
 ## Variáveis de Caminho
 
-Você pode usar variáveis dentro do caminho `autoFill` para resolver dinamicamente os caminhos de destino para os arquivos gerados.
+Você pode usar variáveis dentro do caminho `fill` para resolver dinamicamente os caminhos de destino para os arquivos gerados.
 
 **Variáveis disponíveis:**
 
@@ -189,7 +292,7 @@ Você pode usar variáveis dentro do caminho `autoFill` para resolver dinamicame
 ```ts fileName="src/components/example/index.content.ts"
 const exampleContent = {
   key: "example",
-  autoFill: "/messages/{{locale}}/{{key}}.content.json",
+  fill: "/messages/{{locale}}/{{key}}.content.json",
   content: {
     // Seu conteúdo
   },
@@ -204,7 +307,7 @@ Isso irá gerar:
 ```ts fileName="src/components/example/index.content.ts"
 const exampleContent = {
   key: "example",
-  autoFill: "./{{fileName}}.content.json",
+  fill: "./{{fileName}}.content.json",
   content: {
     // Seu conteúdo
   },

package/docs/pt/benchmark/index.md

@@ -26,8 +26,8 @@ O Benchmark Bloom é uma suíte de benchmarks de desempenho que mede o impacto r
 
 Abaixo estão os relatórios detalhados e a documentação técnica de cada framework:
 
-- [**Next.js Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/nextjs.md)
-- [**TanStack Start Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/tanstack.md)
-- [**Vue Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/vue.md)
-- [**Solid Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/solid.md)
-- [**Svelte Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/benchmark/svelte.md)
+- [**Next.js Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/benchmark/nextjs.md)
+- [**TanStack Start Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/benchmark/tanstack.md)
+- [**Vue Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/benchmark/vue.md)
+- [**Solid Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/benchmark/solid.md)
+- [**Svelte Benchmark Report**](https://github.com/aymericzip/intlayer/blob/main/docs/docs/pt/benchmark/svelte.md)

package/docs/pt/benchmark/solid.md

@@ -118,6 +118,28 @@ Comparamos **quatro estratégias de carregamento**:
 - **Scoped static**: Mantém o código organizado (separação lógica) sem requisições de rede extras complexas.
 - **Scoped dynamic**: Melhor abordagem para _code splitting_ e desempenho. Minimiza a memória carregando apenas o que a view atual e o local ativo precisam.
 
+### O que medi:
+
+Executei o mesmo aplicativo multilíngue em um navegador real para cada stack e anotei o que realmente aparecia na rede e quanto tempo levava. Os tamanhos são relatados **após compressão web normal**, porque isso se aproxima mais do que as pessoas fazem download do que contagens de código-fonte bruto.
+
+- **Tamanho da biblioteca de internacionalização**: Após bundling, tree-shaking e minificação, o tamanho da biblioteca i18n é o tamanho dos providers + código de hooks/primitives em um componente vazio. Não inclui o carregamento de arquivos de tradução. Responde o quão caro é a biblioteca antes de seu conteúdo entrar na história.
+
+- **JavaScript por página**: Para cada rota de benchmark, quanto script o navegador extrai para essa visita, em média nas páginas do conjunto (e entre idiomas onde o relatório os agrega). Páginas pesadas são páginas lentas.
+
+- **Vazamento de outros idiomas**: É 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. (ex. conteúdo da página `/fr/about` no bundle da página `/en/about`)
+
+- **Vazamento de outras rotas**: A mesma ideia para **outras telas** no aplicativo: se sua cópia está viajando junto quando você abriu apenas uma página. (ex. conteúdo da página `/en/about` no bundle da página `/en/contact`). Uma pontuação alta sugere divisão fraca ou bundles muito amplos.
+
+- **Tamanho médio do bundle do componente**: Peças de UI comuns são medidas **uma de cada vez** em vez de se esconder dentro de um número gigante de aplicativo. Mostra se a internacionalização silenciosamente infla componentes cotidianos. Por exemplo, se seu componente é renderizado novamente, ele carregará todos esses dados da memória. Anexar um JSON gigante a qualquer componente é como conectar um grande armazenamento de dados não utilizados que desacelerará o desempenho de seus componentes.
+
+- **Responsividade da troca de idioma**: Mudo o idioma usando o controle do próprio aplicativo e cronometro quanto tempo leva até a página ter claramente trocado, o que um visitante notaria, não um micro-passo 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 redesenhar o novo idioma uma vez que a troca está em andamento. Útil quando o tempo "sentido" e o custo do framework divergem.
+
+- **Tempo de carregamento da página inicial**: Da navegação até o navegador considerar a página totalmente carregada para os cenários que testei. Bom para comparar inícios frios.
+
+- **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 a implementação não forneceu uma figura 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/benchmark/svelte.md

@@ -116,6 +116,28 @@ Comparamos **quatro estratégias de carregamento**:
 - **Scoped static**: Mantém o código organizado (separação lógica) sem requisições de rede extras complexas.
 - **Scoped dynamic**: Melhor abordagem para _code splitting_ e desempenho. Minimiza a memória carregando apenas o que a view atual e o local ativo precisam.
 
+### O que medi:
+
+Executei o mesmo aplicativo multilíngue em um navegador real para cada stack, depois anotei o que realmente apareceu na rede e quanto tempo levou. Os tamanhos são reportados **após a compressão web normal**, porque isso é mais próximo do que as pessoas baixam do que contagens de código-fonte bruto.
+
+- **Tamanho da biblioteca de internacionalização**: Após bundling, tree-shaking e minificação, o tamanho da biblioteca i18n é o tamanho do código de providers + stores em um componente vazio. Não inclui o carregamento de arquivos de tradução. Responde o quanto a biblioteca custa antes do seu conteúdo entrar em cena.
+
+- **JavaScript por página**: Para cada rota de benchmark, quanto script o navegador puxa nessa visita, em média nas páginas do conjunto (e entre locales onde o relatório as agrupa). Páginas pesadas são páginas lentas.
+
+- **Vazamento de outros 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. (ex: conteúdo da página `/fr/about` no bundle da página `/en/about`)
+
+- **Vazamento de outras rotas**: A mesma ideia para **outras telas** do app: se a sua cópia vem junto quando você apenas abriu uma página. (ex: conteúdo da página `/en/about` no bundle da página `/en/contact`). Uma pontuação alta sugere splitting fraco ou bundles muito amplos.
+
+- **Tamanho médio do bundle do componente**: Peças comuns da UI são medidas **uma de cada vez** em vez de se esconder dentro de um número gigante do app. Mostra se a internacionalização silenciosamente inflaciona componentes cotidianos. Por exemplo, se seu componente fizer rerender, carregará todos esses dados da memória. Anexar um JSON gigante a qualquer componente é como conectar um grande armazenamento de dados não utilizados que desacelerará o desempenho de seus componentes.
+
+- **Responsividade da troca de idioma**: Eu troco o idioma usando o controle do próprio app e cronometro quanto tempo leva até a página ter claramente mudado, o que um visitante notaria, não um micro-passo de laboratório.
+
+- **Trabalho de renderização após uma troca de idioma**: Um follow-up mais estreito: quanto esforço a interface levou para repintar para o novo idioma uma vez que a troca está em andamento. Ú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 cold starts.
+
+- **Tempo de hidratação**: Quando o app o expõe, quanto tempo o cliente gasta transformando HTML do servidor em algo que você realmente pode clicar. Um travessão nas tabelas significa que essa implementação não forneceu um número 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/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/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/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/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.